# GPT Image 2 API Documentation

> Generate videos with the GPT Image 2 model through the AI Studio API.

## Overview

Use the AI Studio API to create GPT Image 2 generation tasks and query their status. The flow is asynchronous: create a task first, then poll the task endpoint with the returned `taskId`.

## Authentication

All requests require an API key in the `Authorization` header.

```http
Authorization: Bearer YOUR_API_KEY
```

## Available models

| modelId | Version | Provider | Runtime model |
| --- | --- | --- | --- |
| `image:gpt-image-2-text-to-image` | Text to Image | GPT Image-2 | gpt-image-2-text-to-image |
| `image:gpt-image-2-image-to-image` | Image to Image | GPT Image 2 | gpt-image-2-image-to-image |
| `image:ama-gpt-image-2` | Gpt image 2 Special offer | GPT-Image-2 | gpt-image-2 |
| `image:fal-openai-gpt-image-2` | Gpt image 2 | OpenAI | openai/gpt-image-2 |
| `image:fal-openai-gpt-image-2-edit` | Gpt image 2 edit | OpenAI | openai/gpt-image-2/edit |
| `image:fal-fal-ai-gpt-image-1-5` | GPT Image 1.5 | gpt-image-1.5 | fal-ai/gpt-image-1.5 |
| `image:fal-fal-ai-gpt-image-1-5-edit` | GPT Image 1.5 Edit | gpt-image-1.5 | fal-ai/gpt-image-1.5/edit |

## 1. Create generation task

### Endpoint

```http
POST https://localhost:3000/api/ai-studio/execute
Content-Type: application/json
Authorization: Bearer YOUR_API_KEY
```

### Request example

```json
{
  "modelId": "image:gpt-image-2-text-to-image",
  "isPublic": true,
  "payload": {
    "model": "gpt-image-2-text-to-image",
    "input": {
      "prompt": "A cinematic night city poster with neon reflections on a rainy street.",
      "aspect_ratio": "auto"
    }
  }
}
```

### Success response

```json
{
  "success": true,
  "data": {
    "modelId": "image:gpt-image-2-text-to-image",
    "generationId": "generation-id",
    "reservedCredits": 20,
    "taskId": "provider-task-id",
    "state": "queued"
  }
}
```

## 2. Query task status

### Endpoint

```http
GET https://localhost:3000/api/ai-studio/tasks/{taskId}
Authorization: Bearer YOUR_API_KEY
```

### Success response

```json
{
  "success": true,
  "data": {
    "generationId": "generation-id",
    "taskId": "provider-task-id",
    "modelId": "image:gpt-image-2-text-to-image",
    "state": "succeeded",
    "mediaUrls": [
      "https://example.com/result.mp4"
    ],
    "reservedCredits": 20,
    "refundedCredits": 0
  }
}
```

## Request fields

### Text to Image

#### Payload fields

| Field | Type | Required | Default / Example | Options | Description |
| --- | --- | --- | --- | --- | --- |
| `model` | enum | Yes | `"gpt-image-2-text-to-image"` | gpt-image-2-text-to-image | The model name used for generation. This field is required. This endpoint must use the `gpt-image-2-text-to-image` model. |
| `input` | object | Yes | `-` | - | Input parameters for the text-to-image task. |

#### Input fields

| Field | Type | Required | Default / Example | Options | Description |
| --- | --- | --- | --- | --- | --- |
| `prompt` | string | Yes | `"A cinematic night city poster with neon reflections on a rainy street."` | - | Text prompt. Required, maximum 20,000 characters. |
| `aspect_ratio` | enum | No | `-` | 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 | The aspect ratio of the generated image is set to auto by default.<br>Note: for 2K and 4K resolution, the following aspect ratios are not supported: 5:4, 4:5, 3:1, 1:3, and 9:21. |
| `resolution` | enum | No | `-` | 1K, 2K, 4K | Image resolution: Note: Images with a 1:1 aspect ratio cannot be converted to 4K images. Images with the aspect ratio set to "auto" or without a specified aspect ratio parameter will only be converted to 1K images; otherwise, the task will fail to create. |

