
Set a generated media download's filename in your own authorized delivery response using Content-Disposition. Derive the extension from validated media type and use a controlled filename, rather than copying a prompt or customer-supplied string into a response header. Changing a filename is a delivery action, not a new Imagild generation request.
Key Takeaways
- The application proxy owns its download response headers.
- Use a known extension for validated PNG, JPEG, WebP, or MP4 bytes.
- Keep names free of path separators, control characters, and untrusted header content.
Separate the browser label from the generated file
A result card can display a friendly title such as “Autumn campaign hero.” That title does not have to become the exact transport filename.
For a stable default, combine a controlled prefix with a validated task identifier and an allowed extension. This avoids treating a prompt, original upload filename, or account name as trusted HTTP syntax.
MDN's Content-Disposition reference describes inline versus attachment behavior and filename parameters. The header is an application delivery decision; it is not an accepted filename field in Imagild's strict generation JSON.
Choose the extension from the approved representation
| Validated representation | Suggested extension |
|---|---|
image/png | .png |
image/jpeg | .jpg |
image/webp | .webp |
video/mp4 | .mp4 |
| JSON or HTML error | Do not publish as a media attachment |
Validate status, type, and actual media bytes before selecting a download extension. A server's declared Content-Type is useful, but a mislabeled body still needs detection in the media validation stage.
The API console describes authenticated content delivery. The upstream output_url is private, so the proxy must first authorize the application user and the owned asset.
Generate a conservative attachment header
This JavaScript helper returns a header value after media validation. It does not implement authentication, retrieve the content, or approve the file.
function mediaAttachment(taskId, contentType) {
const uuid = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
if (typeof taskId !== "string" || taskId.length !== 36 || !uuid.test(taskId)) {
throw new Error("Invalid task identifier");
}
if (typeof contentType !== "string") throw new Error("Invalid content type");
const extensions = {
"image/png": "png", "image/jpeg": "jpg",
"image/webp": "webp", "video/mp4": "mp4"
};
const type = contentType.split(";")[0].trim().toLowerCase();
if (!Object.hasOwn(extensions, type)) throw new Error("Unsupported download type");
const extension = extensions[type];
return 'attachment; filename="imagild-' + taskId + '.' + extension + '"';
}
The filename contains only controlled ASCII characters. Keep a friendly user title in the UI or a manifest. If your product requires international filenames, use a maintained standards-aware implementation for the appropriate encoded filename parameter rather than concatenating raw Unicode or untrusted strings.
Never permit carriage returns, line feeds, path traversal components, or copied Authorization data inside a header. The OWASP REST guidance supports careful response handling and authorization at protected resource boundaries.
Preserve delivery semantics
A download route should stream the already approved bytes and preserve correct length and range information when it supports partial transfer. Do not retain an old Content-Length after transforming or compressing the body.
Use private caching behavior appropriate to the asset. An attachment header does not make sensitive content safe to expose through an unprotected public URL, and it does not remove the active-membership requirement on upstream retrieval.
Test filenames in the browsers your application supports. The cross-origin download guide explains why a link's download attribute alone may not control the observed behavior.
Fix the filename without repeating generation
If the saved image has the wrong extension, inspect its real format before renaming or redownloading. The HTML-instead-of-image diagnostic helps identify responses that are not media at all.
Current generation choices and prices remain in the model market. A naming correction should reuse the existing result. Keep task identity, media validation, safe headers, and deliberate sharing together so a convenient filename does not weaken the access boundary.
Related tasks
- Why Does My Download Button Open the Photo in a New Browser Page Instead of Saving It?
- Why Does My Downloaded Image Open as a Web Page?
Sources and scope
- Imagild API console: Private authenticated content route and strict generation fields.
- Imagild model market: New generation choices separate from filename correction.
- MDN Content-Disposition: Attachment/inline semantics and filename response parameters.
- OWASP REST Security Cheat Sheet: Protected endpoint authorization and controlled response/input handling.
Product instructions were checked against the current Imagild API contract and the public model catalog. Code, budgets and acceptance checks are illustrative; this article does not claim a new paid generation test, an uptime measurement, a search-volume study or a ranking of AI citations.
Prepared by Imagild Editorial, the company editorial team responsible for these guides. AI assisted research and drafting. This is documentation-based guidance with proposed examples, not a claim of hands-on testing or an independent product review. Report a correction.
Cover: Original Imagild product screenshot captured on 28 October 2026; model availability and prices may change. This image is not an API response or a performance benchmark.