GPT Image 2

OpenAI GPT Image 2 image generation. Publicly, use a single model id: gpt-image-2. It supports both prompt-only generation and reference-image editing.

Model

Model Name	Output	Mode
`gpt-image-2`	Image URLs	Text-to-image, image-to-image

Pricing

Priced per output resolution tier:

Resolution	Credits	Price
`1k` (default)	4.7 credits	$0.0235
`2k`	9.4 credits	$0.047
`4k`	14.1 credits	$0.0705

Create Task

curl -X POST https://api.aivideoapi.ai/v1/images/generations \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "callback_url": "https://your-server.com/webhook",
    "input": {
      "prompt": "Turn this product photo into a clean studio shot on a white background",
      "image_urls": [
        "https://example.com/source.png"
      ],
      "aspect_ratio": "1:1",
      "nsfw_checker": true
    }
  }'

Request Body

Field	Type	Required	Description
`model`	string	Yes	Must be `gpt-image-2`
`input`	object	Yes	Generation parameters, see below
`callback_url`	string	No	Optional callback URL for completion/failure notifications

Input Parameters

Field	Type	Required	Description
`prompt`	string	Conditionally	Prompt text, max 20,000 characters
`image_urls`	string[]	Conditionally	Reference image URLs for editing. Maximum 16 images.
`aspect_ratio`	string	No	Output image aspect ratio, defaults to `auto`. One of: `auto`, `1:1`, `3:2`, `2:3`, `4:3`, `3:4`, `5:4`, `4:5`, `16:9`, `9:16`, `2:1`, `1:2`, `3:1`, `1:3`, `21:9`, `9:21`; you may also pass an explicit pixel size (e.g. `1881x836`, `887x1774`). `auto` is treated as `1:1`. See Size & Resolution for the exact pixels of each tier.
`resolution`	string	No	Output resolution tier, defaults to `1k`. One of: `1k`, `2k`, `4k`. Combined with `aspect_ratio` it determines the actual pixels — see Size & Resolution.
`nsfw_checker`	boolean	No	Safety check toggle, defaults to `true`

At least one of prompt or image_urls must be provided.

Size & Resolution

aspect_ratio sets the ratio (or an explicit pixel size) and resolution sets the tier (1k / 2k / 4k). Their combination maps to the following actual pixels. 4k supports all 15 ratios; aspect_ratio=auto is treated as 1:1.

Ratio	1k	2k	4k
`1:1`	1024×1024 / 1254×1254	2048×2048	2880×2880
`3:2`	1536×1024	2048×1360	3520×2336
`2:3`	1024×1536	1360×2048	2336×3520
`4:3`	1024×768	2048×1536	3312×2480
`3:4`	768×1024	1536×2048	2480×3312
`5:4`	1280×1024 / 1448×1086	2560×2048	3216×2576
`4:5`	1024×1280 / 1122×1402	2048×2560	2576×3216
`16:9`	1536×864 / 1672×941	2048×1152	3840×2160
`9:16`	864×1536 / 941×1672	1152×2048	2160×3840
`2:1`	2048×1024 / 1774×887	2688×1344	3840×1920
`1:2`	1024×2048 / 887×1774	1344×2688	1920×3840
`3:1`	1881×836 / 1536×512	3072×1024	3840×1280
`1:3`	887×1774 / 512×1536	1024×3072	1280×3840
`21:9`	2016×864 / 1915×821	2688×1152	3840×1648
`9:21`	864×2016 / 821×1915	1152×2688	1648×3840

You can also pass any pixel size from the table above directly via aspect_ratio (e.g. 1881x836 / 887x1774).

Example: Text-to-Image

curl -X POST https://api.aivideoapi.ai/v1/images/generations \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "callback_url": "https://your-server.com/webhook",
    "input": {
      "prompt": "A cinematic night city poster with neon reflections on a rainy street.",
      "aspect_ratio": "16:9",
      "nsfw_checker": true
    }
  }'

Example: Image-to-Image

curl -X POST https://api.aivideoapi.ai/v1/images/generations \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "callback_url": "https://your-server.com/webhook",
    "input": {
      "prompt": "Convert this room into a warm Scandinavian interior design render",
      "image_urls": [
        "https://example.com/room.jpg"
      ],
      "aspect_ratio": "3:2"
    }
  }'

Example: 4K Output

curl -X POST https://api.aivideoapi.ai/v1/images/generations \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "callback_url": "https://your-server.com/webhook",
    "input": {
      "prompt": "An ancient castle under a starry sky, cinematic composition",
      "aspect_ratio": "16:9",
      "resolution": "4k"
    }
  }'

Response

{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "397ce9f2-c04e-4244-ac33-3af19a7cc297"
  }
}

Query Task

curl https://api.aivideoapi.ai/v1/tasks/{taskId} \
  -H "Authorization: Bearer sk-your-api-key"

Status flow: pending -> processing -> completed or failed.

Completed

{
  "id": "397ce9f2-c04e-4244-ac33-3af19a7cc297",
  "status": "completed",
  "model": "gpt-image-2",
  "created_at": 1775383908,
  "completed_at": 1775383910,
  "output": {
    "urls": [
      "https://file.aivideoapi.ai/images/2026/04/05/abc123.png"
    ],
    "metadata": {
      "model": "gpt-image-2-image-to-image",
      "costTime": 70
    }
  }
}

Failed

{
  "id": "57c8772c-f834-46f3-9b7d-81f92e104050",
  "status": "failed",
  "model": "gpt-image-2",
  "created_at": 1775383908,
  "error": {
    "code": "upstream_error",
    "message": "Generation failed"
  }
}

Failed tasks are automatically refunded.

Callback Notifications

Pass callback_url when creating the task. When the task completes or fails, we send a POST request whose payload matches the GET /v1/tasks/{taskId} response.

Error Codes

When a request fails, the API returns a JSON error response:

{
  "error": {
    "code": "insufficient_credits",
    "message": "Your credit balance is too low. Please top up.",
    "type": "billing_error"
  }
}

Error Reference

HTTP Status	Code	Type	Description
400	`invalid_request`	invalid_request_error	Missing or invalid parameters
401	`invalid_api_key`	authentication_error	API key is invalid, disabled, or deleted
402	`insufficient_credits`	billing_error	Credit balance too low, please top up
403	`ip_not_allowed`	permission_error	Request IP not in the key's allowlist
404	`model_not_found`	invalid_request_error	Model does not exist or is inactive
404	`task_not_found`	invalid_request_error	Task ID does not exist
429	`rate_limit_exceeded`	rate_limit_error	Too many requests, please slow down
429	`spend_limit_exceeded`	billing_error	Key spend limit reached (hourly/daily/total)
500	`internal_error`	api_error	Unexpected server error
503	`upstream_error`	upstream_error	Upstream AI provider returned an error

Common Scenarios

invalid_request (400)

Returned when required fields are missing or invalid.

{
  "error": {
    "code": "invalid_request",
    "message": "'model' is required.",
    "type": "invalid_request_error"
  }
}

insufficient_credits (402)

Your balance is too low. Check your balance with GET /v1/credits and top up in Dashboard > Billing.

invalid_api_key (401)

Possible causes:

The key does not start with sk-
The key has been disabled or deleted
The user account has been banned

upstream_error (503)

The upstream AI provider returned an error. This may happen when:

The input contains sensitive or prohibited content
The provider is temporarily unavailable
The request parameters are not supported by the provider

Credits are automatically refunded when a task fails due to upstream errors.