
Do not assume an Imagild image upload has generation-style idempotency. POST /files creates an owned reference resource and returns data.file_id; the route does not use the generation operation-key mechanism. Save that identifier, then reuse it in the request snapshot for any generation that depends on the upload.
Key Takeaways
- An
Idempotency-Keyon upload is not a documented duplicate-resource guarantee.- Upload acceptance and generation acceptance are different checkpoints.
- Replacing a saved
file_idduring generation recovery can change parsed parameters and produce a conflict.
Separate the file resource from the paid task
A typical reference workflow has two stages. First, upload an authorized photograph. Second, submit an image or video generation using its returned selector. These stages have different endpoints, bodies, and response identifiers.
| Stage | Request | Accepted result |
|---|---|---|
| Reference upload | Multipart photo to POST /files | HTTP 201 and data.file_id |
| Image generation | Strict JSON to POST /images/generations | HTTP 202 and data.id |
| Task status | Authenticated GET /tasks/{id} | Task and usage state |
The API console defines this separation. Uploading a file does not itself submit the later generation. Both actions require authorized access, and upload writes count toward the account's current write limit.
Replicate's input-file documentation is another example of treating input media as a distinct integration concern. Its resource identifiers and limits are not Imagild's contract.
Save the upload acknowledgment immediately
The current upload body uses multipart field photo and accepts a maximum of 20 MiB. Use an authorized supported image and retain the source in your own controlled workflow.
This POSIX shell example performs one upload attempt and extracts the returned selector:
curl --silent --show-error --fail-with-body \
--connect-timeout 10 --max-time 30 \
'https://imagild.com/api/relay/v1/files' \
-H "Authorization: Bearer $IMAGILD_API_KEY" \
-F 'photo=@reference.jpg' \
--output upload.json || exit 1
jq -er '.data.file_id | select(type == "string" and length > 0)' \
upload.json > reference-id.txt
The local transfer timeout is not evidence that the server canceled an upload. If acknowledgment is missing, do not invent a file_id from the filename or assume a second attempt will return the original resource.
The public contract does not provide an upload lookup-by-checksum recovery promise. Follow your application's controlled retry policy and support procedure when needed; a repeated upload may create another resource.
Keep generation recovery attached to its original selector
Consider this illustrative sequence:
- Upload A returns file selector A.
- An image operation is saved with selector A and a stable generation key.
- Generation is sent, but its acknowledgment is lost.
- The application uploads the same bytes again and receives selector B.
Selector B is not a safe replacement inside the earlier operation snapshot. Even identical source bytes do not establish that the parsed selector is identical. Recover the original generation using its saved selector A, original request, and original key.
If selector A is no longer usable, investigate the original task before deciding on a new operation. Do not silently switch to B merely to get past an error. A changed accepted request under the same key can return 409.
Plan references for deliberate new work
For a new approved generation, use one owned selector: file_id or a completed owned image_task_id, never both. A referenced image request needs at least 20 characters of meaningful instructions after trimming.
The attachment-order audit helps prevent source-label mistakes. The reference scope guide helps distinguish the object you want to preserve from the scene you want to change.
Current image costs in the model market are 10, 15, and 20 points for 1K, 2K, and 4K. Active membership is separately required for API use.
Stable generation keys reduce duplicate paid submissions when the parsed request is unchanged. They do not provide global exactly-once execution, automatic upload deduplication, or a substitute for reconciling an unknown generation outcome.
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: Separate multipart photo upload and strict generation routes, reference selectors, account access and task acceptance.
- Imagild model market: Current image generation point schedule.
- Replicate input files: Input-file resources are a distinct integration stage; no Replicate deduplication semantics transferred.
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.