# GPT Image 2 API 文档

> 通过 AI Studio API 使用 GPT Image 2 模型生成视频。

## 概览

使用 AI Studio API 创建 GPT Image 2 生成任务并查询任务状态。接口采用异步流程：先创建任务拿到 `taskId`，再通过任务查询接口轮询结果。

## 认证方式

所有请求都需要在 `Authorization` 请求头中携带 API Key。

```http
Authorization: Bearer YOUR_API_KEY
```

## 可用模型

| modelId | 版本 | 服务商 | 运行模型 |
| --- | --- | --- | --- |
| `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. 创建生成任务

### 接口地址

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

### 请求示例

```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"
    }
  }
}
```

### 成功响应

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

## 2. 查询任务状态

### 接口

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

### 成功响应

```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
  }
}
```

## 请求字段

### Text to Image

#### Payload 字段

| 字段 | 类型 | 必填 | 默认值 / 示例 | 可选值 | 说明 |
| --- | --- | --- | --- | --- | --- |
| `model` | enum | 是 | `"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 | 是 | `-` | - | Input parameters for the text-to-image task. |

#### input 字段

| 字段 | 类型 | 必填 | 默认值 / 示例 | 可选值 | 说明 |
| --- | --- | --- | --- | --- | --- |
| `prompt` | string | 是 | `"A cinematic night city poster with neon reflections on a rainy street."` | - | Text prompt. Required, maximum 20,000 characters. |
| `aspect_ratio` | enum | 否 | `-` | 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 | 否 | `-` | 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 字段

| 字段 | 类型 | 必填 | 默认值 / 示例 | 可选值 | 说明 |
| --- | --- | --- | --- | --- | --- |
| `model` | enum | 是 | `"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 | 是 | `-` | - | Input parameters for the image-to-image task. |

#### input 字段

| 字段 | 类型 | 必填 | 默认值 / 示例 | 可选值 | 说明 |
| --- | --- | --- | --- | --- | --- |
| `prompt` | string | 是 | `"Transform this product image into a premium e-commerce poster style."` | - | Text prompts, up to 20,000 characters. |
| `input_urls` | string[] | 是 | `["https://example.com/"]` | - | Array of input image URLs. |
| `aspect_ratio` | enum | 否 | `-` | 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 | 否 | `-` | 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 字段

| 字段 | 类型 | 必填 | 默认值 / 示例 | 可选值 | 说明 |
| --- | --- | --- | --- | --- | --- |
| `model` | enum | 是 | `"gpt-image-2"` | gpt-image-2 | Image generation model name. Fixed to gpt-image-2. |
| `prompt` | string | 是 | `-` | - | Text description for image generation. Supports English and Chinese; detailed descriptions are recommended. Prompts are moderated before submission. |
| `size` | enum | 否 | `"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 | 否 | `"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[] | 否 | `-` | - | 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 字段

_该模型暂无字段配置。_

### Gpt image 2

#### Payload 字段

| 字段 | 类型 | 必填 | 默认值 / 示例 | 可选值 | 说明 |
| --- | --- | --- | --- | --- | --- |
| `prompt` | string | 是 | `"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 | 否 | `{"width":1024,"height":768}` | - | Concrete output size for GPT Image 2 billing. The submitted value is sent as { width, height }. |
| `quality` | enum | 否 | `"high"` | low, medium, high | Quality for the generated image. Auto is disabled because it cannot be priced before submission. |
| `num_images` | number | 否 | `1` | - | Number of images to generate |
| `output_format` | enum | 否 | `"png"` | jpeg, png, webp | Output format for the images |
| `sync_mode` | boolean | 否 | `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 字段

_该模型暂无字段配置。_

### Gpt image 2 edit

#### Payload 字段

