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

# gpt-image-2-vip 生成图像 API

> 使用 `POST /v1/images/generations` 调用 `gpt-image-2-vip` 生成图像。

# gpt-image-2-vip 生成图像 API

`gpt-image-2-vip` 用于提交 VIP 图像生成请求。请求体使用 JSON 格式，按模型名、提示词、输出尺寸和返回格式描述本次生成任务。

* 请求路径为 `POST /v1/images/generations`。
* 通过 `model = "gpt-image-2-vip"` 选择目标模型。
* `prompt` 描述要生成的图像内容。
* `size` 传实际输出尺寸，例如 `2560x1440`、`3504x2336`、`3808x1632`。
* 每条边必须是 `16px` 的倍数，最长边不超过 `3840px`。
* 长短边比例不超过 `3:1`，总像素数必须在 `655,360` 到 `8,294,400` 之间。
* 可在 JSON 中附带 `image` 作为参考图。

## 方法与路径

```http theme={null}
POST /v1/images/generations
```

## 请求示例

<CodeGroup>
  ```bash theme={null}
  curl -X POST https://www.geeknow.top/v1/images/generations \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "gpt-image-2-vip",
      "prompt": "一张高端科技发布会主视觉，超宽画幅，冷暖对比光，细节丰富",
      "n": 1,
      "size": "3808x1632",
      "quality": "high"
    }'
  ```

  ```python theme={null}
  import requests

  resp = requests.post(
      "https://www.geeknow.top/v1/images/generations",
      headers={
          "Authorization": "Bearer YOUR_API_KEY",
          "Content-Type": "application/json",
      },
      json={
          "model": "gpt-image-2-vip",
          "prompt": "一张高端科技发布会主视觉，超宽画幅，冷暖对比光，细节丰富",
          "n": 1,
          "size": "3808x1632",
          "quality": "high",
      },
      timeout=60,
  )
  print(resp.json())
  ```

  ```javascript theme={null}
  const response = await fetch("https://www.geeknow.top/v1/images/generations", {
    method: "POST",
    headers: {
      Authorization: "Bearer YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      model: "gpt-image-2-vip",
      prompt: "一张高端科技发布会主视觉，超宽画幅，冷暖对比光，细节丰富",
      n: 1,
      size: "3808x1632",
      quality: "high",
    }),
  });

  console.log(await response.json());
  ```
</CodeGroup>

## 响应示例

<ResponseExample>
  ```json 200 - URL theme={null}
  {
    "created": 1735689600,
    "data": [
      {
        "url": "https://.../images/img-vip-abc123.png",
        "revised_prompt": "一张高端科技发布会主视觉，超宽画幅，冷暖对比光，细节丰富"
      }
    ]
  }
  ```

  ```json 200 - Base64 theme={null}
  {
    "created": 1735689600,
    "data": [
      {
        "b64_json": "iVBORw0KGgoAAAANSUhEUgAA...",
        "revised_prompt": "一张高端科技发布会主视觉，超宽画幅，冷暖对比光，细节丰富"
      }
    ]
  }
  ```

  ```json 400 theme={null}
  {
    "error": {
      "message": "size must be within vip image size constraints",
      "type": "invalid_request_error",
      "param": "size",
      "code": "invalid_size"
    }
  }
  ```
</ResponseExample>

## 认证

```http theme={null}
Authorization: Bearer YOUR_API_KEY
```

## Body

<ParamField body="model" type="string" required>
  固定传 `gpt-image-2-vip`。
</ParamField>

<ParamField body="prompt" type="string" required>
  生成提示词，用于描述想要生成的图片。
</ParamField>

<ParamField body="n" type="integer">
  生成数量。若不传或显式传 `0`，按 `1` 处理。
</ParamField>

<ParamField body="size" type="string" required>
  输出尺寸，使用 `WxH` 格式，例如 `2048x2048`、`2560x1440`、`3504x2336`、`3808x1632`。VIP 尺寸必须满足下方约束。
</ParamField>

<ParamField body="image" type="string | array<string> | object">
  可选参考图输入。常见写法是 Base64 字符串或 Base64 数组，适合需要图像风格参考的渠道。
