Docs / API
Images
POST /v1/images/generations and /v1/images/edits in the OpenAI Images format, priced per image or per token, plus GET /v1/images/{id} to fetch a result again.
Last updated
Endpoints
| Method | Path | What it does |
|---|---|---|
| POST | /v1/images/generations | Creates images from a text prompt (JSON body) |
| POST | /v1/images/edits | Changes one image you upload, guided by a prompt (multipart/form-data) |
| GET | /v1/images/{id} | Returns a result again for 24 hours, as a short-lived link |
The endpoints follow the OpenAI Images format. Point an OpenAI SDK at the base URL https://api.cent-ai.dev/v1 and call images.generate or images.edit.
Image models are listed in GET /v1/models with their prices in pricing.variants, and on the model pages. Which endpoint a model serves: hunyuan-image-alpha generates and hunyuan-image-alpha-edit edits; qwen-image-3.0-pro, wan2.7-image and wan2.7-image-pro generate and edit; minimax-h3-image generates only and is priced per token, with an approximate price per image on its model page. Images from the two Hunyuan models carry a small text watermark that the model adds; Cent AI does not add or remove it.
Generate an image
Request
POST https://api.cent-ai.dev/v1/images/generations
Authorization: Bearer cai_<secret>
Content-Type: application/json
| Field | Required | What Cent AI does with it |
|---|---|---|
model | yes | An image model that generates. A chat model or an unknown name returns 404 model_not_found |
prompt | yes | Sent to the model as is |
n | no | Number of images, default 1. The hold covers n images (see Cost) |
size | no | Sent as is, for example 1024x1024. A size the model refuses comes back as the model's error |
response_format | no | Leave it out or send b64_json. url returns 400 invalid_request |
Other fields are passed to the model unchanged. Cent AI adds no content filter of its own; a prompt the model refuses returns its error (400 upstream_error or 403 policy_violation) and is not charged.
Example
curl https://api.cent-ai.dev/v1/images/generations \
-H "Authorization: Bearer $CENT_AI_KEY" \
-H "Content-Type: application/json" \
--max-time 630 \
-d '{"model":"hunyuan-image-alpha","prompt":"A lighthouse at dawn, watercolor","size":"1024x1024"}'
Edit an image
Request
POST https://api.cent-ai.dev/v1/images/edits
Authorization: Bearer cai_<secret>
Content-Type: multipart/form-data
| Part | Required | What Cent AI does with it |
|---|---|---|
model | yes | An image model that edits, for example hunyuan-image-alpha-edit |
prompt | yes | Sent to the model as is |
image | yes | One file: PNG, JPEG, WebP or GIF. A second image returns 400 |
mask | no | One file in the same formats |
n, size and other text parts | no | Sent to the model as is |
The body must be multipart/form-data, the way the OpenAI SDKs send it; a JSON body returns 400 invalid_request. The whole body may be up to 32 MiB; a larger one returns 413 request_too_large. The model may return a different size than the one you ask for.
Example
curl https://api.cent-ai.dev/v1/images/edits \
-H "Authorization: Bearer $CENT_AI_KEY" \
--max-time 630 \
-F model=hunyuan-image-alpha-edit \
-F prompt="Make the sky orange" \
-F image=@photo.png
Response
Both endpoints answer the same way:
{
"id": "img_01JC8Z3V6Q4N2T7R5W9X0Y1A2B",
"created": 1792051200,
"data": [{"b64_json": "iVBORw0KGgo…"}],
"usage": {"cost": "0.150000000"}
}
| Field | Meaning |
|---|---|
id | The result id, img_ plus 26 characters. Use it with GET /v1/images/{id} |
data[].b64_json | The image, base64. The model's own link is never passed on |
usage.cost | What this request cost in USD, 9 decimals, the same amount as on your Requests page |
The values above show the shape; the prices are on the model page.
Waiting for the image
An image can take several minutes. Cent AI waits for the model up to 600 seconds.
- When the model answers within 15 seconds, you get the normal status: 200 with the image, or the error status.
- After 15 seconds Cent AI sends status 200 with
Content-Type: application/json, then one space every 15 seconds until the JSON body. Spaces before JSON are valid, so the OpenAI SDKs and JSON parsers read the body as usual. The spaces keep proxies from closing an idle connection. - If the request fails after that status was sent, the status stays 200 and the body is an error:
{"error": {"message": "The model did not respond in time. Try again shortly.", "type": "server_error", "param": null, "code": "upstream_timeout"}}
Check for error, or for a missing data, before you read data. A failed request is never charged.
Set your client timeout to at least 630 seconds: timeout=630 in the Python SDK, timeout: 630_000 in the Node SDK, --max-time 630 for curl.
If the connection drops
A long open connection can be cut on the way, by your network or a proxy, while the image is still being made. Every answer to an accepted request carries the header X-Cent-Image-Id with the image id, from the first byte. If the cut happens on the way, for example a proxy timeout, while Cent AI still finishes the image, GET /v1/images/{id} returns it for 24 hours (see below). If the disconnect reaches Cent AI before the image is ready, the request stops, nothing is charged, and GET answers failed. For images that take minutes, use async mode. Sending the same request again makes and charges a new image.
Async mode
Add the header Prefer: respond-async to POST /v1/images/generations or /v1/images/edits to get the id at once instead of waiting on an open connection:
curl -i https://api.cent-ai.dev/v1/images/generations \
-H "Authorization: Bearer $CENT_AI_KEY" \
-H "Content-Type: application/json" \
-H "Prefer: respond-async" \
-d '{"model": "hunyuan-image-alpha", "prompt": "a red bicycle by a white wall"}'
| Rule | Detail |
|---|---|
| Answer | 202 Accepted with Location: /v1/images/{id}, X-Cent-Image-Id, and Preference-Applied: respond-async |
| Checks | The key, model, body, and balance are checked first; a problem returns the usual error status and nothing runs |
| Result | Poll GET /v1/images/{id}, every few seconds, until status is completed or failed |
| Cost | Charged once the image is stored, only for the images stored. A failed image costs nothing |
| Retries | A second POST is a new image and a new charge; to check on a request, use GET with its id |
Without the header the answer is synchronous as above, which is what the OpenAI SDKs expect. An answer of 200 without Preference-Applied ran synchronously: read its body as above.
Image status and result
GET https://api.cent-ai.dev/v1/images/img_01JC8Z3V6Q4N2T7R5W9X0Y1A2B
Authorization: Bearer cai_<secret>
| Rule | Detail |
|---|---|
| Status | in_progress while the image is being made, then completed with data and usage, or failed with the error code and message of the failed answer |
| How long | Results are kept for 24 hours, then deleted. After that the id returns 404 not_found |
| Link | data[].url is a signed link that works for 10 minutes; ask again for a new one |
| Who | Only keys of the account that made the image. Any other key gets 404 not_found |
| Cost | Free; the normal rate limit of the key applies |
Use it after async mode, or when the connection dropped before the body arrived.
Cost
Image models are not included in budget packs. Each one is priced in one of two ways, shown in pricing.variants:
- Per image (
unitimage): a fixed price for each image you receive. - Per token (
unit1m_input_tokensand1m_output_tokens): rates per 1M text input, image input, and output tokens, billed from the tokens the model reports for each request. Only the output of images you receive is charged. These models also showapprox_per_image, the cost of one 1K image from a short prompt, with its assumption inapprox_assumption. A request with neitherareanorsizeis sent witharea1K.
| Step | What happens to your balance |
|---|---|
| Before the model is called | The most the request can cost is held: the price times n for a per-image model; for a per-token model, the most output tokens per image for the requested area times n, plus the most input tokens. Too little balance returns 402 insufficient_balance and the model is not called |
| The images arrive | Only the images you receive are charged; the rest of the hold is released |
| The request fails | The hold is released in full; the request costs nothing |
The charge is in usage.cost and on the Requests page of the dashboard. See Request cost.
Errors
| Status | Code | When |
|---|---|---|
| 400 | invalid_request | Missing model or prompt, response_format url, a JSON body on edits, a file that is not an image, two images |
| 400 | upstream_error | The model refused the request, for example a size it does not support. Not charged |
| 402 | insufficient_balance | The balance does not cover the hold |
| 403 | policy_violation | The model's own moderation refused the prompt as a policy violation. Not charged |
| 404 | model_not_found | Unknown model, or a chat model on an image endpoint |
| 413 | request_too_large | The body is over 32 MiB |
| 503 | upstream_timeout, upstream_unavailable | The model did not answer in 600 seconds, or no image came back. Not charged |
After the first 15 seconds these errors arrive with status 200, as shown above. See Errors.
Contract
POST/v1/images/generations
Image generation (OpenAI Images format)
Auth · API key (Bearer or x-api-key)
Request body
modelstringrequirednintegeroptionalNumber of images; no limit of its own beyond what the model accepts.
promptstringrequiredMust not be empty.
response_format"b64_json"optionalOnly b64_json is served; url is a 400.
sizestringoptionalPassed to the model, for example 1024x1024; a size the model refuses is a 400.
Responses
- 200The images as base64, or an
errorobject when the request failed after the early 200 header. - 202Accepted with
Prefer: respond-async; the image is made and billed in the background. - 400Error in the OpenAI shape.
- 401Error in the OpenAI shape.
- 402Error in the OpenAI shape.
- 403Error in the OpenAI shape.
- 404Error in the OpenAI shape.
- 413Error in the OpenAI shape.
- 429Error in the OpenAI shape that may be retried after Retry-After.retry
- 500Error in the OpenAI shape.
- 501The endpoint is not open yet; not billed and the model is never called.
- 503Error in the OpenAI shape that may be retried after Retry-After.retry
Response headers
LocationPreference-AppliedRetry-AfterX-Cent-Image-Idx-request-id
POST/v1/images/edits
Image editing (OpenAI Images format)
Auth · API key (Bearer or x-api-key)
Responses
- 200The images as base64, or an
errorobject when the request failed after the early 200 header. - 202Accepted with
Prefer: respond-async; the image is made and billed in the background. - 400Error in the OpenAI shape.
- 401Error in the OpenAI shape.
- 402Error in the OpenAI shape.
- 403Error in the OpenAI shape.
- 404Error in the OpenAI shape.
- 413Error in the OpenAI shape.
- 429Error in the OpenAI shape that may be retried after Retry-After.retry
- 500Error in the OpenAI shape.
- 501The endpoint is not open yet; not billed and the model is never called.
- 503Error in the OpenAI shape that may be retried after Retry-After.retry
Response headers
LocationPreference-AppliedRetry-AfterX-Cent-Image-Idx-request-id
GET/v1/images/{id}
Image status and result
Auth · API key (Bearer or x-api-key)
Responses
- 200The request's status, with the stored images once completed.
- 401Error in the OpenAI shape.
- 404Error in the OpenAI shape.
- 429Error in the OpenAI shape that may be retried after Retry-After.retry
- 501The endpoint is not open yet; not billed and the model is never called.
- 503Error in the OpenAI shape that may be retried after Retry-After.retry
Response headers
Retry-Afterx-request-id
Generated from the OpenAPI contract.