| 字段 | 类型 | 必填 | 默认值 / 示例 | 可选值 | 说明 |
| --- | --- | --- | --- | --- | --- |
| `prompt` | string | 是 | `"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 | 否 | `{"width":1024,"height":768}` | - | Concrete output size for GPT Image 2 billing. The submitted value is sent as { width, height }. |
| `image_urls` | string[] | 是 | `["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 | 否 | `1` | - | Number of images to generate |
| `mask_url` | object | 否 | `-` | - | The URL of the mask image to use for the generation. This indicates what part of the image to edit. |
| `quality` | enum | 否 | `"high"` | low, medium, high | Quality for the generated image. Auto is disabled because it cannot be priced before submission. |
| `sync_mode` | boolean | 否 | `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 | 否 | `"png"` | jpeg, png, webp | Output format for the images |

#### input 字段

_该模型暂无字段配置。_

### GPT Image 1.5

#### Payload 字段

| 字段 | 类型 | 必填 | 默认值 / 示例 | 可选值 | 说明 |
| --- | --- | --- | --- | --- | --- |
| `prompt` | string | 是 | `"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 | 否 | `"1024x1024"` | 1024x1024, 1536x1024, 1024x1536 | Aspect ratio for the generated image |
| `sync_mode` | boolean | 否 | `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 | 否 | `"png"` | jpeg, png, webp | Output format for the images |
| `quality` | enum | 否 | `"high"` | low, medium, high | Quality for the generated image |
| `background` | enum | 否 | `"auto"` | auto, transparent, opaque | Background for the generated image |
| `num_images` | number | 否 | `1` | - | Number of images to generate |

#### input 字段

_该模型暂无字段配置。_

### GPT Image 1.5 Edit

#### Payload 字段

| 字段 | 类型 | 必填 | 默认值 / 示例 | 可选值 | 说明 |
| --- | --- | --- | --- | --- | --- |
| `mask_image_url` | object | 否 | `-` | - | The URL of the mask image to use for the generation. This indicates what part of the image to edit. |
| `output_format` | enum | 否 | `"png"` | jpeg, png, webp | Output format for the images |
| `background` | enum | 否 | `"auto"` | auto, transparent, opaque | Background for the generated image |
| `num_images` | number | 否 | `1` | - | Number of images to generate |
| `prompt` | string | 是 | `"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 | 否 | `"auto"` | auto, 1024x1024, 1536x1024, 1024x1536 | Aspect ratio for the generated image |
| `quality` | enum | 否 | `"high"` | low, medium, high | Quality for the generated image |
| `image_urls` | string[] | 是 | `["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 | 否 | `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 | 否 | `"high"` | low, high | Input fidelity for the generated image |

#### input 字段

_该模型暂无字段配置。_

## 价格

创建生成任务时会预扣积分。创建任务响应中的 `reservedCredits` 是本次请求最终预留的积分数量。

| 模型 | 类型 | 规格 | 价格 | 计费方式 |
| --- | --- | --- | --- | --- |
| Text to Image | 文生图 | 1K | 3 积分 | 单次生成固定价格 |
| Text to Image | 文生图 | 2K | 5 积分 | 单次生成固定价格 |
| Text to Image | 文生图 | 4K | 8 积分 | 单次生成固定价格 |
| Image to Image | 图生图 | 1K | 3 积分 | 单次生成固定价格 |
| Image to Image | 图生图 | 2K | 5 积分 | 单次生成固定价格 |
| Image to Image | 图生图 | 4K | 8 积分 | 单次生成固定价格 |
| Gpt image 2 Special offer | 文生图 | 1k | 1 积分 | 单次生成固定价格 |
| Gpt image 2 Special offer | 文生图 | 2k | 2 积分 | 单次生成固定价格 |
| Gpt image 2 Special offer | 文生图 | 4k | 4 积分 | 单次生成固定价格 |
| Gpt image 2 | 文生图 | 1024x768 | 1 积分/张 | 图片数量 × 1 |
| Gpt image 2 | 文生图 | 1024x768 | 7 积分/张 | 图片数量 × 7 |
| Gpt image 2 | 文生图 | 1024x768 | 29 积分/张 | 图片数量 × 29 |
| Gpt image 2 | 文生图 | 768x1024 | 1 积分/张 | 图片数量 × 1 |
| Gpt image 2 | 文生图 | 768x1024 | 7 积分/张 | 图片数量 × 7 |
| Gpt image 2 | 文生图 | 768x1024 | 29 积分/张 | 图片数量 × 29 |
| Gpt image 2 | 文生图 | 1024x1024 | 1 积分/张 | 图片数量 × 1 |
| Gpt image 2 | 文生图 | 1024x1024 | 11 积分/张 | 图片数量 × 11 |
| Gpt image 2 | 文生图 | 1024x1024 | 42 积分/张 | 图片数量 × 42 |
| Gpt image 2 | 文生图 | 1024x1536 | 1 积分/张 | 图片数量 × 1 |
| Gpt image 2 | 文生图 | 1024x1536 | 8 积分/张 | 图片数量 × 8 |
| Gpt image 2 | 文生图 | 1024x1536 | 33 积分/张 | 图片数量 × 33 |
| Gpt image 2 | 文生图 | 1536x1024 | 1 积分/张 | 图片数量 × 1 |
| Gpt image 2 | 文生图 | 1536x1024 | 8 积分/张 | 图片数量 × 8 |
| Gpt image 2 | 文生图 | 1536x1024 | 33 积分/张 | 图片数量 × 33 |
| Gpt image 2 | 文生图 | 1920x1080 | 1 积分/张 | 图片数量 × 1 |
| Gpt image 2 | 文生图 | 1920x1080 | 8 积分/张 | 图片数量 × 8 |
| Gpt image 2 | 文生图 | 1920x1080 | 32 积分/张 | 图片数量 × 32 |
| Gpt image 2 | 文生图 | 1080x1920 | 1 积分/张 | 图片数量 × 1 |
| Gpt image 2 | 文生图 | 1080x1920 | 8 积分/张 | 图片数量 × 8 |
| Gpt image 2 | 文生图 | 1080x1920 | 32 积分/张 | 图片数量 × 32 |
| Gpt image 2 | 文生图 | 2560x1440 | 1 积分/张 | 图片数量 × 1 |
| Gpt image 2 | 文生图 | 2560x1440 | 11 积分/张 | 图片数量 × 11 |
| Gpt image 2 | 文生图 | 2560x1440 | 44 积分/张 | 图片数量 × 44 |
| Gpt image 2 | 文生图 | 1440x2560 | 1 积分/张 | 图片数量 × 1 |
| Gpt image 2 | 文生图 | 1440x2560 | 11 积分/张 | 图片数量 × 11 |
| Gpt image 2 | 文生图 | 1440x2560 | 44 积分/张 | 图片数量 × 44 |
| Gpt image 2 | 文生图 | 3840x2160 | 2 积分/张 | 图片数量 × 2 |
| Gpt image 2 | 文生图 | 3840x2160 | 20 积分/张 | 图片数量 × 20 |
| Gpt image 2 | 文生图 | 3840x2160 | 80 积分/张 | 图片数量 × 80 |
| Gpt image 2 | 文生图 | 2160x3840 | 2 积分/张 | 图片数量 × 2 |
| Gpt image 2 | 文生图 | 2160x3840 | 20 积分/张 | 图片数量 × 20 |
| Gpt image 2 | 文生图 | 2160x3840 | 80 积分/张 | 图片数量 × 80 |
| Gpt image 2 edit | 图生图 | 1024x768 | 1 积分/张 | 图片数量 × 1 |
| Gpt image 2 edit | 图生图 | 1024x768 | 7 积分/张 | 图片数量 × 7 |
| Gpt image 2 edit | 图生图 | 1024x768 | 29 积分/张 | 图片数量 × 29 |
| Gpt image 2 edit | 图生图 | 1024x1024 | 1 积分/张 | 图片数量 × 1 |
| Gpt image 2 edit | 图生图 | 1024x1024 | 11 积分/张 | 图片数量 × 11 |
| Gpt image 2 edit | 图生图 | 1024x1024 | 42 积分/张 | 图片数量 × 42 |
| Gpt image 2 edit | 图生图 | 1024x1536 | 1 积分/张 | 图片数量 × 1 |
| Gpt image 2 edit | 图生图 | 1024x1536 | 8 积分/张 | 图片数量 × 8 |
| Gpt image 2 edit | 图生图 | 1024x1536 | 33 积分/张 | 图片数量 × 33 |
| Gpt image 2 edit | 图生图 | 1920x1080 | 1 积分/张 | 图片数量 × 1 |
| Gpt image 2 edit | 图生图 | 1920x1080 | 8 积分/张 | 图片数量 × 8 |
| Gpt image 2 edit | 图生图 | 1920x1080 | 32 积分/张 | 图片数量 × 32 |
| Gpt image 2 edit | 图生图 | 2560x1440 | 1 积分/张 | 图片数量 × 1 |
| Gpt image 2 edit | 图生图 | 2560x1440 | 11 积分/张 | 图片数量 × 11 |
| Gpt image 2 edit | 图生图 | 2560x1440 | 44 积分/张 | 图片数量 × 44 |
| Gpt image 2 edit | 图生图 | 3840x2160 | 2 积分/张 | 图片数量 × 2 |
| Gpt image 2 edit | 图生图 | 3840x2160 | 20 积分/张 | 图片数量 × 20 |
| Gpt image 2 edit | 图生图 | 3840x2160 | 80 积分/张 | 图片数量 × 80 |
| GPT Image 1.5 | 文生图 | - | 27 积分/张 | 图片数量 × 27 |
| GPT Image 1.5 Edit | 图生图 | auto | 3 积分/张 | 图片数量 × 3 |
| GPT Image 1.5 Edit | 图生图 | auto | 10 积分/张 | 图片数量 × 10 |
| GPT Image 1.5 Edit | 图生图 | auto | 40 积分/张 | 图片数量 × 40 |
| GPT Image 1.5 Edit | 图生图 | 1024x1024 | 2 积分/张 | 图片数量 × 2 |
| GPT Image 1.5 Edit | 图生图 | 1024x1024 | 7 积分/张 | 图片数量 × 7 |
| GPT Image 1.5 Edit | 图生图 | 1024x1024 | 27 积分/张 | 图片数量 × 27 |
| GPT Image 1.5 Edit | 图生图 | 1024x1536 | 3 积分/张 | 图片数量 × 3 |
| GPT Image 1.5 Edit | 图生图 | 1024x1536 | 10 积分/张 | 图片数量 × 10 |
| GPT Image 1.5 Edit | 图生图 | 1024x1536 | 40 积分/张 | 图片数量 × 40 |
| GPT Image 1.5 Edit | 图生图 | 1536x1024 | 3 积分/张 | 图片数量 × 3 |
| GPT Image 1.5 Edit | 图生图 | 1536x1024 | 10 积分/张 | 图片数量 × 10 |
| GPT Image 1.5 Edit | 图生图 | 1536x1024 | 40 积分/张 | 图片数量 × 40 |

## 常见错误

| 状态 | 含义 |
| --- | --- |
| `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 |