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

# doubao-seedream-5.0

通过 OpenAI 兼容接口调用 Doubao Seedream 5.0 系列图像生成模型，覆盖 `doubao-seedream-5.0`、`doubao-seedream-5.0-lite`、`doubao-seedream-5.0-pro` 三个模型，支持文生图、图生图。

所有请求都经由 GregAPI 转发到火山方舟，不需要自行签名，只需在 Header 中携带 GregAPI API Key。

```bash theme={null}
export BASE_URL="https://api.gregapi.com/v1"
export TOKEN="oh-xxxxxxxxxxxxxxxx"
```

统一使用：

```http theme={null}
Authorization: Bearer <TOKEN>
Content-Type: application/json
```

## 模型总览

| 模型 | 模型 ID（版本映射） | 分辨率 | 输出格式 | 特色能力 |
| - | - | - | - | - |
| `doubao-seedream-5.0` | `doubao-seedream-5-0-260128` | `2K` / `3K` / `4K` | png / jpeg | 文生组图、多图生组图、流式输出、联网搜索 |
| `doubao-seedream-5.0-lite` | `doubao-seedream-5-0-lite-260128` | `2K` / `3K` / `4K` | png / jpeg | 轻量高性价比；组图、流式输出、联网搜索 |
| `doubao-seedream-5.0-pro` | `doubao-seedream-5-0-pro-260628` | `1K` / `1.5K` / `2K` | png / jpeg | 交互编辑、图层拆分 |

### 各模型说明

* `doubao-seedream-5.0`：Seedream 5.0 基础版，支持联网检索，增强知识广度、参考一致性与专业场景生成质量；支持文生图、图生图、文生组图、多图生组图、流式输出。
* `doubao-seedream-5.0-lite`：Seedream 5.0 轻量版，速度与成本更优，能力与基础版一致（组图、流式、联网搜索）。
* `doubao-seedream-5.0-pro`：面向高精度创作，支持交互编辑（坐标/框选/箭头精准定位）与图层拆分（1 张底图 + 最多 16 个图层）；暂不支持文生组图、流式输出与联网搜索。

## 接口说明

### 端点

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

### 请求头

```http theme={null}
Authorization: Bearer <TOKEN>
Content-Type: application/json
```

控制台侧需要将 `doubao-seedream-*` 模型名绑定到 Doubao / VolcArk 渠道（`ChannelTypeVolcArk`），即可通过统一的 OpenAI 风格接口访问。

## 请求参数

### 基础参数（OpenAI 兼容）

| 参数 | 类型 | 必填 | 说明 |
| - | - | - | - |
| `model` | string | ✅ | `doubao-seedream-5.0` / `doubao-seedream-5.0-lite` / `doubao-seedream-5.0-pro` |
| `prompt` | string | ✅ | 图片描述文本，建议不超过 300 汉字或 600 英文单词 |
| `size` | string | ❌ | 分辨率档位或精确尺寸，档位因模型而异：`5.0`/`5.0-lite` 为 `2K`/`3K`/`4K`，`5.0-pro` 为 `1K`/`1.5K`/`2K`；也可传像素尺寸如 `2048x2048` |
| `n` | integer | ❌ | 单图请求省略此字段；普通单图生成不支持 `n>1` |
| `response_format` | string | ❌ | `url`（默认）或 `b64_json` |
| `quality` | string | ❌ | 图片质量，例如 `high` / `standard` |
| `style` | string | ❌ | 图片风格，例如 `vivid` / `natural` |

`stream=true`、`tools`、`sequential_image_generation` 和 `sequential_image_generation_options` 等组图/流式参数仅对 `5.0` 与 `5.0-lite` 等支持组图、流式的模型生效；`5.0-pro` 不支持这些参数。

### 火山方舟专用参数

| 参数 | 类型 | 说明 |
| - | - | - |
| `image` | string / string\[] | 参考图片 URL 或完整 Data URI，不接受裸 Base64；单张可传字符串或单元素数组 |
| `watermark` | boolean | 是否添加水印，默认 `true` |
| `output_format` | string | 输出格式，`png` / `jpeg` |

