
Design an Imagild idempotency key around one approved media operation, not around one HTTP attempt. Generate the key once, persist it with the intended request, and reuse it when the acknowledgment is uncertain. For a deliberately new generation, create a new operation and a new key even if the prompt happens to be identical.
Key Takeaways
- Keys must contain 8–128 characters using letters, digits, or
._:-.- Reusing a key with the same parsed parameters reuses the task; changed parameters produce a conflict.
- This is duplicate-submission protection, not a global exactly-once guarantee across your entire application.
Start with the user's paid decision
Imagine a user approves a 2K product image. That approval should create an application operation with an owner, a request snapshot, and a stable key. If a worker retries because the connection drops, it is still fulfilling the original approval.
If the user later asks for another candidate, that is a different decision. Do not deduplicate all identical prompts forever: people can intentionally request multiple candidates from the same brief. The operation expresses intent; the prompt describes the desired image.
The AWS Builders' Library discussion of safe retries explains why caller-provided identifiers help express whether repeated requests represent the same intent. Imagild's specific limits and behavior come from its API console.
Choose a key format you can preserve
A random UUID fits the supported character set and length. A descriptive prefix is optional; it should identify application work without exposing customer information.
| Candidate | Assessment |
|---|---|
| A random UUID | Suitable when generated once and stored |
product-cover:20261028:0007 | Suitable if your application prevents collisions |
| Customer email plus prompt | Avoid: leaks private information and couples identity to content |
| Current timestamp alone | Avoid: weak uniqueness and easy accidental regeneration |
| A newly generated UUID on every retry | Valid syntax, wrong operation design |
Use the header Idempotency-Key. Do not place the value inside the strict image JSON body. It is a correlation identifier, not a substitute for the Bearer API credential.
This native Node.js example creates a valid identifier without a live API call:
import { randomUUID } from "node:crypto";
const operation = {
idempotencyKey: randomUUID(),
request: {
model: "gpt-image-2.5",
prompt: "A blue ceramic vase on a pale stone plinth",
resolution: "2K"
}
};
if (!/^[a-zA-Z0-9._:-]{8,128}$/.test(operation.idempotencyKey)) {
throw new Error("Invalid operation identifier");
}
console.log(operation.idempotencyKey);
Persist this record before sending it. The example generates a new plan each time it runs; a recovery worker must load an existing record instead of rerunning creation.
Scope identity to the account and operation
Imagild's reuse behavior is associated with the owning account and idempotency key. Creating a second API credential under the same account does not make an intentionally reused operation key a fresh generation. Keep application namespaces consistent across deployment environments that share that account.
Record the account reference, endpoint, exact submitted payload, key, and returned task ID. Protect the record according to its contents: the key itself is not your API secret, but prompts and customer associations may be private.
When the server accepts the request, save data.id. Poll that ID rather than repeating generation to check progress. Same-key recovery with the same parsed parameters must not be confused with changing a prompt or resolution under an existing key.
Connect the identifier to a visible budget
The model market currently prices image operations at 10 points for 1K, 15 for 2K, and 20 for 4K across the three public image choices. API access requires active membership independently of points.
Store the displayed quote with the approval. A stable key helps keep a network retry tied to that approval; it does not promise identical output across separate operations or eliminate every distributed failure.
Use the points and job planning guide for budget context. If the task outcome is unknown, preserve its identity and use the failed-job decision process to reconcile it before authorizing additional paid work.
Related tasks
- Imagild Points, Resolution and Jobs: Plan a Creation Before You Spend
- What Should You Check Before Retrying a Failed Image or Video Job?
Sources and scope
- Imagild API console: Required header, accepted key format, same-parameter task reuse and asynchronous task identity.
- Imagild model market: Current image tier pricing.
- AWS Making Retries Safe with Idempotent APIs: Caller request identifiers distinguish repeated fulfillment of one intent from new intended work.
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.