Images idempotency and original-submission recovery

Send Idempotency-Key on the first generation request. A key cannot be attached retroactively to an earlier submission. If its response is lost, recover the original submission using authenticated GET requests; do not create a replacement generation.

Coverage

The contract applies to every current or future model served through POST /v1/images/generations, /v1/images/generations/async, /v1/images/edits, /v1/images/edits/async, /v1/edits, and /v1/images/variations when that operation is supported. It also covers the /v1/midjourney/generations aliases and legacy /mj/submit/* routes. It does not enable an otherwise unsupported model/endpoint combination.

To cover image-producing multimodal models without a model allowlist, the same protection applies to keyed POST /v1/chat/completions, /v1/responses, and native Gemini /v1/models/{model}:generateContent calls (including :predict and :streamGenerateContent). These routes can also produce text; their keyed calls follow the same contract. Streaming output is buffered for durable recovery rather than delivered incrementally. Prefer non-streaming calls with this contract.

Requests without this header retain their existing behavior. Seedance has a separate video submission contract.

Header, scope and request identity

Authorization: Bearer YOUR_API_KEY
Idempotency-Key: image-order-123-attempt-1
Content-Type: application/json

• Use 8–128 visible ASCII characters, with no spaces. Generate a unique key for each intended generation and retain it before sending the request.
• Keys belong to the submitting account, across all covered endpoints. Another valid API key for the same account can recover the receipt and original response. Account status, key revocation/expiry and IP restrictions still apply. Exhausted key quota does not block recovery; a new execution still requires normal quota authorization.
• APIMaster and other services have independent key namespaces and receipts. Reusing a key on another service does not deduplicate across services.
• A repeated key with identical request identity never executes or charges again. An available accepted response is replayed with Idempotency-Replayed: true. If the outcome is pending or unknown, it returns HTTP 202 and the original receipt.
• A changed endpoint, model, body, effective key group or explicitly pinned channel returns HTTP 409 with error.code = idempotency_conflict. JSON identity is byte-exact: retain and resend the original bytes, including whitespace, field order, number spelling and omitted/explicit fields. GET recovery requires no body.
• For multipart, the boundary and uploaded filename may change. Form field values, upload field names, file bytes and file order within each upload field must remain identical. Repeated scalar fields are rejected. Do not change references while reusing a key.
• Receipts and stored original responses are retained for at least 30 days. There is currently no automatic deletion or key reuse. A timeout or an old key never grants permission to execute it again. Stored response URLs retain their own lifetime; download results promptly.

A durable account/key claim is written before downstream generation or billing. Concurrent requests use one original execution. Keyed submissions disable automatic channel retries and speculative image hedges; an uncertain attempt is not replaced internally. This is opt-in: requests without Idempotency-Key retain the existing fallback behavior and do not receive this original-submission recovery guarantee.

Recover without another generation POST

Use the same key and a valid Bearer key for the submitting account:

# Read the original submission receipt. This does not poll a provider or bill.
curl --fail-with-body 'https://apimaster.ai/v1/image-submissions/by-key' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Idempotency-Key: image-order-123-attempt-1'

# Retrieve the stored original HTTP body and status: task response or image result.
curl --fail-with-body 'https://apimaster.ai/v1/image-submissions/by-key/response' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Idempotency-Key: image-order-123-attempt-1'

Both lookups are authenticated and read-only: they do not create a task, generate an image, settle/refund billing or re-send to an upstream. They include Cache-Control: no-store, X-Image-Submission-Id and X-Original-Request-Id. Receipt responses use data; /response returns the original body and HTTP status when available, or HTTP 202 with the receipt when unavailable.

If the original response contains data[0].task_id, continue using the model's existing task GET endpoint with that ID and original model. The original response can instead contain synchronous data[].url / b64_json, a Midjourney batch or a native multimodal result. The recovery endpoint does not convert result formats or refresh expired image URLs.

Acceptance and billing evidence

data.status	Meaning	Create a replacement?
pending, submitting	The original claim/execution is in progress	No; query the receipt later
accepted	The original successful JSON response was persisted; asynchronous work may still be running	No; retrieve the response and query its original task
acceptance_unknown	Acceptance cannot be established, including interrupted execution or an expired execution lease	No; retain the key and request ID for support
not_accepted	The live original request was rejected before entering downstream business/generation/billing code	Only after correcting the cause, using a new key

A new technical attempt is authorized only when the receipt establishes all of: status = not_accepted, acceptance_final = true, new_submission_safe = true, retry_safe = true, billing_final = true, billing_status = final_zero and net_charge = 0. Reusing the old key still returns its original receipt; it never starts a new attempt.

For other states, billing_status = unverified, billing_final = false and net_charge = null. These values deliberately do not certify a final bill. A failed task, refund request, timeout or empty result is not proof of non-acceptance or final zero-net billing. This receipt does not infer those guarantees from a task failure or a later refund.

An absent receipt returns HTTP 404 with error.code = submission_not_found and error.retry_safe = false. It can reflect an in-flight race, a request without a key or a submission before this feature. It is not final not_accepted.

Structured errors and uncertain outcomes

error.code	Meaning	Safe to create a replacement?
invalid_idempotency_key	Header does not meet the format requirements	Correct the header; it does not establish another original request's outcome
idempotency_conflict	The account/key already identifies a different request	No; recover the original key
submission_not_found	No receipt is currently visible	No
submission_storage_unavailable, submission_claim_unavailable	Temporary storage/claim failure	No; retry the GET lookup for the original key
submission_response_too_large	The original response exceeded the 64 MiB recovery buffer	No; use a known original task ID or contact support
do_request_failed, read_response_body_failed, image_generation_timeout	Transport, response-read or generation-wait failures on applicable adapters	No; these codes do not prove non-acceptance

Provider-specific errors and HTTP 408/429/5xx are not a universal safe-retry signal. After a lost response, preserve the account, key, original request bytes, UTC timestamp, model, endpoint and request ID if received. Never send your API key to support.

Signed-in image playground proxy

The signed-in /api/playground/image proxy forwards a supplied Idempotency-Key and the original receipt headers. Recover through GET /api/playground/image with that header; add ?submission_response=1 to retrieve the stored original body. A GET with task_id remains a task query. Session authentication is required. The playground does not invent a key for a request that omitted it.