General Image API

Generate or edit images synchronously with POST /v1/image. Omit images for text-to-image; provide images to edit with reference images. The response contains image URLs; there is no task to poll.

Endpoints and authentication

Operation	Method and path
Generate / edit image	POST /v1/image
Available image models	GET /v1/models?output_modalities=image

Requests use Authorization: Bearer <API_KEY> and application/json; responses are direct JSON objects.

BASE_URL="https://api.ope.ai"
API_KEY="YOUR_API_KEY"

curl "$BASE_URL/v1/models?output_modalities=image" \
  -H "Authorization: Bearer $API_KEY"

Request parameters

Field	Type	Required	Description
model	string	Yes	Model ID from the available model list
prompt	string	Yes	Image description; also the edit instruction when editing
images	object[]	No	Reference images applied in array order; omit for text-to-image. Each item is {"url": "..."}
n	integer	No	Upper bound on the number of outputs; the model decides the actual count and is not required to fill it
size	string	No	Output size as WIDTHxHEIGHT with a lowercase x, such as 1024x1024; 2K, 4K, and auto are not accepted
output_format	string	No	Output encoding, such as png, jpeg, or webp; support depends on the model
extra_parameters	object	No	Model-specific parameters, see below

images[].url accepts a publicly readable HTTP/HTTPS URL or a data:image/...;base64,... Data URL. Omit optional parameters you do not need; do not send null to mean omission.

extra_parameters

Field	Type	Description
quality	string	Output quality level; values depend on the model
mask	object	Edit mask as {"url": "..."}; requires images and applies to the first reference image
background	string	Background control; support depends on the model

Results are always delivered as image URLs; response_format is not accepted.

Text-to-image

The example model ID is qwen-image-2.0; replace it with an actual ID from the model list.

curl "$BASE_URL/v1/image" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
    "model": "qwen-image-2.0",
    "prompt": "Product photo of a white ceramic teapot, soft side light, crisp details.",
    "size": "1024x1024"
  }'

Edit with a reference image

curl "$BASE_URL/v1/image" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
    "model": "qwen-image-2.0",
    "prompt": "Keep the product, replace the background with a light gray studio.",
    "images": [{"url": "https://example.com/input.png"}],
    "size": "1024x1024"
  }'

Multiple reference images

curl "$BASE_URL/v1/image" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
    "model": "qwen-image-2.0",
    "prompt": "Combine the furniture from both references into one living room scene.",
    "images": [
      {"url": "https://example.com/sofa.png"},
      {"url": "https://example.com/lamp.png"}
    ],
    "n": 2,
    "size": "1536x1024"
  }'

Response

A successful request returns HTTP 200:

{
  "created": 1791000000,
  "model": "qwen-image-2.0",
  "data": [
    {
      "index": 0,
      "url": "https://media.example.com/generated/8f3c1d.png",
      "mime_type": "image/png",
      "width": 1024,
      "height": 1024
    }
  ],
  "usage": {
    "input_tokens": 24,
    "output_tokens": 1152,
    "total_tokens": 1176,
    "output_images": 1
  }
}

Field	Description
created	Completion time, Unix seconds
model	Requested model ID
data[]	Output items, index numbered from 0
data[].url	Image URL, valid for 24 hours after generation; download promptly
data[].mime_type, width, height	Actual output type and size
data[].error	Present when that item failed, with code, type, and message
usage	Actual usage; omitted when the model returns none

A single request can partially succeed: successful items carry url, failed items carry error, and no placeholder items are added for images that were not generated. 200 is returned only when at least one image succeeded.

Errors

{"error":{"code":"invalid_request","type":"invalid_request_error","message":"size must be WIDTHxHEIGHT","param":"size"}}

param points to the field to fix. Common HTTP statuses: 400 invalid parameters, 401/403 authentication or permission issues, 402 insufficient quota, 404 model not found, 413 request too large, 429 rate limited, 500/503 service error or temporarily unavailable, 504 timeout. The X-Request-ID response header helps when reporting an issue.

Calling limits

• Synchronous only: no async tasks, task queries, streaming, callbacks, or cancellation.
• One request performs one generation; do not repeat requests to wait for a result.
• Image URLs are kept for 24 hours; regenerate after they expire, and download images you need to keep.