POST /v1/images/generations

Create an image using an enabled model with a reviewed image.generate route. Check available options and prices with GET /v1/images/catalog?model=YOUR_MODEL; example model names and prompts below are not preconfigured products.

Request

This command can incur charges if you execute it with a real key and supported model. Every creation requires a new application-chosen Idempotency-Key; keep that key for retries of this same request.

curl https://api.model-gate.com/v1/images/generations \
  -H "Authorization: Bearer $MODEL_GATE_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: illustration-001' \
  -d '{"model":"YOUR_MODEL","prompt":"A clean isometric server gateway illustration","n":1,"model_gate":{"async":true}}'

With model_gate.async: true the server returns HTTP 202 and an image.operation containing its ID, status and result URL. Without it, the server waits up to 55 seconds, then returns the finished image, an explicit provider error, or an HTTP 202 operation to poll. Top-level async, streaming, unknown options, repeated JSON fields and incompatible settings are rejected.

Response and result retrieval

Example HTTP 202 response excerpt (timestamps and other operation fields are omitted):

{"object":"image.operation","id":"01K5P0Y3S80X8GFH1Q9WXQK7BX","status":"queued","result_url":"/v1/images/operations/01K5P0Y3S80X8GFH1Q9WXQK7BX/result"}

Call GET /v1/images/operations/{id} with the same active API key. A completed result is at GET /v1/images/operations/{id}/result, with only created and data by default. Add ?view=details for the previous model_gate metadata. Each output normally has b64_json. When the route supports response_format: url, its URL is relative to this gateway and still requires authentication. Never expect a public upstream URL.

A repeated identical request with the same Idempotency-Key does not start another generation. A different request under that key returns HTTP 409. When the status is outcome_unknown or review_required, stop and request operator investigation; changing the key could pay for a duplicate. A download failure is separate and can use the download-only retry described in image operations.

The price is not inferred from base64 length. An unknown token price remains unknown; there is no advance wallet reserve. A committed accounting record is separate from eventual wallet settlement. Files are retained for 24 hours, while the operation remains available for idempotent replay. Use your normal API key, not a browser-session key. The dedicated Playground Images tab is available from10.49.0.

For source images and optional masks, see POST /v1/images/edits.

Optional model_gate.quote_sha256 binds a previously approved route quote; changed context fails before dispatch. The Images tab uses scoped permissions without exposing permanent API secrets.

Price and usage fields

In the explicit details view, a fixed_quote in an unfinished operation is a price quote, not a debit. Recorded measured pricing is shown as Calculated cost; accounting_recorded still does not prove that the balance has already been updated. files_available is true only when the operation lists saved output files whose retention window has not expired. No files while a request is pending does not mean they have expired.

Some image-priced results report only aggregate token counts. In that case usage can contain token_usage_status: aggregate_only_not_priced and reported_tokens with input_tokens, output_tokens, total_tokens and optional cached_tokens. These are reported observations, not a text/image token breakdown; an omitted category is not an observed zero. A token-priced result still needs sufficient usage data. Invalid or contradictory results remain review_required; contact support without submitting another generation.

Default queued/ongoing replies omit accounting and empty fields. Read the operation with ?view=details to inspect its quote, usage and settlement. Playground creates omit max_cost_usd, keeping route/quote binding and Idempotency-Key.

Image request errors

Errors contain a stable error.code, human-readable error.message, error.type and, where applicable, error.param. Keep X-Request-ID from the response for support; never send the API key. Unknown canonical model and alias return 400 model_not_found, not a catalog outage.

Restrictions of several routes are not merged into fictitious accepted combinations. Do not automatically repeat a paid POST after a timeout or ambiguous failure. Check operation status and keep the original idempotency key. Detailed internal configuration/credential errors are not returned to clients.

Terminal provider errors (14.11.2)

A complete recognized provider error without an image becomes status: failed, including when the supplier incorrectly returns HTTP 200. Synchronous creation and a replay of an already failed operation return a mapped HTTP error with both error and the accepted operation ID. For example, image_generation_failed uses HTTP 502 and error.type: image_generation_error; invalid parameters or content policy use 400, and a provider request limit uses 429.

A successful status GET remains HTTP 200 and carries the same failed status and safe error. billing_review_required is a separate accounting observation; it does not change a failure into a pending generation or authorize another paid POST. Keep Location, X-Request-ID and the original Idempotency-Key. See image operation errors and accounting for the complete response and retry rules.