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": "Ancient castle under the starry sky, cinematic lighting, hyper-realistic style",
    "size": "16:9",
    "resolution": "2k",
    "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.

  • Official OpenAI gpt-image-2 model, called via the gpt-image-1.5-official model name
  • Async processing — returns a task ID for subsequent polling
  • Supports text-to-image, multi-reference image-to-image, and mask-based inpainting
  • 13 aspect ratios with 1K / 2K / 4K resolution tiers
  • Up to 4 images per request, up to 16 reference images
Note: gpt-image-1.5-official does not support transparent backgrounds. Passing background: "transparent" will be silently downgraded to auto.

​
Authorizations

​
Authorization
string
required
All endpoints require Bearer Token authenticationGet your API Key from the API Key Management PageAdd to request header:
Authorization: Bearer YOUR_API_KEY

​
Body

​
model
string
default:"gpt-image-1.5-official"
required
Image generation model nameUse gpt-image-1.5-official
​
prompt
string
required
Text prompt describing the image to generateSupports English and Chinese; detailed descriptions of scene, style, and composition are recommended
​
size
string
default:"1:1"
Aspect ratioSupported values, or pass auto to let the server choose: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
4K tier only supports 6 ratios: 16:9 / 9:16 / 2:1 / 1:2 / 21:9 / 9:21. Use 2K for all other ratios.
​
resolution
string
default:"1k"
Resolution tier
  • 1k — 1024-base, fast and cost-effective (default)
  • 2k — 2048-base, suitable for posters and high-definition needs
  • 4k — 3840-base, only supports the 6 ratios above; high quality can take >120s

​
Size Reference Table

size1K2K4K
1:11024x10242048x2048Not supported
3:21536x10242048x1360Not supported
2:31024x15361360x2048Not supported
4:31024x7682048x1536Not supported
3:4768x10241536x2048Not supported
5:41280x10242560x2048Not supported
4:51024x12802048x2560Not supported
16:91536x8642048x11523840x2160
9:16864x15361152x20482160x3840
2:12048x10242688x13443840x1920
1:21024x20481344x26881920x3840
21:92016x8642688x11523840x1648
9:21864x20161152x26881648x3840
​
quality
string
default:"high"
Image quality
  • low — fast and economical, suitable for drafts/previews
  • medium — balanced speed and quality
  • high — maximum detail, default value (4K + high can take 120s+)
​
output_format
string
default:"png"
Output format
  • png — default
  • jpeg — smaller file size (supports compression)
Azure OpenAI does not support webp format.
​
output_compression
integer
default:100
JPEG compression level, range 0–100 (0 = no compression, 100 = maximum compression, default 100)Only applies when output_format is "jpeg"
​
n
integer
default:1
Number of images to generateRange: 1 ~ 10
​
image_urls
string[]
Reference image URL array for image-to-image generation
  • Maximum 16 images, must be publicly accessible stable URLs
  • Use the Upload Image API to upload local files and get URLs
​
mask_url
string
Mask image URL for inpaintingMust be used together with image_urls. The mask must match the dimensions of the first reference image and include an Alpha channel (transparent areas indicate regions to be repainted)

​
Response

​
id
string
Unique task identifier for status queries
​
object
string
Object type, always generation.task
​
model
string
Model name used
​
status
string
Task status
  • queued — waiting to be processed
  • in_progress — processing
  • completed — successfully completed
  • failed — 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": "Ancient castle under the starry sky, cinematic lighting, hyper-realistic style",
    "size": "16:9",
    "resolution": "2k",
    "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": {}
}