Images
OpenAI's two image routes, front doors on the task API's image_generation and image_edit (decided 2026-11-04, the edit route 2026-11-12): each body is read in OpenAI's shape and served as the task it stands for, with the task route's key, limits, idempotency-key, requirement headers, quote, content checks and placement (Image generation and editing). Neither body takes a hips object: requirements ride as the x-hips-* headers. A route answers 400 type_not_served at model while no model of its type is served.
/v1/images/generationsservedImage generation in OpenAI's JSON shape, billed per image at its size. Answers 400 type_not_served while no image generation model is served.
Request
{"model": "<catalog id>", "prompt": "A red apple on a wooden table, soft morning light", "n": 2, "size": "1024x1024", "output_format": "png"}Parts list: Generation fields
modelRequiredAn image model's catalog id, alias or pinned id. A model of another task is a 400
task_mismatch.promptRequiredA string, not empty, at most 64 KiB, with no NUL character.
nAcceptedThe images to make, from 1 to the model's limit and never above 8; 1 when absent. A string of digits is read as the number.
sizeAccepted<width>x<height>in pixels, such as1024x1024, held to the model's bounds aswidthandheightare on the task API;autoor absent, the model's own size. The size sets the price, and one the model is not offered at is a 400invalid_valuenaming the sizes it is.output_formatAcceptedpng(the default, lossless),jpegorwebp(lossless).output_compressionAccepted with jpegA
jpegoutput's quality, a whole number from 1 to 100, 75 when absent. With apngoutput, the default, or awebpoutput, which are lossless, a 400unsupported_value; anything but a whole number a 400invalid_type.response_formatAccepted as b64_jsonImages are answered inline; HIPS keeps no image to link to, so
urlis a 400unsupported_value.userAccepted, not usedA string. It changes neither the images nor the bill.
streamAccepted as falsetrueis a 400unsupported_parameter: an image answer is never streamed.quality, style, background, moderation, partial_images, input_fidelityRejected, 400 unsupported_parameterOpenAI's fields that HIPS does not serve, named in the refusal.
Any other nameRejected, 400 unknown_parameterNever ignored, even when sent as
null. A field sent twice is a 400invalid_value.
/v1/images/editsservedImage editing in OpenAI's multipart shape, billed per image at its size. Answers 400 type_not_served while no image editing model is served.
A multipart/form-data body, its fields those of the generation route as form fields, beside the images as file parts. Anything else is a 400 invalid_value at body.
Parts list: Edit fields
image, image[]RequiredThe images to change, each a file part, at most 16 in a form and at most the model's number of input images. PNG, JPEG or WebP, told by their first bytes; an empty part is a 400
invalid_image. The input images' bounds of the task API hold (Input images).maskOn a model that inpaintsOne file part, the area to paint over. A model that takes no mask refuses it with a 400
unsupported_value; a second mask is a 400invalid_value.model, prompt, n, size, output_format, output_compression, response_format, user, streamAs on the generation routeForm fields, each sent once.
Any other fieldRejectedOpenAI's fields HIPS does not serve are a 400
unsupported_parameter, any other name a 400unknown_parameter, a field sent twice a 400invalid_value.
A body on either route is at most 3,358,720 bytes, the images within the 3,096,576 bytes one request carries to a GPU; a larger body is a 400 request_too_large before it is read whole, since an image request carries its images inline and takes no upload.
Answer
{ "created": 1792663200, "data": [{"b64_json": "<base64>"}], "output_format": "png", "size": "1024x1024", "hips": { "withheld": [ {"index": 1, "error": {"message": "HIPS's automated content checks withheld this image: ...", "type": "invalid_request_error", "param": null, "code": "image_withheld"}} ] }}Parts list: Fields
createdThe answer's time, in seconds since 1970.
dataEach delivered image in order, as
b64_json, marked as made with AI (The AI-generated mark).output_format, sizeThe format and the size of every image of the answer.
hips.withheldOnly when the content checks withheld an image: each withheld image's
indexamong the images asked and itserror, whose message is the statement of reasons. A withheld image is not billed.
The answer carries the task route's headers: x-hips-cost-micros (the images delivered times the price at their size), x-hips-quote, x-hips-model, x-hips-pool and x-hips-request-id (Requirements and headers). There is no usage object.
An image answer's body must be read within 120 seconds of its head: a client reading slower than about 270 KB/s on a 32 MiB answer is cut, and the answer is not resent.
A refusal is in the error envelope, and param names the field as these routes name it: n, size, prompt, image, image[0], mask, output_compression. The content checks' refusals, the 429 and 503 an image request can meet and what each costs are on Image generation and editing.
| Status | Type | Code | Situation | Retry |
|---|---|---|---|---|
| 400 | invalid_request_error | invalid_json | The body is not JSON, or not an object | No |
| 400 | invalid_request_error | missing_required_parameter | A required field or header is absent; param names it | No |
| 400 | invalid_request_error | invalid_type | A field has the wrong JSON type | No |
| 400 | invalid_request_error | invalid_value | A value is out of range or malformed: stop with more than 16 entries, a prompt_cache_key over 512 characters, a string holding a lone surrogate escape, a router name with an empty or unknown suffix, both max_tokens names with different values | No |
| 400 | invalid_request_error | unknown_parameter | A field the gateway does not know, at any depth; param names it | No |
| 400 | invalid_request_error | unsupported_parameter | A known field HIPS does not accept, or a feature the named model does not advertise in the pool the request resolves to; param names it and message names the model | No |
| 400 | invalid_request_error | unsupported_value | n other than 1, stream_options without stream, a message role, part, item or tool type not accepted, a hosted tool that is not served | No |
| 400 | invalid_request_error | type_not_served | POST /v1/audio/transcriptions or /v1/audio/speech, or POST /v1/images/generations or /v1/images/edits while no model of the route's type is served: the message names the type | Once the type is served |
| 400 | invalid_request_error | invalid_image | An image part or input cannot be decoded, is of an unsupported type or over the pixel limit | No |
| 400 | invalid_request_error | request_too_large, input_too_large, too_many_inputs, upload_too_large | A limit of the Limits page | No |
| 400 | invalid_request_error | task_mismatch | task is not the model's task, or the model is not an embedding model or a reranker on its route | No |
| 400 | invalid_request_error | requirement_conflict | Two requirements that cannot both hold, a header and a hips field that differ, a pool the model is never offered in, community with an always-on deployment, a knowledge base whose requirements the request cannot meet | No |
| 400 | invalid_request_error | invalid_idempotency_key, idempotency_key_reused, idempotency_in_progress | The idempotency rules | The last one, later |
| 400 | invalid_request_error | content_refused | An image request the content checks refused: its prompt or an input image asks for content the Acceptable Use Policy prohibits (param the prompt, inputs[0].text, for a generation, inputs for an edit; before any work), or every image made was withheld (param task). The message is the statement of reasons. Nothing charged | No |
| 400 | invalid_request_error | image_withheld | Not a request's answer: the error a withheld image carries in a task's results or in an image route's hips.withheld, beside the images delivered, its message the statement of reasons. A withheld image is not charged | No |
| 402 | insufficient_credit | insufficient_credit | The balance does not cover the request's maximum cost at the bound quote | After a top-up |
| 402 | insufficient_credit | budget_exceeded | A budget guardrail of the workspace, the key or the person is at its limit with block; the error carries guardrail and resets_at (null for a budget that never resets). Never a payment challenge | After resets_at, or once the limit is raised |
| 403 | permission_error | pool_not_allowed | A pool the workspace may not use for this model: one an access guardrail keeps out (named in the error), or a customer model's pool whose runtime-access conditions were not accepted | No |
| 403 | permission_error | model_not_allowed, region_not_allowed | A model, or a region requirement, that an access guardrail keeps out, the guardrail named in the error's guardrail member | No |
| 403 | permission_error | guardrail_unsupported | A content moderation guardrail applies to text it does not scan yet: a batch, or a task request with text; the guardrail named, uncharged | No |
| 404 | not_found_error | model_not_found | Unknown catalog id, alias, pinned id or dep_; another workspace's dep_; a name starting with hips-router that is not one of the four routers | No |
| 404 | not_found_error | result_expired | A task, embeddings or rerank request retried with its idempotency-key after the first completed: no answer is kept, and the message names the first request's req_ id. It ran and was billed once | No |
| 429 | rate_limit_error | rate_limit_exceeded | A rate limit; param is requests, tokens, uploads, batches (batches created per hour) or knowledge_search; Retry-After | Yes, after Retry-After |
| 503 | overloaded_error | no_capacity | No eligible worker under the request's requirements, in any pool the requirements allow; Retry-After. The message says what those pools can do now: a GPU that fits the model takes it when free or loads it when asked, which can take minutes or longer; or nothing can serve it, and a retry sooner than the given delay gets the same answer | Yes, after the given delay |
| 503 | overloaded_error | pool_unavailable | The named pool has no eligible supply for this model now and fallback is off; the other pool may have; Retry-After | Yes, or with fallback |
| 503 | overloaded_error | overloaded | Eligible workers exist and every one is saturated, or the queue is full; Retry-After | Yes |
| 503 | overloaded_error | content_check_unavailable | The content checks of an image request could not run (the decision service failed or did not answer in time), and HIPS sends no image request unchecked; Retry-After; uncharged | Yes, after Retry-After |
| 500 | api_error | internal_error | A fault in HIPS. Nothing billed | Once |
| 500 | api_error | attempt_failed | Every attempt failed for a reason that is not the client's and retries are exhausted. Nothing billed | Once |
| 500 | api_error | deadline_exceeded | The request's own time bound ended it; x-should-retry: false. Nothing billed | Not unchanged |
- Status
- 400
- Type
invalid_request_error- Code
invalid_json- Situation
- The body is not JSON, or not an object
- Retry
- No
- Status
- 400
- Type
invalid_request_error- Code
missing_required_parameter- Situation
- A required field or header is absent;
paramnames it - Retry
- No
- Status
- 400
- Type
invalid_request_error- Code
invalid_type- Situation
- A field has the wrong JSON type
- Retry
- No
- Status
- 400
- Type
invalid_request_error- Code
invalid_value- Situation
- A value is out of range or malformed:
stopwith more than 16 entries, aprompt_cache_keyover 512 characters, a string holding a lone surrogate escape, a router name with an empty or unknown suffix, bothmax_tokensnames with different values - Retry
- No
- Status
- 400
- Type
invalid_request_error- Code
unknown_parameter- Situation
- A field the gateway does not know, at any depth;
paramnames it - Retry
- No
- Status
- 400
- Type
invalid_request_error- Code
unsupported_parameter- Situation
- A known field HIPS does not accept, or a feature the named model does not advertise in the pool the request resolves to;
paramnames it andmessagenames the model - Retry
- No
- Status
- 400
- Type
invalid_request_error- Code
unsupported_value- Situation
nother than 1,stream_optionswithoutstream, a message role, part, item or tool type not accepted, a hosted tool that is not served- Retry
- No
- Status
- 400
- Type
invalid_request_error- Code
type_not_served- Situation
POST /v1/audio/transcriptionsor/v1/audio/speech, orPOST /v1/images/generationsor/v1/images/editswhile no model of the route's type is served: the message names the type- Retry
- Once the type is served
- Status
- 400
- Type
invalid_request_error- Code
invalid_image- Situation
- An image part or input cannot be decoded, is of an unsupported type or over the pixel limit
- Retry
- No
- Status
- 400
- Type
invalid_request_error- Code
request_too_large,input_too_large,too_many_inputs,upload_too_large- Situation
- A limit of the Limits page
- Retry
- No
- Status
- 400
- Type
invalid_request_error- Code
task_mismatch- Situation
taskis not the model's task, or the model is not an embedding model or a reranker on its route- Retry
- No
- Status
- 400
- Type
invalid_request_error- Code
requirement_conflict- Situation
- Two requirements that cannot both hold, a header and a
hipsfield that differ, a pool the model is never offered in,communitywith an always-on deployment, a knowledge base whose requirements the request cannot meet - Retry
- No
- Status
- 400
- Type
invalid_request_error- Code
invalid_idempotency_key,idempotency_key_reused,idempotency_in_progress- Situation
- The idempotency rules
- Retry
- The last one, later
- Status
- 400
- Type
invalid_request_error- Code
content_refused- Situation
- An image request the content checks refused: its prompt or an input image asks for content the Acceptable Use Policy prohibits (
paramthe prompt,inputs[0].text, for a generation,inputsfor an edit; before any work), or every image made was withheld (paramtask). The message is the statement of reasons. Nothing charged - Retry
- No
- Status
- 400
- Type
invalid_request_error- Code
image_withheld- Situation
- Not a request's answer: the error a withheld image carries in a task's
resultsor in an image route'ships.withheld, beside the images delivered, its message the statement of reasons. A withheld image is not charged - Retry
- No
- Status
- 402
- Type
insufficient_credit- Code
insufficient_credit- Situation
- The balance does not cover the request's maximum cost at the bound quote
- Retry
- After a top-up
- Status
- 402
- Type
insufficient_credit- Code
budget_exceeded- Situation
- A budget guardrail of the workspace, the key or the person is at its limit with
block; the error carriesguardrailandresets_at(nullfor a budget that never resets). Never a payment challenge - Retry
- After
resets_at, or once the limit is raised
- Status
- 403
- Type
permission_error- Code
pool_not_allowed- Situation
- A pool the workspace may not use for this model: one an access guardrail keeps out (named in the error), or a customer model's pool whose runtime-access conditions were not accepted
- Retry
- No
- Status
- 403
- Type
permission_error- Code
model_not_allowed,region_not_allowed- Situation
- A model, or a region requirement, that an access guardrail keeps out, the guardrail named in the error's
guardrailmember - Retry
- No
- Status
- 403
- Type
permission_error- Code
guardrail_unsupported- Situation
- A content moderation guardrail applies to text it does not scan yet: a batch, or a task request with text; the guardrail named, uncharged
- Retry
- No
- Status
- 404
- Type
not_found_error- Code
model_not_found- Situation
- Unknown catalog id, alias, pinned id or
dep_; another workspace'sdep_; a name starting withhips-routerthat is not one of the four routers - Retry
- No
- Status
- 404
- Type
not_found_error- Code
result_expired- Situation
- A task, embeddings or rerank request retried with its
idempotency-keyafter the first completed: no answer is kept, and the message names the first request'sreq_id. It ran and was billed once - Retry
- No
- Status
- 429
- Type
rate_limit_error- Code
rate_limit_exceeded- Situation
- A rate limit;
paramisrequests,tokens,uploads,batches(batches created per hour) orknowledge_search;Retry-After - Retry
- Yes, after
Retry-After
- Status
- 503
- Type
overloaded_error- Code
no_capacity- Situation
- No eligible worker under the request's requirements, in any pool the requirements allow;
Retry-After. The message says what those pools can do now: a GPU that fits the model takes it when free or loads it when asked, which can take minutes or longer; or nothing can serve it, and a retry sooner than the given delay gets the same answer - Retry
- Yes, after the given delay
- Status
- 503
- Type
overloaded_error- Code
pool_unavailable- Situation
- The named pool has no eligible supply for this model now and fallback is off; the other pool may have;
Retry-After - Retry
- Yes, or with fallback
- Status
- 503
- Type
overloaded_error- Code
overloaded- Situation
- Eligible workers exist and every one is saturated, or the queue is full;
Retry-After - Retry
- Yes
- Status
- 503
- Type
overloaded_error- Code
content_check_unavailable- Situation
- The content checks of an image request could not run (the decision service failed or did not answer in time), and HIPS sends no image request unchecked;
Retry-After; uncharged - Retry
- Yes, after
Retry-After
- Status
- 500
- Type
api_error- Code
internal_error- Situation
- A fault in HIPS. Nothing billed
- Retry
- Once
- Status
- 500
- Type
api_error- Code
attempt_failed- Situation
- Every attempt failed for a reason that is not the client's and retries are exhausted. Nothing billed
- Retry
- Once
- Status
- 500
- Type
api_error- Code
deadline_exceeded- Situation
- The request's own time bound ended it;
x-should-retry: false. Nothing billed - Retry
- Not unchanged
Related sheets
- Sheet
- 18 of 20
- Detail
- J
- Updated
- 2026-11-16