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

# Seedream 系列

> 使用 AIOAGI 图像接口调用 Seedream 文生图、图生图、多图融合和组图输出能力。

Seedream 系列通过 `POST /images/generations` 调用。你可以使用 AIOAGI API Key，并将基础地址设置为 `https://api.aiearth.dev/v1` 或 `https://api.aiearth.vip/v1`。

<Warning>
  Seedream 模型名称、尺寸范围、价格和参数支持可能变化。生产调用前，请在 **控制台**、`GET /models` 或 **开发者指南** 中核对当前可用模型。
</Warning>

## 接口概览

| 能力   | 接口                    | 方法     | 说明                                               |
| ---- | --------------------- | ------ | ------------------------------------------------ |
| 文生图  | `/images/generations` | `POST` | 根据 `prompt` 生成图片。                                |
| 图生图  | `/images/generations` | `POST` | 通过 `image` 传入参考图。                                |
| 多图融合 | `/images/generations` | `POST` | 通过 `image` 数组传入多张参考图。                            |
| 组图输出 | `/images/generations` | `POST` | 使用 `sequential_image_generation: auto` 生成一组关联图片。 |

## 文生图示例

```bash theme={null}
export AIO_API_KEY="sk-your-api-key"
export AIO_BASE_URL="https://api.aiearth.dev/v1"

curl "$AIO_BASE_URL/images/generations" \
  -H "Authorization: Bearer $AIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedream-5-0-260128",
    "prompt": "充满活力的特写编辑肖像，模特眼神犀利，头戴雕塑感帽子，色彩拼接丰富，眼部焦点锐利，景深较浅，具有杂志封面的美学风格，采用中画幅拍摄，工作室灯光效果强烈。",
    "size": "2K",
    "output_format": "png",
    "response_format": "url",
    "watermark": false
  }'
```

## 图生图示例

```bash theme={null}
curl "$AIO_BASE_URL/images/generations" \
  -H "Authorization: Bearer $AIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedream-5-0-260128",
    "prompt": "保持主体姿态和构图不变，将服装材质从银色金属改为透明玻璃质感，光影从反射变为折射。",
    "image": "https://example.com/source.png",
    "size": "2K",
    "output_format": "png",
    "response_format": "url",
    "watermark": false
  }'
```

## 多图融合示例

如果你希望模型基于多张参考图生成一张结果，把 `image` 设为图片数组，并将 `sequential_image_generation` 设为 `disabled`。

```json theme={null}
{
  "model": "doubao-seedream-5-0-260128",
  "prompt": "将图1中的人物换上图2中的服装，保持人物姿态和画面光线自然。",
  "image": [
    "https://example.com/person.png",
    "https://example.com/clothes.png"
  ],
  "sequential_image_generation": "disabled",
  "size": "2K",
  "output_format": "png",
  "watermark": false
}
```

## 组图输出示例

如果你希望输出一组关联图片，把 `sequential_image_generation` 设为 `auto`，并用 `sequential_image_generation_options.max_images` 控制最多输出数量。

```json theme={null}
{
  "model": "doubao-seedream-5-0-260128",
  "prompt": "生成3张同一女孩和奶牛玩偶在游乐园开心乘坐过山车的图片，分别表现早晨、中午和晚上。",
  "image": [
    "https://example.com/character.png",
    "https://example.com/toy.png"
  ],
  "sequential_image_generation": "auto",
  "sequential_image_generation_options": {
    "max_images": 3
  },
  "size": "2K",
  "output_format": "png",
  "response_format": "url",
  "watermark": false
}
```

## 核心参数

| 参数                                               | 类型                 | 说明                                                 |
| ------------------------------------------------ | ------------------ | -------------------------------------------------- |
| `model`                                          | `string`           | 必填。Seedream 模型 ID，例如 `doubao-seedream-5-0-260128`。 |
| `prompt`                                         | `string`           | 必填。用于生成或编辑图像的提示词，支持中文和英文。                          |
| `image`                                          | `string` 或 `array` | 可选。图生图、多图融合和多参考图任务使用。支持 URL 或 Base64。              |
| `size`                                           | `string`           | 可选。可使用 `2K`、`3K`、`4K` 或具体像素尺寸。不同模型支持范围不同。          |
| `response_format`                                | `string`           | 可选。`url` 或 `b64_json`。默认通常为 `url`。                 |
| `output_format`                                  | `string`           | 可选。Seedream 5.0 支持 `png` 或 `jpeg`。默认通常为 `jpeg`。    |
| `watermark`                                      | `boolean`          | 可选。是否添加水印。默认通常为 `true`。                            |
| `sequential_image_generation`                    | `string`           | 可选。`auto` 表示启用组图判断，`disabled` 表示只生成单张图。            |
| `sequential_image_generation_options.max_images` | `integer`          | 可选。组图输出最多图片数。当前资料中范围为 `1` 到 `15`。                  |
| `seed`                                           | `integer`          | 仅部分 3.0 模型支持。用于控制随机性。                              |
| `guidance_scale`                                 | `number`           | 仅部分 3.0 模型支持。用于控制提示词一致程度。                          |

## 返回说明

* `response_format: "url"` 通常返回图片下载链接。链接可能有有效期，请及时下载并转存。
* `response_format: "b64_json"` 返回 Base64 图片数据。你需要先解码再保存。
* 响应中可能包含 `usage` 字段。字段结构可能随模型和参数变化。

## 排障建议

* 遇到 `401`，检查 API Key 和 `Authorization: Bearer sk-...` 请求头。
* 遇到 `403`，检查账户余额、Token 组额度和模型权限。
* 遇到 `404` 或 `model_not_found`，调用 `GET /models` 核对模型 ID。
* 遇到参数错误，先检查 `size`、`image`、`response_format`、`output_format` 是否被当前模型支持。