ToAPIsToAPIs
GPT-Image-2

GPT-Image-2 Official Channel 画像生成

Generate images with the official OpenAI gpt-image-2-official model — text-to-image, image-to-image, and inpainting (mask) in one API, with 1K / 2K / 4K resolution tiers

POST
/v1/images/generations

中国本土のユーザー向け: 中国本土のユーザーは https://toapis.cn を API エンドポイント(Base URL)としてご利用ください。本ドキュメント内の例では https://toapis.com を https://toapis.cn に置き換えてください。

  • Official OpenAI gpt-image-2-official model
  • 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

Authorizations

Authorizationstringヘッダー必須

All endpoints require Bearer Token authentication

Get your API Key from the API Key Management Page

Add to request header:

Authorization: Bearer YOUR_API_KEY

Body

modelstringボディ必須デフォルト: gpt-image-2-official

Image generation model name

Use gpt-image-2-official

promptstringボディ必須

Text prompt describing the image to generate

Supports English and Chinese; detailed descriptions of scene, style, and composition are recommended

sizestringボディデフォルト: 1:1

Aspect ratio

Preset values, or pass auto to let the upstream provider 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

You may also pass any ratio in width:height format, such as 1:3 or 7:4, subject to the custom-size limits below.

With auto, the upstream provider determines the final aspect ratio and pixel dimensions, so a fixed output is not guaranteed.

resolutionstringボディデフォルト: 1k

Resolution tier

  • 1k — 1024-base, fast and cost-effective (default)
  • 2k — 2048-base, suitable for posters and high-definition needs
  • 4k — 3840-base; high quality can take more than 120 seconds

Size Reference Table

size1K2K4K
1:11024x10242048x20482880x2880
3:21536x10242048x13603520x2336
2:31024x15361360x20482336x3520
4:31024x7682048x15363312x2480
3:4768x10241536x20482480x3312
5:41280x10242560x20483216x2576
4:51024x12802048x25602576x3216
16:91536x8642048x11523840x2160
9:16864x15361152x20482160x3840
2:12048x10242688x13443840x1920
1:21024x20481344x26881920x3840
21:92016x8642688x11523840x1648
9:21864x20161152x26881648x3840

Custom Resolutions

In addition to the presets above, pass any ratio in width:height format through size. The service calculates pixel dimensions from the selected resolution tier. The resulting dimensions must meet all of these limits:

  • Both sides must be multiples of 16 pixels
  • The long edge can be at most 3,840 pixels (4K)
  • The aspect ratio can be at most 3:1
  • Total pixel count must be between 655,360 and 8,294,400

Examples:

  • size: "1:3" with resolution: "2k" → 1024x3072
  • size: "7:4" with resolution: "1k" → 1344x768
curl --request POST \
  --url https://toapis.com/v1/images/generations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "gpt-image-2-official",
    "prompt": "A simple red circle on a white background",
    "size": "7:4",
    "resolution": "1k",
    "quality": "medium",
    "n": 1
  }'
qualitystringボディデフォルト: 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+)
backgroundstringボディデフォルト: auto

生成画像の背景

  • auto — モデルが自動で決定(デフォルト)
  • transparent — 透明背景
  • opaque — 不透明背景
透明背景は PNG 出力との組み合わせを推奨します。
output_formatstringボディデフォルト: png

Output format

  • png — default
  • jpeg — smaller file size (supports compression)
Azure OpenAI does not support webp format.
output_compressionintegerボディデフォルト: 100

JPEG compression level, range 0–100 (0 = no compression, 100 = maximum compression, default 100)

Only applies when output_format is "jpeg"

nintegerボディデフォルト: 1

Number of images to generate

Range: 1 ~ 10

image_urlsstring[]ボディ

Reference image URL array for image-to-image generation

  • Maximum 16 images, must be publicly accessible stable URLs
  • Use the Upload 画像API to upload local files and get URLs
mask_urlstringボディ

Mask image URL for inpainting

Must 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)

レスポンス

idstring

Unique task identifier for status queries

objectstring

Object type, always generation.task

modelstring

モデル name used

statusstring

Task status

  • queued — waiting to be processed
  • in_progress — processing
  • completed — successfully completed
  • failed — failed
progressinteger

Task progress percentage (0-100)

created_atinteger

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-2-official",
    "prompt": "Ancient castle under the starry sky, cinematic lighting, hyper-realistic style",
    "size": "16:9",
    "resolution": "2k",
    "quality": "high",
    "n": 1
  }'
curl --request POST \
  --url https://toapis.com/v1/images/generations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "gpt-image-2-official",
    "prompt": "Snowy mountain sunrise panorama, extreme detail",
    "size": "16:9",
    "resolution": "4k",
    "quality": "high",
    "output_format": "jpeg",
    "output_compression": 90
  }'
curl --request POST \
  --url https://toapis.com/v1/images/generations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "gpt-image-2-official",
    "prompt": "Merge these two reference images into an illustrated poster, preserving the subject outlines",
    "size": "1:1",
    "quality": "high",
    "image_urls": [
      "https://example.com/input-a.png",
      "https://example.com/input-b.png"
    ]
  }'
curl --request POST \
  --url https://toapis.com/v1/images/generations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "gpt-image-2-official",
    "prompt": "Replace the background with a desert sunset",
    "size": "1:1",
    "quality": "medium",
    "image_urls": ["https://example.com/photo.png"],
    "mask_url": "https://example.com/mask.png"
  }'
const response = await fetch('https://toapis.com/v1/images/generations', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer your-ToAPIs-key',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    model: 'gpt-image-2-official',
    prompt: 'Ancient castle under the starry sky, cinematic lighting, hyper-realistic style',
    size: '16:9',
    resolution: '2k',
    quality: 'high',
    n: 1
  })
});

const task = await response.json();
console.log(task.id, task.status);

レスポンス例

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