
Send file_id when the reference is an image you uploaded through the Imagild API. Send image_task_id when it is the output of an already completed Imagild image task. Choose one selector, never both, and use a source owned by the same account as the new request.
Key Takeaways
- Upload IDs and completed image-task IDs are different reference types.
- An arbitrary URL, a video task ID, or another account's identifier is not an accepted reference.
- Image requests with either selector need at least 20 characters of instructions after trimming.
Choose by the origin of the reference
| Source you want to use | Selector | What must be true |
|---|---|---|
A photograph uploaded through POST /files | file_id | The upload exists and belongs to the account |
| A generated API image | image_task_id | The owned image task succeeded and its result is available |
| A website URL or external CDN link | Neither directly | Obtain an authorized file and upload it first |
| A generated video task | Neither for an image reference | Choose a supported image source instead |
A generated image's task ID saves an unnecessary manual download-and-upload step in your integration. It is a source selector, not permission to reference every task ID visible in a log.
Replicate's input-file documentation illustrates why input media deserves its own integration path. Its upload formats and limits are provider-specific; the selectors and ownership rules here belong to Imagild.
Use the returned upload identifier unchanged
For an authorized local photograph, upload it from your backend:
curl --fail-with-body \
'https://imagild.com/api/relay/v1/files' \
-H "Authorization: Bearer $IMAGILD_API_KEY" \
-F 'photo=@product-reference.jpg'
Read data.file_id from the response. Do not construct it from a filename or infer it from a Library page URL. The current API upload body uses the multipart field photo, with a 20 MiB maximum.
Then submit an image request such as:
{
"model": "nano-banana-pro",
"prompt": "Keep the blue cup and its handle shape; replace the background with a plain warm studio backdrop.",
"resolution": "2K",
"file_id": "USE_THE_RETURNED_FILE_ID"
}
The placeholder must be replaced by the actual returned value. Send this JSON to POST /images/generations with Bearer authentication and a new operation's Idempotency-Key. Do not send both multipart content and generation JSON to the same endpoint.
Reference a completed generated image instead
If the source came from a prior API image generation, first inspect that task. Wait for data.status: "succeeded" and verify the output is the one you intend to reuse.
Replace the reference field in the previous request with:
{
"model": "nano-banana-pro",
"prompt": "Keep the blue cup and its handle shape; replace the background with a plain warm studio backdrop.",
"resolution": "2K",
"image_task_id": "00000000-0000-4000-8000-000000000001"
}
That UUID is illustrative, not a real available task. Use your completed owned image task ID. Remove file_id entirely when choosing this path. An in-progress task cannot yet supply a completed reference, and a missing retained result must be resolved before starting dependent work.
Keep ownership and the edit brief together
Your application should store the source type, source ID, owner, and requested change together. A selector UI that shows only “Image 1” can hide a mistaken binding after reordering. The attachment-order audit describes the wider class of reference-label errors.
Write what should change and what should remain. The reference scope decision guide helps avoid confusing an object reference with an instruction to borrow an entire scene. A valid selector cannot guarantee preservation of every visual detail; inspect the new output.
Quote the new operation separately
Using an existing reference does not make the next image free. Current image generations cost 10, 15, or 20 points for 1K, 2K, or 4K. Check the model market, and use the API console for current request details. API access still requires active membership; a points purchase alone does not satisfy that gate.
Preserve the reference record with the new task ID so support and reviewers can identify exactly which source and instructions produced the next candidate.
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: POST /files, reference selectors, asynchronous image tasks and membership gate.
- Imagild model market: Current image pricing tiers.
- Replicate input files: Input files are a distinct integration concern; Replicate's contract is not transferred to Imagild.
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.