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

# GPT Image 2 图像生成

> GPT Image 2 文生图接口，基于 OpenAI Images 兼容协议。

`/v1/images/generations` 用于 GPT Image 2 文生图。该接口仅面向 OpenAI-compatible 分组，并受图片生成权限控制。

<RequestExample>
  ```bash cURL theme={null}
  curl --request POST \
    --url https://code.heihuzi.ai/v1/images/generations \
    --header 'Authorization: Bearer <token>' \
    --header 'Content-Type: application/json' \
    --data '{
      "model": "gpt-image-2",
      "prompt": "一只橘猫坐在窗台上看夕阳，水彩画风格",
      "n": 1,
      "size": "2048x1152",
      "quality": "high",
      "output_format": "png"
    }'
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      "https://code.heihuzi.ai/v1/images/generations",
      headers={
          "Authorization": "Bearer <token>",
          "Content-Type": "application/json",
      },
      json={
          "model": "gpt-image-2",
          "prompt": "一只橘猫坐在窗台上看夕阳，水彩画风格",
          "n": 1,
          "size": "2048x1152",
          "quality": "high",
          "output_format": "png",
      },
  )

  print(response.json())
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch("https://code.heihuzi.ai/v1/images/generations", {
    method: "POST",
    headers: {
      "Authorization": "Bearer <token>",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      model: "gpt-image-2",
      prompt: "一只橘猫坐在窗台上看夕阳，水彩画风格",
      n: 1,
      size: "2048x1152",
      quality: "high",
      output_format: "png"
    })
  });

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

## Body

<ParamField body="model" type="string" required>
  图像生成模型。推荐固定使用 `gpt-image-2`。
</ParamField>

<ParamField body="prompt" type="string" required>
  图像生成提示词。
</ParamField>

<ParamField body="n" type="integer">
  生成图片张数，默认 `1`。
</ParamField>

<ParamField body="size" type="string">
  输出尺寸。支持 `auto` 或具体像素尺寸，例如 `1024x1024`、`2048x1152`、`3840x2160`。
</ParamField>

<ParamField body="quality" type="string">
  图片质量参数，例如 `low`、`medium`、`high`。
</ParamField>

<ParamField body="response_format" type="string">
  旧 OpenAI Images 客户端兼容字段。GPT Image 2 转发到官方 OpenAI 上游时，服务端会移除该字段；不要依赖它强制指定 `url` 或 `b64_json`。
</ParamField>

<ParamField body="output_format" type="string">
  输出图片格式，例如 `png`、`jpeg`、`webp`。
</ParamField>

<ParamField body="output_compression" type="integer">
  输出压缩比例，适用于 `jpeg`、`jpg`、`webp`，范围 `0` 到 `100`。
</ParamField>

<ParamField body="stream" type="boolean">
  是否启用流式返回。开启后返回 OpenAI-compatible SSE 事件。
</ParamField>

## Response

<ResponseExample>
  ```json theme={null}
  {
    "created": 1710000000,
    "data": [
      {
        "b64_json": "..."
      }
    ]
  }
  ```
</ResponseExample>

## 错误

| 状态码     | 场景      | 说明                    |
| ------- | ------- | --------------------- |
| 400     | 参数不合法   | 模型、尺寸、格式或请求体不符合要求。    |
| 401     | 未认证     | 缺少或错误的 Bearer Token。  |
| 403     | 无图片权限   | API Key 所属分组没有图片生成能力。 |
| 429     | 并发或速率限制 | 降低请求频率后重试。            |
| 500/503 | 上游失败    | 上游账号、渠道或网关临时不可用。      |

## 注意事项

* 该接口是同步 OpenAI Images 兼容响应，不返回异步任务 ID。
* 非流式响应通常包含 `data` 数组；每个结果可能包含 `url` 或 `b64_json`，具体取决于上游能力和渠道配置。
* 对 GPT Image 2 不支持的字段，服务端会按兼容策略处理。
* 非 OpenAI-compatible 分组不能调用 Images 接口。