</ParamField>

<ParamField body="quality" type="string">
  质量字段。常见值为 `low`、`medium`、`high`、`auto`，是否真正生效取决于最终命中的渠道。
</ParamField>

<ParamField body="response_format" type="string">
  返回格式字段。VIP 通道建议不传该字段，由通道返回 `url` 或 `b64_json`；若传入，是否生效取决于实际命中的渠道。
</ParamField>

<ParamField body="style" type="string | object">
  风格字段，原样透传给支持的上游。
</ParamField>

<ParamField body="background" type="string | object">
  背景控制字段，原样透传给支持的上游。
</ParamField>

<ParamField body="watermark" type="boolean">
  显式水印开关。`false` 与不传语义不同。
</ParamField>

## 尺寸约束

`size` 必须同时满足：

| 约束    | 要求                           |
| ----- | ---------------------------- |
| 边长    | 宽和高都必须是 `16px` 的倍数           |
| 最长边   | 不超过 `3840px`                 |
| 长短边比例 | 不超过 `3:1`                    |
| 总像素数  | `655,360` 到 `8,294,400`，含边界值 |

## 尺寸表

接口请求体中的 `size` 传“实际目标尺寸”这一列。`1K`、`2K`、`4K` 是业务侧常用预设分组。

### `1K` 档位

| 预设     | 实际目标尺寸      |
| ------ | ----------- |
| `1:1`  | `1024x1024` |
| `4:3`  | `1024x768`  |
| `3:4`  | `768x1024`  |
| `3:2`  | `1008x672`  |
| `2:3`  | `672x1008`  |
| `16:9` | `1280x720`  |
| `9:16` | `720x1280`  |
| `21:9` | `1344x576`  |

### `2K` 档位

| 预设         | 实际目标尺寸      |
| ---------- | ----------- |
| `1:1(2K)`  | `2048x2048` |
| `4:3(2K)`  | `2304x1728` |
| `3:4(2K)`  | `1728x2304` |
| `3:2(2K)`  | `2496x1664` |
| `2:3(2K)`  | `1664x2496` |
| `16:9(2K)` | `2560x1440` |
| `9:16(2K)` | `1440x2560` |
| `21:9(2K)` | `3024x1296` |

### `4K` 档位

| 预设         | 实际目标尺寸      |
| ---------- | ----------- |
| `1:1(4K)`  | `2880x2880` |
| `4:3(4K)`  | `3264x2448` |
| `3:4(4K)`  | `2448x3264` |
| `3:2(4K)`  | `3504x2336` |
| `2:3(4K)`  | `2336x3504` |
| `16:9(4K)` | `3840x2160` |
| `9:16(4K)` | `2160x3840` |
| `21:9(4K)` | `3808x1632` |

<Info>
  如果你按比例预设做业务封装，请先映射为上表中的实际 `WxH` 尺寸再提交请求。
</Info>

## Response

<ResponseField name="created" type="integer">
  生成时间戳。
</ResponseField>

<ResponseField name="data[].url" type="string">
  返回 URL 时的图片地址。
</ResponseField>

<ResponseField name="data[].b64_json" type="string">
  返回 Base64 时的图片数据。
</ResponseField>

<ResponseField name="data[].revised_prompt" type="string">
  部分上游会改写提示词并返回在这个字段里。
</ResponseField>

## 异步调用

如需提交后异步查询结果，可以使用图像异步生成入口：

```http theme={null}
POST /v1/images/generations/async
```

异步请求仍传 `model = "gpt-image-2-vip"`，`size` 仍需满足本页列出的尺寸约束。提交成功后读取返回的 `id` / `task_id`，再通过 `GET /v1/images/generations/async/{taskId}` 查询状态和结果。

## 相关页面

* [图像模型支持矩阵](/api-reference/images/model-matrix)
* [图像异步生成 API](/api-reference/images/gpt-image-async/generation)
* [图像异步任务查询](/api-reference/images/gpt-image-async/query)
* [OpenAI Images 兼容概览](/api-reference/images/gpt-image-1/overview)