### Image to Image

#### Payload fields

| Field | Type | Required | Default / Example | Options | Description |
| --- | --- | --- | --- | --- | --- |
| `model` | enum | Yes | `"gpt-image-2-image-to-image"` | gpt-image-2-image-to-image | The model name used for generation. This field is required. This endpoint must use the `gpt-image-2-image-to-image` model. |
| `input` | object | Yes | `-` | - | Input parameters for the image-to-image task. |

#### Input fields

| Field | Type | Required | Default / Example | Options | Description |
| --- | --- | --- | --- | --- | --- |
| `prompt` | string | Yes | `"Transform this product image into a premium e-commerce poster style."` | - | Text prompts, up to 20,000 characters. |
| `input_urls` | string[] | Yes | `["https://example.com/"]` | - | Array of input image URLs. |
| `aspect_ratio` | enum | No | `-` | 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 | The aspect ratio of the generated image is set to auto by default.<br>Note: 5:4 and 4:5 aspect ratios only support 1K images. |
| `resolution` | enum | No | `-` | 1K, 2K, 4K | Image resolution: Note: Images with a 1:1 aspect ratio cannot be converted to 4K images. Images with the aspect ratio set to "auto" or without a specified aspect ratio parameter will only be converted to 1K images; otherwise, the task will fail to create. |

### Gpt image 2 Special offer

#### Payload fields

| Field | Type | Required | Default / Example | Options | Description |
| --- | --- | --- | --- | --- | --- |
| `model` | enum | Yes | `"gpt-image-2"` | gpt-image-2 | Image generation model name. Fixed to gpt-image-2. |
| `prompt` | string | Yes | `-` | - | Text description for image generation. Supports English and Chinese; detailed descriptions are recommended. Prompts are moderated before submission. |
| `size` | enum | No | `"1:1"` | 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 | Image aspect ratio, or a direct pixel size such as 1881x836 / 887x1774. Use auto to let the server select a ratio; auto defaults to 1:1. |
| `resolution` | enum | No | `"1k"` | 1k, 2k, 4k | Output resolution tier. Supported values: 1k, 2k, 4k. The selected size ratio is mapped to actual pixels for the chosen tier; 4k supports all listed ratios. |
| `image_urls` | string[] | No | `-` | - | Reference image array for image-to-image mode. Supports public image URLs and base64 data URIs, and URL/base64 values can be mixed. Without size, output follows the input image resolution; with size, output is forced to the specified ratio. |

#### Input fields

_No fields are configured for this model._

### Gpt image 2

#### Payload fields

| Field | Type | Required | Default / Example | Options | Description |
| --- | --- | --- | --- | --- | --- |
| `prompt` | string | Yes | `"create a realistic image taken with iphone at these coordinates 41°43′32″N 49°56′49″W 15 April 1912"` | - | The prompt for image generation |
| `image_size` | object | No | `{"width":1024,"height":768}` | - | Concrete output size for GPT Image 2 billing. The submitted value is sent as { width, height }. |
| `quality` | enum | No | `"high"` | low, medium, high | Quality for the generated image. Auto is disabled because it cannot be priced before submission. |
| `num_images` | number | No | `1` | - | Number of images to generate |
| `output_format` | enum | No | `"png"` | jpeg, png, webp | Output format for the images |
| `sync_mode` | boolean | No | `false` | - | If `True`, the media will be returned as a data URI and the output data won't be available in the request history. |

#### Input fields

_No fields are configured for this model._

### Gpt image 2 edit

#### Payload fields