### Base64 参考图格式

`image` 中的每张参考图必须是公网可访问的图片 URL，或以下完整 Data URI：

* JPEG：`data:image/jpeg;base64,<完整Base64>`
* PNG：`data:image/png;base64,<完整Base64>`

MIME 类型必须与图片实际格式一致，逗号后紧接完整 Base64，不添加空格或换行。只传 `/9j/...` 或 `iVBOR...` 这样的裸 Base64，会被当作 URL 解析，可能返回 HTTP 400、`InvalidParameter`。`response_format="b64_json"` 只控制输出格式，不会为输入的 `image` 自动补前缀。

## 响应格式

### 非流式响应

```json theme={null}
{
  "created": 1589478378,
  "data": [
    {
      "url": "https://...",
      "size": "2048x2048"
    }
  ],
  "usage": {
    "output_tokens": 16384,
    "total_tokens": 16384
  }
}
```

### Base64 响应（`response_format=b64_json`）

```json theme={null}
{
  "created": 1589478378,
  "data": [
    {
      "b64_json": "iVBORw0KGgoAAAANSUhEUgAA..."
    }
  ]
}
```

`b64_json` 是不带 Data URI 前缀的裸 Base64。若要将生成结果再次作为 `image` 输入，需要补上 `data:image/jpeg;base64,` 或 `data:image/png;base64,` 前缀。

## 使用示例

### 文生图

```bash theme={null}
curl -X POST "https://api.gregapi.com/v1/images/generations" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "doubao-seedream-5.0-pro",
  "prompt": "一只可爱的熊猫在竹林里吃竹子，阳光透过树叶洒下斑驳的光影",
  "size": "2K",
  "response_format": "url"
}'
```

如图生图需传入参考图，或使用 `doubao-seedream-5.0` / `doubao-seedream-5.0-lite`，只需替换 `model`（与可选 `size` 档位）。

### 图生图（Base64 Data URI）

将 `<完整JPEG图片Base64>` 替换为 JPEG 图片的完整 Base64，保留前面的 `data:image/jpeg;base64,`。PNG 图片改用 `data:image/png;base64,`。

```bash theme={null}
curl -X POST "https://api.gregapi.com/v1/images/generations" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  --data-raw '{
  "model": "doubao-seedream-5.0-pro",
  "prompt": "将这张图片转换为水彩画风格",
  "image": [
    "data:image/jpeg;base64,<完整JPEG图片Base64>"
  ],
  "size": "2K",
  "response_format": "b64_json"
}'
```

成功后从 `data[0].b64_json` 读取并解码图片。单图也可将 `image` 写成一个完整 Data URI 字符串。

## 常见问题

### 如何选择模型？

* 需要高精度编辑、精准定位、图层拆分：用 `doubao-seedream-5.0-pro`。
* 需要组图、流式输出、联网搜索，或追求更强知识广度与一致性：用 `doubao-seedream-5.0` 或 `doubao-seedream-5.0-lite`（lite 成本更低）。

### 图片 URL 有效期多久？

生成的图片 URL 通常在 24 小时内有效，请在有效期内下载并保存到自己的存储。

### 如何去除水印？

在请求体中设置 `"watermark": false` 即可关闭模型水印（前提是当前模型与账号配置允许关闭）。

### 图生图时图片传不上去怎么办？

* 确认 `image` 字段使用公网可访问的 HTTPS URL，或完整 Data URI（如 `data:image/jpeg;base64,<完整Base64>`）；
* 出现 `InvalidParameter` / `invalid url specified` 时，检查是否误传了裸 Base64，并补上与实际格式匹配的前缀；
* `response_format="b64_json"` 是输出设置，不能代替输入图片所需的 Data URI 前缀；
* 图片较大时建议预先压缩，避免超过上游大小限制。

## 计费说明

* 按成功生成的图片张数计费；
* 生成失败的图片通常不计费（以上游账单为准）；
* 具体价格请在后台「模型价格管理」中查看 Doubao Seedream 相关条目。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.