Docs menu

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

MethodPathWhat it does
POST/v1/images/generationsCreates images from a text prompt (JSON body)
POST/v1/images/editsChanges 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
FieldRequiredWhat Cent AI does with it
modelyesAn image model that generates. A chat model or an unknown name returns 404 model_not_found
promptyesSent to the model as is
nnoNumber of images, default 1. The hold covers n images (see Cost)
sizenoSent as is, for example 1024x1024. A size the model refuses comes back as the model's error
response_formatnoLeave 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
PartRequiredWhat Cent AI does with it
modelyesAn image model that edits, for example hunyuan-image-alpha-edit
promptyesSent to the model as is
imageyesOne file: PNG, JPEG, WebP or GIF. A second image returns 400
masknoOne file in the same formats
n, size and other text partsnoSent 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"}
}
FieldMeaning
idThe result id, img_ plus 26 characters. Use it with GET /v1/images/{id}
data[].b64_jsonThe image, base64. The model's own link is never passed on
usage.costWhat 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"}'
RuleDetail
Answer202 Accepted with Location: /v1/images/{id}, X-Cent-Image-Id, and Preference-Applied: respond-async
ChecksThe key, model, body, and balance are checked first; a problem returns the usual error status and nothing runs
ResultPoll GET /v1/images/{id}, every few seconds, until status is completed or failed
CostCharged once the image is stored, only for the images stored. A failed image costs nothing
RetriesA 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>
RuleDetail
Statusin_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 longResults are kept for 24 hours, then deleted. After that the id returns 404 not_found
Linkdata[].url is a signed link that works for 10 minutes; ask again for a new one
WhoOnly keys of the account that made the image. Any other key gets 404 not_found
CostFree; 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 (unit image): a fixed price for each image you receive.
  • Per token (unit 1m_input_tokens and 1m_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 show approx_per_image, the cost of one 1K image from a short prompt, with its assumption in approx_assumption. A request with neither area nor size is sent with area 1K.
StepWhat happens to your balance
Before the model is calledThe 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 arriveOnly the images you receive are charged; the rest of the hold is released
The request failsThe 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

StatusCodeWhen
400invalid_requestMissing model or prompt, response_format url, a JSON body on edits, a file that is not an image, two images
400upstream_errorThe model refused the request, for example a size it does not support. Not charged
402insufficient_balanceThe balance does not cover the hold
403policy_violationThe model's own moderation refused the prompt as a policy violation. Not charged
404model_not_foundUnknown model, or a chat model on an image endpoint
413request_too_largeThe body is over 32 MiB
503upstream_timeout, upstream_unavailableThe 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

  • modelstringrequired

  • nintegeroptional

    Number of images; no limit of its own beyond what the model accepts.

  • promptstringrequired

    Must not be empty.

  • response_format"b64_json"optional

    Only b64_json is served; url is a 400.

  • sizestringoptional

    Passed to the model, for example 1024x1024; a size the model refuses is a 400.

Responses

  • 200The images as base64, or an error object 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 error object 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.