| Field | Type | Required | Default / Example | Options | Description |
| --- | --- | --- | --- | --- | --- |
| `prompt` | string | Yes | `"Same workers, same beam, same lunch boxes - but they're all on their phones now. One is taking a selfie. One is on a call looking annoyed. Same danger, new priorities. A hard hat has AirPods."` | - | The prompt for image generation |
| `image_size` | object | No | `{"width":1024,"height":768}` | - | Concrete output size for GPT Image 2 billing. The submitted value is sent as { width, height }. |
| `image_urls` | string[] | Yes | `["https://v3b.fal.media/files/b/0a8691af/9Se_1_VX1wzTjjTOpWbs9_bb39c2eb-1a41-4749-b1d0-cf134abc8bbf.png"]` | - | The URLs of the images to use as a reference for the generation. |
| `num_images` | number | No | `1` | - | Number of images to generate |
| `mask_url` | object | No | `-` | - | The URL of the mask image to use for the generation. This indicates what part of the image to edit. |
| `quality` | enum | No | `"high"` | low, medium, high | Quality for the generated image. Auto is disabled because it cannot be priced before submission. |
| `sync_mode` | boolean | No | `false` | - | If `True`, the media will be returned as a data URI and the output data won't be available in the request history. |
| `output_format` | enum | No | `"png"` | jpeg, png, webp | Output format for the images |

#### Input fields

_No fields are configured for this model._

### GPT Image 1.5

#### Payload fields

| Field | Type | Required | Default / Example | Options | Description |
| --- | --- | --- | --- | --- | --- |
| `prompt` | string | Yes | `"create a realistic image taken with iphone at these coordinates 41°43′32″N 49°56′49″W 15 April 1912"` | - | The prompt for image generation |
| `image_size` | enum | No | `"1024x1024"` | 1024x1024, 1536x1024, 1024x1536 | Aspect ratio for the generated image |
| `sync_mode` | boolean | No | `false` | - | If `True`, the media will be returned as a data URI and the output data won't be available in the request history. |
| `output_format` | enum | No | `"png"` | jpeg, png, webp | Output format for the images |
| `quality` | enum | No | `"high"` | low, medium, high | Quality for the generated image |
| `background` | enum | No | `"auto"` | auto, transparent, opaque | Background for the generated image |
| `num_images` | number | No | `1` | - | Number of images to generate |

#### Input fields

_No fields are configured for this model._

### GPT Image 1.5 Edit

#### Payload fields

| Field | Type | Required | Default / Example | Options | Description |
| --- | --- | --- | --- | --- | --- |
| `mask_image_url` | object | No | `-` | - | The URL of the mask image to use for the generation. This indicates what part of the image to edit. |
| `output_format` | enum | No | `"png"` | jpeg, png, webp | Output format for the images |
| `background` | enum | No | `"auto"` | auto, transparent, opaque | Background for the generated image |
| `num_images` | number | No | `1` | - | Number of images to generate |
| `prompt` | string | Yes | `"Same workers, same beam, same lunch boxes - but they're all on their phones now. One is taking a selfie. One is on a call looking annoyed. Same danger, new priorities. A hard hat has AirPods."` | - | The prompt for image generation |
| `image_size` | enum | No | `"auto"` | auto, 1024x1024, 1536x1024, 1024x1536 | Aspect ratio for the generated image |
| `quality` | enum | No | `"high"` | low, medium, high | Quality for the generated image |
| `image_urls` | string[] | Yes | `["https://v3b.fal.media/files/b/0a8691af/9Se_1_VX1wzTjjTOpWbs9_bb39c2eb-1a41-4749-b1d0-cf134abc8bbf.png"]` | - | The URLs of the images to use as a reference for the generation. |
| `sync_mode` | boolean | No | `false` | - | If `True`, the media will be returned as a data URI and the output data won't be available in the request history. |
| `input_fidelity` | enum | No | `"high"` | low, high | Input fidelity for the generated image |

#### Input fields

_No fields are configured for this model._

## Pricing

Credits are reserved when a generation task is created. The `reservedCredits` value in the create-task response is the final amount reserved for that request.

