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

# Doubao Seedream 生成图像 API

> 使用 `POST /v1/images/generations` 调用 Doubao Seedream 系列图像生成接口。

# Doubao Seedream 生成图像 API

Doubao Seedream 系列通过统一图像生成入口发起请求，适合文生图，也支持通过 `image` 数组传参考图做图生图。

* 统一入口为 `POST /v1/images/generations`。
* `model` 传具体 Seedream 型号即可。
* `size` 直接传像素尺寸字符串，例如 `2048x2048`、`2560x1440`。
* `image` 支持图片 URL 或 Base64 数组，适合图生图和多参考图场景。
* 返回通常兼容 OpenAI Images 风格，常见为 `url` 或 `b64_json`。

## 当前可用模型

* `doubao-seedream-4-0-250828`
* `seedream-4-0-250828`
* `doubao-seedream-4-5-251128`
* `doubao-seedream-5-0-260128`

## 方法与路径

```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": "doubao-seedream-4-0-250828",
      "prompt": "一只可爱的小海獭，阳光下漂浮在海面，电影感，高清细节",
      "n": 1,
      "size": "2048x2048"
    }'
  ```

  ```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": "doubao-seedream-4-0-250828",
          "prompt": "一只可爱的小海獭，阳光下漂浮在海面，电影感，高清细节",
          "n": 1,
          "size": "2048x2048",
      },
      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: "doubao-seedream-4-0-250828",
      prompt: "一只可爱的小海獭，阳光下漂浮在海面，电影感，高清细节",
      n: 1,
      size: "2048x2048",
    }),
  });

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

## 图生图示例

```json theme={null}
{
  "model": "doubao-seedream-4-5-251128",
  "prompt": "保留参考图主体和氛围，重绘成更高级的广告海报",
  "n": 1,
  "size": "2560x1440",
  "image": [
    "BASE64_IMAGE_1",
    "https://example.com/reference-2.png"
  ]
}
```

## 响应示例

<ResponseExample>
  ```json 200 - URL theme={null}
  {
    "created": 1735689600,
    "data": [
      {
        "url": "https://.../images/doubao-img-abc123.png",
        "revised_prompt": "一只可爱的小海獭，阳光下漂浮在海面，电影感，高清细节"
      }
    ]
  }
  ```

  ```json 200 - Base64 theme={null}
  {
    "created": 1735689600,
    "data": [
      {
        "b64_json": "iVBORw0KGgoAAAANSUhEUgAA...",
        "revised_prompt": "一只可爱的小海獭，阳光下漂浮在海面，电影感，高清细节"
      }
    ]
  }
  ```
</ResponseExample>

## 认证

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

## Body

<ParamField body="model" type="string" required>
  Doubao Seedream 模型名称。常见值包括 `doubao-seedream-4-0-250828`、`doubao-seedream-4-5-251128`、`doubao-seedream-5-0-260128`。
</ParamField>

<ParamField body="prompt" type="string" required>
  生成提示词。文生图和图生图都建议显式传入。
</ParamField>

<ParamField body="n" type="integer">
  生成数量。该字段可选；建议显式传 `1`，便于获得稳定的返回结构。
</ParamField>

<ParamField body="size" type="string">
  输出尺寸，直接传宽高像素值。Doubao 这组模型通常按固定比例映射到固定像素尺寸。
</ParamField>

<ParamField body="image" type="array<string> | string">
  可选参考图输入。支持图片链接或 Base64 数组，图生图时把参考图放进这个字段。
</ParamField>

<ParamField body="response_format" type="string">
  可选返回格式。常见值为 `url`、`b64_json`。若不传，最终返回格式取决于模型和渠道能力。
</ParamField>

<ParamField body="quality" type="string">
  质量字段。接口可接收该字段，是否生效取决于具体 Doubao 模型和渠道能力。
</ParamField>

<ParamField body="style" type="string | object">
  风格字段。接口可接收该字段，是否生效取决于具体 Doubao 模型和渠道能力。
</ParamField>

<ParamField body="background" type="string | object">
  背景控制字段。接口可接收该字段，是否生效取决于具体 Doubao 模型和渠道能力。
</ParamField>

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

## 尺寸映射

Doubao 这组模型通常按宽高比映射到固定像素尺寸，可按下表使用：

| 宽高比    | `size` 值    |
| ------ | ----------- |
| `1:1`  | `2048x2048` |
| `4:3`  | `2304x1728` |
| `3:4`  | `1728x2304` |
| `16:9` | `2560x1440` |
| `9:16` | `1440x2560` |
| `3:2`  | `2496x1664` |
| `2:3`  | `1664x2496` |
| `21:9` | `3024x1296` |

<Info>
  和 Gemini 不同，Doubao 这组接口不是传“比例枚举”，而是把比例映射成具体像素尺寸，再把该尺寸写入 `size`。
</Info>

## 文生图 vs 图生图

| 场景  | 关键字段                        | 说明                 |
| --- | --------------------------- | ------------------ |
| 文生图 | `prompt` + `size`           | 最基础写法              |
| 图生图 | `prompt` + `size` + `image` | `image` 可放一张或多张参考图 |

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

## 异步调用

Doubao Seedream 系列也支持通过异步入口提交任务：

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

请求体字段与本页同步生图基本一致，`model` 可以传 `doubao-seedream-4-0-250828`、`doubao-seedream-4-5-251128` 或 `doubao-seedream-5-0-260128`。提交成功后读取返回的 `id` / `task_id`，再通过 `GET /v1/images/generations/async/{taskId}` 查询状态和结果。

## 相关接口

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