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": {}
}