
Imagild's image-generation JSON does not accept an n field. To request several images, create one logical operation per image, give each a different idempotency key, and track each returned task separately. Your application can present a batch, but the API contract remains individual asynchronous image tasks.
Key Takeaways
- Three intentional 2K image operations currently require a 45-point generation allocation.
- Distinct images need distinct operation keys; retries of one image keep its existing key.
- Preserve partial results instead of repeating successful items when one task fails.
Plan the set before sending requests
Decide whether the user wants independent alternatives or a sequence of dependent edits. Three alternatives can start from the same brief. A sequence in which image two references image one must wait for the first completed output before the next dependent submission.
For independent alternatives, prepare a manifest:
| Item | User intent | Resolution | Planned points |
|---|---|---|---|
| A | Blue vase beside a clear window | 2K | 15 |
| B | Blue vase on a dark studio shelf | 2K | 15 |
| C | Blue vase against a warm paper backdrop | 2K | 15 |
The total is 45 points. It excludes retakes, separate reference-image generations, and the active membership required for API access. Check the current model market before presenting the quote.
A shared model name does not make request fields universal. OpenAI's image reference defines its own image API; Imagild's accepted fields come from the API console.
Create durable operation identities once
This Node.js planning script writes a local manifest before any paid calls. Run it in a private project directory. It deliberately refuses to overwrite an existing manifest.
import { randomUUID } from "node:crypto";
import { writeFile } from "node:fs/promises";
const prompts = [
"A blue vase beside a clear window, soft morning light",
"A blue vase on a dark studio shelf, soft side light",
"A blue vase against a warm paper backdrop, soft light"
];
const operations = prompts.map((prompt, index) => ({
item: index + 1,
idempotencyKey: randomUUID(),
payload: { model: "gpt-image-2.5", prompt, resolution: "2K" },
taskId: null
}));
const manifest = { plannedPoints: operations.length * 15, operations };
await writeFile("image-batch.json", JSON.stringify(manifest, null, 2), {
flag: "wx"
});
console.log("Planned generation points:", manifest.plannedPoints);
A production application should keep this ledger in durable storage with account ownership and access controls. The important property is that a process restart reads existing operation identities instead of recreating them. Prompts can contain private information, so treat the manifest as application data.
Submit gradually and save each acceptance
For each unsent manifest entry:
- Send its
payloadtoPOST /images/generationswith Bearer authentication and that entry'sIdempotency-Key. - On HTTP 202, persist
data.idbefore moving to the next item. - Poll accepted task IDs independently, respecting
poll_after_seconds. - Download only successful outputs, labeling them with the manifest item and task ID.
Do not submit an uncontrolled burst. The current account write limit is ten generation or upload writes per minute; a 429 response includes a retry delay. A small sequential submission loop is easy to reason about, although it does not mean generation itself is synchronous.
Stripe's idempotency documentation explains why a logical operation needs a stable retry identity. Imagild has its own key constraints and task-reuse behavior; Stripe's storage durations and response replay rules do not apply here.
Recover the missing item, not the whole batch
Suppose A and C succeed while B fails. Keep A and C. Inspect B's task status, error, and usage.state before offering another attempt. If B's outcome is uncertain, retain the same operation identity and reconcile it instead of creating an accidental extra generation.
For a confirmed failure and a deliberate new candidate, record a replacement operation linked to B. Do not erase the failed record or call all three again. The failed-job next-action guide helps choose the correction.
Use points and job planning to explain the batch's visible budget. Per-item identity and partial completion let your UI offer several candidates without hiding duplicate work or implying a nonexistent batch endpoint.
Related tasks
- What Should You Check Before Retrying a Failed Image or Video Job?
- Imagild Points, Resolution and Jobs: Plan a Creation Before You Spend
Sources and scope
- Imagild API console: Individual image tasks, required Idempotency-Key, async polling, access gate and current write limits.
- Imagild model market: 2K costs 15 points per current image operation.
- OpenAI image generation reference: Other image APIs expose separate parameter contracts.
- Stripe idempotent requests: A stable client-generated operation identifier is the foundation for safe network retries; Stripe-specific replay rules not 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.