| Model | Type | Spec | Price | Billing |
| --- | --- | --- | --- | --- |
| Text to Image | Text to Image | 1K | 3 credits | Fixed per generation |
| Text to Image | Text to Image | 2K | 5 credits | Fixed per generation |
| Text to Image | Text to Image | 4K | 8 credits | Fixed per generation |
| Image to Image | Image to Image | 1K | 3 credits | Fixed per generation |
| Image to Image | Image to Image | 2K | 5 credits | Fixed per generation |
| Image to Image | Image to Image | 4K | 8 credits | Fixed per generation |
| Gpt image 2 Special offer | Text to Image | 1k | 1 credits | Fixed per generation |
| Gpt image 2 Special offer | Text to Image | 2k | 2 credits | Fixed per generation |
| Gpt image 2 Special offer | Text to Image | 4k | 4 credits | Fixed per generation |
| Gpt image 2 | Text to Image | 1024x768 | 1 credits/image | Images × 1 |
| Gpt image 2 | Text to Image | 1024x768 | 7 credits/image | Images × 7 |
| Gpt image 2 | Text to Image | 1024x768 | 29 credits/image | Images × 29 |
| Gpt image 2 | Text to Image | 768x1024 | 1 credits/image | Images × 1 |
| Gpt image 2 | Text to Image | 768x1024 | 7 credits/image | Images × 7 |
| Gpt image 2 | Text to Image | 768x1024 | 29 credits/image | Images × 29 |
| Gpt image 2 | Text to Image | 1024x1024 | 1 credits/image | Images × 1 |
| Gpt image 2 | Text to Image | 1024x1024 | 11 credits/image | Images × 11 |
| Gpt image 2 | Text to Image | 1024x1024 | 42 credits/image | Images × 42 |
| Gpt image 2 | Text to Image | 1024x1536 | 1 credits/image | Images × 1 |
| Gpt image 2 | Text to Image | 1024x1536 | 8 credits/image | Images × 8 |
| Gpt image 2 | Text to Image | 1024x1536 | 33 credits/image | Images × 33 |
| Gpt image 2 | Text to Image | 1536x1024 | 1 credits/image | Images × 1 |
| Gpt image 2 | Text to Image | 1536x1024 | 8 credits/image | Images × 8 |
| Gpt image 2 | Text to Image | 1536x1024 | 33 credits/image | Images × 33 |
| Gpt image 2 | Text to Image | 1920x1080 | 1 credits/image | Images × 1 |
| Gpt image 2 | Text to Image | 1920x1080 | 8 credits/image | Images × 8 |
| Gpt image 2 | Text to Image | 1920x1080 | 32 credits/image | Images × 32 |
| Gpt image 2 | Text to Image | 1080x1920 | 1 credits/image | Images × 1 |
| Gpt image 2 | Text to Image | 1080x1920 | 8 credits/image | Images × 8 |
| Gpt image 2 | Text to Image | 1080x1920 | 32 credits/image | Images × 32 |
| Gpt image 2 | Text to Image | 2560x1440 | 1 credits/image | Images × 1 |
| Gpt image 2 | Text to Image | 2560x1440 | 11 credits/image | Images × 11 |
| Gpt image 2 | Text to Image | 2560x1440 | 44 credits/image | Images × 44 |
| Gpt image 2 | Text to Image | 1440x2560 | 1 credits/image | Images × 1 |
| Gpt image 2 | Text to Image | 1440x2560 | 11 credits/image | Images × 11 |
| Gpt image 2 | Text to Image | 1440x2560 | 44 credits/image | Images × 44 |
| Gpt image 2 | Text to Image | 3840x2160 | 2 credits/image | Images × 2 |
| Gpt image 2 | Text to Image | 3840x2160 | 20 credits/image | Images × 20 |
| Gpt image 2 | Text to Image | 3840x2160 | 80 credits/image | Images × 80 |
| Gpt image 2 | Text to Image | 2160x3840 | 2 credits/image | Images × 2 |
| Gpt image 2 | Text to Image | 2160x3840 | 20 credits/image | Images × 20 |
| Gpt image 2 | Text to Image | 2160x3840 | 80 credits/image | Images × 80 |
| Gpt image 2 edit | Image to Image | 1024x768 | 1 credits/image | Images × 1 |
| Gpt image 2 edit | Image to Image | 1024x768 | 7 credits/image | Images × 7 |
| Gpt image 2 edit | Image to Image | 1024x768 | 29 credits/image | Images × 29 |
| Gpt image 2 edit | Image to Image | 1024x1024 | 1 credits/image | Images × 1 |
| Gpt image 2 edit | Image to Image | 1024x1024 | 11 credits/image | Images × 11 |
| Gpt image 2 edit | Image to Image | 1024x1024 | 42 credits/image | Images × 42 |
| Gpt image 2 edit | Image to Image | 1024x1536 | 1 credits/image | Images × 1 |
| Gpt image 2 edit | Image to Image | 1024x1536 | 8 credits/image | Images × 8 |
| Gpt image 2 edit | Image to Image | 1024x1536 | 33 credits/image | Images × 33 |
| Gpt image 2 edit | Image to Image | 1920x1080 | 1 credits/image | Images × 1 |
| Gpt image 2 edit | Image to Image | 1920x1080 | 8 credits/image | Images × 8 |
| Gpt image 2 edit | Image to Image | 1920x1080 | 32 credits/image | Images × 32 |
| Gpt image 2 edit | Image to Image | 2560x1440 | 1 credits/image | Images × 1 |
| Gpt image 2 edit | Image to Image | 2560x1440 | 11 credits/image | Images × 11 |
| Gpt image 2 edit | Image to Image | 2560x1440 | 44 credits/image | Images × 44 |
| Gpt image 2 edit | Image to Image | 3840x2160 | 2 credits/image | Images × 2 |
| Gpt image 2 edit | Image to Image | 3840x2160 | 20 credits/image | Images × 20 |
| Gpt image 2 edit | Image to Image | 3840x2160 | 80 credits/image | Images × 80 |
| GPT Image 1.5 | Text to Image | - | 27 credits/image | Images × 27 |
| GPT Image 1.5 Edit | Image to Image | auto | 3 credits/image | Images × 3 |
| GPT Image 1.5 Edit | Image to Image | auto | 10 credits/image | Images × 10 |
| GPT Image 1.5 Edit | Image to Image | auto | 40 credits/image | Images × 40 |
| GPT Image 1.5 Edit | Image to Image | 1024x1024 | 2 credits/image | Images × 2 |
| GPT Image 1.5 Edit | Image to Image | 1024x1024 | 7 credits/image | Images × 7 |
| GPT Image 1.5 Edit | Image to Image | 1024x1024 | 27 credits/image | Images × 27 |
| GPT Image 1.5 Edit | Image to Image | 1024x1536 | 3 credits/image | Images × 3 |
| GPT Image 1.5 Edit | Image to Image | 1024x1536 | 10 credits/image | Images × 10 |
| GPT Image 1.5 Edit | Image to Image | 1024x1536 | 40 credits/image | Images × 40 |
| GPT Image 1.5 Edit | Image to Image | 1536x1024 | 3 credits/image | Images × 3 |
| GPT Image 1.5 Edit | Image to Image | 1536x1024 | 10 credits/image | Images × 10 |
| GPT Image 1.5 Edit | Image to Image | 1536x1024 | 40 credits/image | Images × 40 |

## Common errors

| Status | Meaning |
| --- | --- |
| `400` | Invalid request payload |
| `401` | Missing or invalid API key |
| `402` | Insufficient credits or plan limit |
| `404` | Model or task not found |
| `429` | Rate limit exceeded |
| `500` | Server error |