Skip to main content
POST
/
v1
/
images
/
generations
curl --request POST \
  --url https://toapis.com/v1/images/generations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "gpt-image-1.5-official",
    "prompt": "Blend these two references into a cyberpunk illustrated poster",
    "image_urls": [
      "https://example.com/input-a.png",
      "https://example.com/input-b.png"
    ],
    "size": "1:1",
    "quality": "high",
    "n": 1
  }'

{
  "id": "tsk_img_01KPTXXXXXXXXXXXXXXX",
  "object": "generation.task",
  "model": "gpt-image-1.5-official",
  "status": "queued",
  "progress": 0,
  "created_at": 1703884800,
  "metadata": {}
}

Documentation Index

Fetch the complete documentation index at: https://docs.toapis.com/llms.txt

Use this file to discover all available pages before exploring further.

  • Uses the same /v1/images/generations endpoint as text-to-image generation
  • Editing mode is triggered automatically when image_urls is included in the request
  • Supports multi-reference blending (up to 16 images) and mask-based inpainting
  • Reference images must be publicly accessible PNG / JPG, max 50MB each
Image editing is fully compatible with the generation API: simply add image_urls (and optionally mask_url) to your generation request — no endpoint switch required.

​
Authorizations

​
Authorization
string
required
All endpoints require Bearer Token authenticationGet your API Key from the API Key Management Page
Authorization: Bearer YOUR_API_KEY

​
Body

​
model
string
default:"gpt-image-1.5-official"
required
Use gpt-image-1.5-official
​
prompt
string
required
Describe the desired editExample: "Replace the background with a starry sky, keep the subject unchanged"
​
image_urls
string[]
required
Reference image URL array (the field that triggers editing mode)
  • Maximum 16 images
  • Must be publicly accessible stable URLs (PNG / JPG, max 50MB each)
  • Use the Upload Image API to get URLs for local files
​
mask_url
string
Mask image URL for inpainting
  • Must be PNG format with an Alpha channel
  • Transparent areas (alpha = 0) will be repainted; opaque areas are preserved
  • Must match the dimensions of the first reference image
​
size
string
default:"1:1"
Output aspect ratioSupports 13 ratios or auto:1:1 · 3:2 · 2:3 · 4:3 · 3:4 · 5:4 · 4:5 · 16:9 · 9:16 · 2:1 · 1:2 · 21:9 · 9:21
​
resolution
string
default:"1k"
Resolution tier: 1k / 2k / 4k4K only supports 6 ratios: 16:9 / 9:16 / 2:1 / 1:2 / 21:9 / 9:21
​
quality
string
default:"high"
Image quality: low / medium / high
​
n
integer
default:1
Number of images to generate, range 1 ~ 10
​
output_format
string
default:"png"
Output format: png / jpeg
Azure OpenAI does not support webp format.
​
output_compression
integer
default:100
JPEG compression level, range 0–100 (only applies when output_format is "jpeg")

​
Response

​
id
string
Unique task identifier for status queries
​
object
string
Always generation.task
​
status
string
Task status: queued / in_progress / completed / failed
​
progress
integer
Task progress percentage (0-100)
​
created_at
integer
Task creation timestamp (Unix timestamp)
curl --request POST \
  --url https://toapis.com/v1/images/generations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "gpt-image-1.5-official",
    "prompt": "Blend these two references into a cyberpunk illustrated poster",
    "image_urls": [
      "https://example.com/input-a.png",
      "https://example.com/input-b.png"
    ],
    "size": "1:1",
    "quality": "high",
    "n": 1
  }'

{
  "id": "tsk_img_01KPTXXXXXXXXXXXXXXX",
  "object": "generation.task",
  "model": "gpt-image-1.5-official",
  "status": "queued",
  "progress": 0,
  "created_at": 1703884800,
  "metadata": {}
}