> ## 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.

# OpenAI Images 兼容图像生成

> 使用 `POST /v1/images/generations` 调用统一图像生成入口，按 `model` 选择 `gpt-image-1`、`dall-e-3`、`dall-e-2` 等兼容模型。

# OpenAI Images 兼容图像生成

使用统一图像生成入口提交文生图请求，返回 OpenAI Images 风格响应。

* 统一的图像生成接口，通过 `model` 选择不同图像模型。
* 保持 OpenAI Images 响应结构：`created` + `data[]`。
* 支持 `url` 和 `b64_json` 两种返回格式。
* `dall-e-2`、`dall-e-3` 会按各自支持的尺寸范围校验。
* `n` 不传或显式传 `0` 时会按 `1` 处理。

## 方法与路径

```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-1",
      "prompt": "一张极简风格的 API 平台首页插图，白色背景，蓝绿色点缀",
      "n": 1,
      "size": "1024x1024",
      "quality": "auto",
      "response_format": "url"
    }'
  ```

  ```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-1",
          "prompt": "一张极简风格的 API 平台首页插图，白色背景，蓝绿色点缀",
          "n": 1,
          "size": "1024x1024",
          "quality": "auto",
          "response_format": "url",
      },
      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-1",
      prompt: "一张极简风格的 API 平台首页插图，白色背景，蓝绿色点缀",
      n: 1,
      size: "1024x1024",
      quality: "auto",
      response_format: "url",
    }),
  });

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

## 响应示例

<ResponseExample>
  ```json 200 - URL theme={null}
  {
    "created": 1735689600,
    "data": [
      {
        "url": "https://.../images/img-abc123.png",
        "revised_prompt": "一张极简风格的 API 平台首页插图，白色背景，蓝绿色点缀"
      }
    ]
  }
  ```

  ```json 200 - Base64 theme={null}
  {
    "created": 1735689600,
    "data": [
      {
        "b64_json": "iVBORw0KGgoAAAANSUhEUgAA...",
        "revised_prompt": "一张极简风格的 API 平台首页插图，白色背景，蓝绿色点缀"
      }
    ]
  }
  ```

  ```json 400 theme={null}
  {
    "error": {
      "message": "size must be one of 1024x1024, 1024x1792 or 1792x1024 for dall-e-3",
      "type": "invalid_request_error",
      "param": "",
      "code": "invalid_request"
    }
  }
  ```

  ```json 401 theme={null}
  {
    "error": {
      "message": "Invalid API key provided",
      "type": "invalid_request_error",
      "param": "",
      "code": "invalid_api_key"
    }
  }
  ```

  ```json 402 theme={null}
  {
    "error": {
      "message": "用户额度不足",
      "type": "new_api_error",
      "param": "",
      "code": "insufficient_user_quota"
    }
  }
  ```

  ```json 429 theme={null}
  {
    "error": {
      "message": "当前请求频率过高，请稍后再试",
      "type": "new_api_error",
      "param": "",
      "code": "too_many_requests"
    }
  }
  ```

  ```json 500 theme={null}
  {
    "error": {
      "message": "bad response body",
      "type": "new_api_error",
      "param": "",
      "code": "bad_response_body"
    }
  }
  ```
</ResponseExample>

## 认证

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

## Body

<ParamField body="model" type="string" required>
  模型名称。该字段必填。
</ParamField>

<ParamField body="prompt" type="string">
  生成提示词。对于图像生成语义应视为必填；具体校验规则取决于目标模型和渠道能力。
</ParamField>

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

<ParamField body="size" type="string">
  输出尺寸。`dall-e-2` 只接受 `256x256`、`512x512`、`1024x1024`；`dall-e-3` 只接受 `1024x1024`、`1024x1792`、`1792x1024`。
</ParamField>

<Info>
  如果你实际使用的是 `gpt-image-2-pro`，还可以使用 `1:1(2K)`、`4:3(2K)`、`3:2(2K)`、`2:3(2K)`、`16:9(2K)`、`9:16(2K)`、`1:1(4K)`、`4:3(4K)`、`3:2(4K)`、`2:3(4K)`、`16:9(4K)`、`9:16(4K)` 这类高分档位。完整映射见 [图像模型支持矩阵](/api-reference/images/model-matrix)。
</Info>

<ParamField body="quality" type="string">
  图像质量。`dall-e-3` 默认补成 `standard`；`gpt-image-1` 默认补成 `auto`。
</ParamField>

<ParamField body="response_format" type="string">
  返回格式，常见值为 `url`、`b64_json`。当请求 `b64_json` 或 `base64` 时，返回 Base64 图像数据。
</ParamField>

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

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

<ParamField body="watermark" type="boolean">
  显式水印开关。`false` 与不传语义不同：不传表示交给默认策略，传 `false` 表示明确关闭。
</ParamField>

## Response

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

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

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

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

<ResponseField name="metadata" type="object">
  附加元数据。是否存在取决于具体渠道。
</ResponseField>

## 使用场景

### 基础生图

```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-1",
    "prompt": "生成一张简洁的产品海报"
  }'
```

### 高质量 DALL·E 3

```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": "dall-e-3",
    "prompt": "一张科幻城市夜景插画",
    "size": "1792x1024",
    "quality": "hd",
    "response_format": "url"
  }'
```

### Base64 输出

```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-1",
    "prompt": "生成一张简洁的图标集海报",
    "response_format": "b64_json"
  }'
```

## 注意事项

<Warning>
  这个页面只描述统一入口的公共语义，不代表所有图像渠道都支持完全相同的字段。像 `style`、`background`、`watermark` 等字段是否真正生效，取决于最终命中的渠道。
</Warning>

## 相关接口

* [OpenAI Images 兼容概览](./overview)
* [OpenAI Images 兼容图像编辑](./edit)
* [上传图片](/api-reference/uploads/image-upload)