
Upload an Imagild reference photo to POST /files as multipart form data using the field name photo. Do not send a base64 image inside generation JSON. In a browser application, send the user's file to your own authenticated backend; that backend keeps the Imagild API key private and performs the upstream upload.
Key Takeaways
- Use multipart
photofor upload, then save the returneddata.file_id.- Let FormData generate its boundary instead of manually setting a multipart Content-Type.
- A successful upload is a reference resource, not an accepted image-generation task.
Put the credential on the correct side
The browser can select a file without receiving your Imagild Bearer key. Your application endpoint must authenticate the user, apply its own upload policy, and bind the resulting reference to that user's authorized operation.
MDN's FormData guide explains form-style file transmission and warns against overriding the generated multipart boundary. If your backend reconstructs a new FormData body, forward the file bytes and filename; do not copy an old boundary header onto the new body.
The Imagild API console provides the upstream Base URL and access requirements. Active membership is required for uploads and generation; buying points alone is not API eligibility.
Build a real multipart upload
This example runs on a backend runtime with Fetch, FormData, and Blob support. It receives an already authorized Blob from your application's upload handling. Authentication of your browser user and request-size enforcement belong before this function.
async function uploadReference(photoBlob, filename, apiKey) {
if (!(photoBlob instanceof Blob) || photoBlob.size > 20 * 1024 * 1024) {
throw new Error("Invalid photo or file exceeds 20 MiB");
}
const form = new FormData();
form.append("photo", photoBlob, filename);
const response = await fetch("https://imagild.com/api/relay/v1/files", {
method: "POST",
headers: { Authorization: "Bearer " + apiKey },
body: form,
signal: AbortSignal.timeout(30000)
});
if (response.status !== 201) throw new Error("Reference upload not accepted");
const { data } = await response.json();
if (!data?.file_id) throw new Error("Upload acknowledgment lacks file_id");
return data.file_id;
}
Do not add Content-Type: application/json or a bare multipart/form-data header here. The runtime creates the correct boundary. The thirty-second abort is a client transfer limit, not proof of server-side cancellation.
The 20 MiB check is only one preflight. The server still validates the actual image. Avoid treating a browser-supplied filename or MIME label as proof of valid image bytes.
Persist the selector before starting generation
An accepted upload returns HTTP 201 with data.file_id. Save that exact value with the account, application user, source description, and intended operation. Do not build it from the original filename or a website Library URL.
Your next image request sends strict JSON with a valid model, prompt, resolution, and file_id. A referenced image prompt needs at least 20 characters after trimming. Supply one reference selector; do not also add image_task_id.
Image generation is a separate HTTP 202 task. Preserve its own operation key and task ID. An upload's acknowledgment should never be displayed as “image generated.”
Handle missing acknowledgment without inventing deduplication
The upload route does not promise generation-style Idempotency-Key deduplication. If an upload response is lost, keep the uncertainty visible and follow a controlled retry policy. A repeated upload can create a different resource.
For an already submitted generation, retain its original file_id in the request snapshot. Reuploading identical bytes does not guarantee an identical selector, and replacing it can alter parsed parameters under the old generation key.
Make the next paid decision explicit
Current image tiers in the model market cost 10 points at 1K, 15 at 2K, and 20 at 4K. Show that generation quote after upload rather than implying that file selection already approved a paid render.
Use the attachment-order audit to verify source binding and the reference scope guide to write the intended edit. Correct multipart transport gets the reference into the workflow; ownership, clear instructions, and output review complete the integration.
Related tasks
- After Reordering References, Does “Image 1” Still Point to the Right File?
- Should an AI Reference Replace an Object or Bring in the Whole Scene?
Sources and scope
- Imagild API console: Multipart photo upload, file_id acknowledgment, membership and generation separation.
- Imagild model market: Current image generation quote tiers.
- MDN Using FormData Objects: FormData file transmission and runtime-generated multipart boundaries.
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.