> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vidgo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# GPT Image 2

> GPT Image 2 API 用于生成和编辑图像。

> [!TIP]
>
> 1. 提交后会返回 `task_id`。如果提供了 `callback_url`，当任务状态变为 `finished` 或 `failed` 时，系统会向 `callback_url` 发送 POST 请求。
> 2. 无论是否提供 `callback_url`，都可以通过统一的[查询任务状态](https://docs.vidgo.ai/zh/api-manual/task-management/status.md)接口获取结果。

## 模型

* **gpt-image-2** - 根据提示词进行文生图。
* **gpt-image-2-edit** - 基于一张或多张 `image_urls` 和文字指令进行图像编辑。

## 概览

使用 Vidgo API 根据提示词生成一张图像，或用自然语言指令编辑一张或多张参考图。GPT Image 2 支持显式的质量档位、比例预设、自定义尺寸，以及 `1K`、`2K` 或 `4K` 分辨率控制。

## 分辨率

`resolution` 参数控制实际输出分辨率。

| 分辨率 | 说明 |
| - | - |
| `1K` | 标准分辨率 |
| `2K` | 高分辨率 |
| `4K` | 超高分辨率，适用于支持真 4K 的尺寸 |

### 计费因素

每次请求生成一张图像。计费取决于 `quality` 以及由 `size` 和 `resolution` 决定的实际输出分辨率。下面的规则说明实际分辨率如何确定。

## 分辨率规则

* 如果省略 `size` 或设为 `auto`，即使提供了 `resolution`，请求也按 `1K` 处理和计费。
* 自定义 `WIDTHxHEIGHT` 尺寸需要 `resolution` 为 `2K` 或 `4K`。
* 只有 `16:9`、`9:16`、`21:9`，或某条边为 `3840` 像素的自定义尺寸才按 `4K` 计费。
* 不满足真 4K 规则的 `4K` 请求按实际的 `2K` 档位计费。
* 最长边为 `3840` 的自定义尺寸必须使用 `resolution: "4K"`。

## 自定义尺寸限制

自定义尺寸使用 `WIDTHxHEIGHT` 格式，例如 `2304x1536`，并且必须同时满足：

* 宽和高都必须能被 `16` 整除。
* 最长边不超过 `3840` 像素。
* 宽高比不超过 `3:1`。
* 像素总数在 `655,360` 到 `8,294,400` 之间。

## 请求示例

### 生成图像

```bash theme={null}
curl --request POST \
  --url https://api.vidgo.ai/api/generate/submit \
  --header "Authorization: Bearer VIDGO_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "model": "gpt-image-2",
    "callback_url": "https://your-domain.com/callback",
    "input": {
      "prompt": "A premium product photo of a silver espresso machine on a clean white studio background, realistic lighting, high detail",
      "quality": "low",
      "size": "1:1",
      "resolution": "1K"
    }
  }'
```

### 编辑图像

```bash theme={null}
curl --request POST \
  --url https://api.vidgo.ai/api/generate/submit \
  --header "Authorization: Bearer VIDGO_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "model": "gpt-image-2-edit",
    "callback_url": "https://your-domain.com/callback",
    "input": {
      "prompt": "Replace the background with a clean white studio backdrop and add a soft natural shadow while preserving the product shape",
      "quality": "medium",
      "size": "1:1",
      "resolution": "2K",
      "image_urls": [
        "https://cdn.vidgo.ai/temp/reference-product.jpg"
      ]
    }
  }'
```

## 响应流程

提交接口返回 `task_id`、`status` 和 `created_time`。如果提供了 `callback_url`，任务变为 `finished` 或 `failed` 时，Vidgo API 会向其发送 POST 请求。

使用统一的状态接口获取最终结果：

```bash theme={null}
curl --request GET \
  --url https://api.vidgo.ai/api/generate/status/task-unified-1757165031-uyujaw3d \
  --header "Authorization: Bearer VIDGO_API_KEY"
```

任务为 `finished` 时，状态响应的 `data.files` 中包含生成的图像文件 URL。任务失败时，状态响应会返回失败详情，便于排查。

## 注意事项

* `input.prompt` 必填，最多 `4000` 个字符。
* `input.quality` 可选：`low`、`medium` 或 `high`。默认：`low`。
* `input.size` 可选。支持的值为 `auto`、`1:1`、`2:3`、`3:2`、`3:4`、`4:3`、`4:5`、`5:4`、`16:9`、`9:16`、`21:9`，或自定义 `WIDTHxHEIGHT` 值。
* `input.resolution` 可选：`1K`、`2K` 或 `4K`。
* `gpt-image-2-edit` 需要 `input.image_urls`。
* `gpt-image-2` 不接受 `input.image_urls`。
* 每次请求返回一张图像。


## OpenAPI

````yaml zh/api-manual/image-series/gpt-image-2.json POST /api/generate/submit
openapi: 3.0.0
info:
  title: Vidgo API - GPT Image 2 API
  description: >-
    在 Vidgo API 上使用 GPT Image 2，每次请求生成或编辑一张图像。支持质量档位、比例预设、自定义尺寸，以及显式的 1K、2K 或 4K
    分辨率控制。
  version: 1.0.0
servers:
  - url: https://api.vidgo.ai
    description: 生产环境服务器
security:
  - BearerAuth: []
paths:
  /api/generate/submit:
    post:
      tags:
        - GPT Image 2
      summary: 提交 GPT Image 2 任务
      description: >-
        在 Vidgo API 上使用 GPT Image 2 生成或编辑一张图像。基于提示词生成请使用 gpt-image-2，需要参考图 URL
        时请使用 gpt-image-2-edit。
      operationId: submitGPTImage2Task
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SubmitRequest'
            examples:
              gpt-image-2:
                summary: gpt-image-2
                value:
                  model: gpt-image-2
                  callback_url: https://your-domain.com/callback
                  input:
                    prompt: >-
                      A premium product photo of a silver espresso machine on a
                      clean white studio background, realistic lighting, high
                      detail
                    quality: low
                    size: '1:1'
                    resolution: 1K
              gpt-image-2-2k:
                summary: gpt-image-2-2k
                value:
                  model: gpt-image-2
                  callback_url: https://your-domain.com/callback
                  input:
                    prompt: >-
                      A clean landing-page hero illustration of a fintech
                      dashboard with crisp typography and balanced spacing
                    quality: medium
                    size: '16:9'
                    resolution: 2K
              gpt-image-2-4k:
                summary: gpt-image-2-4k
                value:
                  model: gpt-image-2
                  callback_url: https://your-domain.com/callback
                  input:
                    prompt: >-
                      A cinematic 21:9 hero image of an electric concept car in
                      a rain-soaked city at night
                    quality: high
                    size: '21:9'
                    resolution: 4K
              gpt-image-2-custom-size:
                summary: gpt-image-2-custom-size
                value:
                  model: gpt-image-2
                  callback_url: https://your-domain.com/callback
                  input:
                    prompt: >-
                      A product marketing banner with a centered smartwatch,
                      soft reflections, and clean negative space for headline
                      copy
                    quality: medium
                    size: 2304x1536
                    resolution: 2K
              gpt-image-2-edit:
                summary: gpt-image-2-edit
                value:
                  model: gpt-image-2-edit
                  callback_url: https://your-domain.com/callback
                  input:
                    prompt: >-
                      Replace the background with a clean white studio backdrop
                      and add a soft natural shadow while preserving the product
                      shape
                    quality: medium
                    size: '1:1'
                    resolution: 2K
                    image_urls:
                      - https://cdn.vidgo.ai/temp/reference-product.jpg
      responses:
        '200':
          description: 任务提交成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubmitResponse'
        '400':
          description: 请求参数无效
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                missing_prompt:
                  value:
                    code: 400
                    error:
                      message: prompt is required
                      type: invalid_request_error
                missing_image_urls_for_edit:
                  value:
                    code: 400
                    error:
                      message: image_urls is required for edit
                      type: invalid_request_error
                image_urls_not_supported_for_generate:
                  value:
                    code: 400
                    error:
                      message: image_urls is only supported for gpt-image-2-edit
                      type: invalid_request_error
                custom_size_requires_higher_resolution:
                  value:
                    code: 400
                    error:
                      message: custom size requires resolution 2K or 4K
                      type: invalid_request_error
                true_4k_custom_size_requires_4k:
                  value:
                    code: 400
                    error:
                      message: true 4K custom size requires resolution 4K
                      type: invalid_request_error
                invalid_quality:
                  value:
                    code: 400
                    error:
                      message: 'quality must be one of: low, medium, high'
                      type: invalid_request_error
                invalid_resolution:
                  value:
                    code: 400
                    error:
                      message: 'resolution must be one of: 1K, 2K, 4K'
                      type: invalid_request_error
        '401':
          description: 未授权 - API Key 无效
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                code: 401
                error:
                  message: Unauthorized - Invalid API key
                  type: authentication_error
components:
  schemas:
    SubmitRequest:
      type: object
      required:
        - model
        - input
      properties:
        model:
          type: string
          example: gpt-image-2
        callback_url:
          type: string
          format: uri
          description: 任务完成或失败时用于接收通知的 Webhook 回调 URL。
          example: https://your-domain.com/callback
        input:
          type: object
          required:
            - prompt
          description: 在 Vidgo API 上进行 GPT Image 2 生成或编辑的输入参数。
          properties:
            prompt:
              type: string
              description: 描述期望图像或编辑内容的提示词。
              maxLength: 4000
              example: A studio product photo of a matte black espresso machine
            quality:
              type: string
              description: 图像质量档位。默认 low，与实际分辨率共同决定积分消耗。
              enum:
                - low
                - medium
                - high
              default: low
              example: low
            size:
              description: >-
                图像尺寸。可使用 auto、受支持的宽高比，或自定义 WIDTHxHEIGHT 值。省略 size 或设为 auto 时，请求按
                1K 档位处理。


                使用预设（`auto`、`1:1`、`2:3`、`3:2`、`3:4`、`4:3`、`4:5`、`5:4`、`16:9`、`9:16`、`21:9`）或自定义
                `WIDTHxHEIGHT` 尺寸。


                自定义尺寸时，每个维度须为三位或四位数字，用小写 `x` 分隔。
              example: '16:9'
              type: string
            resolution:
              type: string
              description: >-
                请求的分辨率。自定义尺寸需要 2K 或 4K。size 为 auto 时，实际结果保持 1K。非真 4K 请求可能按实际的 2K
                档位计费。
              enum:
                - 1K
                - 2K
                - 4K
              example: 1K
            image_urls:
              type: array
              description: 编辑请求的参考图 URL。gpt-image-2-edit 必填，gpt-image-2 不接受此字段。
              items:
                type: string
                format: uri
              example:
                - https://cdn.vidgo.ai/temp/reference-product.jpg
    SubmitResponse:
      type: object
      required:
        - code
        - data
      properties:
        code:
          type: integer
          example: 200
        data:
          type: object
          required:
            - task_id
            - status
            - created_time
          properties:
            task_id:
              type: string
              example: task-unified-1757165031-uyujaw3d
            status:
              type: string
              enum:
                - not_started
              example: not_started
            created_time:
              type: string
              format: date-time
              example: '2026-04-27T10:30:00'
    ErrorResponse:
      type: object
      required:
        - code
        - error
      properties:
        code:
          type: integer
          example: 400
        error:
          type: object
          required:
            - message
            - type
          properties:
            message:
              type: string
              example: Invalid request parameters
            type:
              type: string
              example: invalid_request_error
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: |-
        所有 API 接口都需要 Bearer Token 认证。

        在 **仪表盘 → API 密钥** 页面获取 API Key，并在请求头中传入：

        ```
        Authorization: Bearer VIDGO_API_KEY
        ```

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.