火山豆包（Doubao）绘画模型格式

# 火山豆包（Doubao）绘画模型格式
请求地址
`POST /v1/images/generations`

# 豆包图像生成 API 文档

本文档根据实际 CURL 测试结果整理，用于说明如何通过 `https://api.cxsee.com/v1/images/generations` 接口调用豆包 Seedream 图像生成模型，完成文生图或带参考图的图像生成任务。

---

## 1. 接口说明

### 接口地址

```http
POST https://api.cxsee.com/v1/images/generations
```

### 接口功能

用于调用豆包图像生成模型，根据用户输入的文本提示词生成图片。

部分模型支持传入参考图片，可用于图像参考、风格参考、主体参考等场景。

---

## 2. 请求方式

```http
POST
```

---

## 3. 请求头 Headers

| 参数名 | 必填 | 示例 | 说明 |
|---|---|---|---|
| `Content-Type` | 是 | `application/json` | 请求体格式，固定为 JSON |
| `Authorization` | 是 | `Bearer sk-xxxx` | API Key 鉴权信息 |

示例：

```http
Content-Type: application/json
Authorization: Bearer sk-xxxxxxxxxxxxxxxx
```

> 注意：请勿在前端代码、公开仓库、截图或文档中暴露真实 API Key。

---

# 4. CURL 调用示例

以下是已测试成功的豆包图像生成请求示例。

```bash
curl https://api.cxsee.com/v1/images/generations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxxxxxxxxxxxxxxx" \
  -d '{
    "model": "doubao-seedream-4-5-251128",
    "prompt": "一只可爱的卡通猫，风格简洁",
    "size": "1920x1920",
    "n": 1
  }'
```

---

# 5. 请求参数说明

## Body 参数

| 参数名 | 类型 | 必填 | 示例 | 说明 |
|---|---|---|---|---|
| `model` | string | 是 | `doubao-seedream-4-5-251128` | 使用的图像生成模型 |
| `prompt` | string | 是 | `一只可爱的卡通猫，风格简洁` | 图像生成提示词 |
| `size` | string | 否 | `1920x1920` / `2K` | 图片尺寸或清晰度规格 |
| `n` | integer | 否 | `1` | 生成图片数量 |
| `output_format` | string | 否 | `png` / `jpeg` | 输出图片格式，是否支持以实际模型为准 |
| `watermark` | boolean | 否 | `false` | 是否添加水印，是否支持以实际模型为准 |

---

# 6. 请求体示例

```json
{
  "model": "doubao-seedream-4-5-251128",
  "prompt": "一只可爱的卡通猫，风格简洁",
  "size": "1920x1920",
  "n": 1
}
```

---

# 7. 成功响应示例

实际测试返回如下：

```json
{
  "model": "doubao-seedream-4-5-251128",
  "created": 1782680992,
  "data": [
    {
      "url": "https://ark-content-generation-v2-cn-beijing.tos-cn-beijing.volces.com/xxx.jpeg?...",
      "size": "1920x1920"
    }
  ],
  "usage": {
    "generated_images": 1,
    "output_tokens": 14400,
    "total_tokens": 14400
  }
}
```

![](/uploads/editor/20260629/img_6a419194f14932.77987464.png)

![](/uploads/editor/20260629/img_6a4191b99b42a7.97373893.png)

![](/uploads/editor/20260629/img_6a4191d4ae3432.56333630.png)

---

# 8. 响应字段说明

| 字段名 | 类型 | 说明 |
|---|---|---|
| `model` | string | 实际使用的模型名称 |
| `created` | integer | 图片生成时间戳 |
| `data` | array | 生成图片结果列表 |
| `usage` | object | 本次请求的用量统计 |

---

## data 字段说明

| 字段名 | 类型 | 说明 |
|---|---|---|
| `url` | string | 生成图片的访问地址 |
| `size` | string | 生成图片尺寸 |

示例：

```json
{
  "url": "https://example.com/generated-image.jpeg",
  "size": "1920x1920"
}
```

---

## usage 字段说明

| 字段名 | 类型 | 说明 |
|---|---|---|
| `generated_images` | integer | 本次生成的图片数量 |
| `output_tokens` | integer | 输出消耗的 token 数 |
| `total_tokens` | integer | 总 token 消耗数量 |

---

# 9. 可用模型示例

根据当前测试，以下模型可用于图像生成接口：

```text
doubao-seedream-4-5-251128
```

测试成功接口：

```http
POST /v1/images/generations
```

测试成功请求：

```json
{
  "model": "doubao-seedream-4-5-251128",
  "prompt": "一只可爱的卡通猫，风格简洁",
  "size": "1920x1920",
  "n": 1
}
```

---

# 10. 图片尺寸 size 参数说明

`size` 用于控制生成图片的尺寸或清晰度。

## 方式一：使用具体分辨率

例如：

```json
"size": "1920x1920"
```

常见示例：

```text
1024x1024
1920x1080
1080x1920
1920x1920
2048x2048
```

是否全部支持，取决于具体模型和平台配置。

---

## 方式二：使用清晰度规格

部分豆包 Seedream 模型支持使用：

```text
1K
2K
3K
4K
```

作为 `size` 参数。

例如：

```json
"size": "2K"
```

---

# 11. 不同模型的 size 可选值参考

以下信息根据官方说明整理，实际以平台支持情况为准。

| 模型系列 | size 可选值 | 默认值 |
|---|---|---|
| `doubao-seedream-5.0-lite` | `2K`、`3K`、`4K` | `2048x2048` |
| `doubao-seedream-4.5` | `1K`、`2K`、`4K` | `2048x2048` |
| `doubao-seedream-4.0` | `2K`、`4K` | `2048x2048` |

> 注：如果使用具体分辨率，如 `1920x1920`，需要确认当前模型是否支持该尺寸。

---

# 12. 图片输入说明：URL 或 Base64

部分豆包 Seedream 模型支持传入参考图片。

支持图片输入的模型包括：

```text
doubao-seedream-5.0-lite
doubao-seedream-4.5
doubao-seedream-4.0
```

这些模型支持：

```text
单图输入
多图输入
```

图片可以通过以下方式传入：

```text
图片 URL
Base64 编码
```

---

## 12.1 图片 URL 示例

```json
{
  "model": "doubao-seedream-4-5-251128",
  "prompt": "参考这张图片的主体，生成一张卡通风格头像",
  "image": "https://example.com/cat.png",
  "size": "1920x1920",
  "n": 1
}
```

---

## 12.2 Base64 图片示例

```json
{
  "model": "doubao-seedream-4-5-251128",
  "prompt": "参考输入图片，生成简洁插画风格版本",
  "image": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...",
  "size": "1920x1920",
  "n": 1
}
```

---

## 12.3 多图输入示例

部分模型最多支持传入 14 张参考图。

```json
{
  "model": "doubao-seedream-4-5-251128",
  "prompt": "参考这些图片的主体和色彩风格，生成一张新的商业插画",
  "image": [
    "https://example.com/ref1.png",
    "https://example.com/ref2.jpeg",
    "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..."
  ],
  "size": "2K",
  "n": 1
}
```

> 字段名 `image`、`images` 或其他名称可能因平台实现不同而不同。如果当前接口不支持图片输入，请以平台实际接口定义为准。

---

# 13. 参考图片限制

对于 `doubao-seedream-5.0-lite`、`doubao-seedream-4.5`、`doubao-seedream-4.0`，参考图片限制如下。

## 13.1 图片格式

支持格式：

```text
jpeg
png
webp
bmp
tiff
gif
heic
heif
```

其中：

```text
webp、bmp、tiff、gif、heic、heif 为 doubao-seedream-5.0-lite / 4.5 / 4.0 新增支持格式。
```

---

## 13.2 图片宽高比限制

宽高比范围：

```text
[1/16, 16]
```

也就是：

```text
图片宽度 / 图片高度 >= 1/16
图片宽度 / 图片高度 <= 16
```

适用模型：

```text
doubao-seedream-5.0-lite
doubao-seedream-4.5
doubao-seedream-4.0
```

---

## 13.3 图片宽高限制

图片宽度和高度需要满足：

```text
宽度 > 14 px
高度 > 14 px
```

---

## 13.4 图片大小限制

单张图片大小：

```text
不超过 30MB
```

---

## 13.5 图片总像素限制

单张图片总像素不超过：

```text
6000 x 6000 = 36,000,000 px
```

这里限制的是：

```text
图片宽度 × 图片高度
```

而不是单独限制宽度或高度。

例如：

```text
6000 x 6000 = 36,000,000 px，允许
8000 x 4000 = 32,000,000 px，可能允许
8000 x 5000 = 40,000,000 px，超过限制
```

---

## 13.6 参考图数量限制

`doubao-seedream-5.0-lite`、`doubao-seedream-4.5`、`doubao-seedream-4.0` 最多支持传入：

```text
14 张参考图
```

---

# 14. 文生图完整示例

```bash
curl https://api.cxsee.com/v1/images/generations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxxxxxxxxxxxxxxx" \
  -d '{
    "model": "doubao-seedream-4-5-251128",
    "prompt": "一只可爱的卡通猫，圆圆的眼睛，浅色背景，简洁插画风格，画面干净，适合作为头像",
    "size": "1920x1920",
    "n": 1
  }'
```

---

# 15. 高质量提示词示例

如果希望图片效果更稳定，可以把提示词写得更完整。

## 示例一：卡通头像

```text
一只可爱的卡通猫，圆圆的大眼睛，柔和的浅色背景，简洁插画风格，线条干净，色彩明亮，适合作为社交媒体头像，正方形构图，高质量细节。
```

请求示例：

```json
{
  "model": "doubao-seedream-4-5-251128",
  "prompt": "一只可爱的卡通猫，圆圆的大眼睛，柔和的浅色背景，简洁插画风格，线条干净，色彩明亮，适合作为社交媒体头像，正方形构图，高质量细节。",
  "size": "1920x1920",
  "n": 1
}
```

---

## 示例二：商业海报

```text
一张现代科技风格的产品宣传海报，主体是一台未来感智能设备，蓝紫色渐变背景，柔和光效，高级商业摄影质感，画面简洁，中心构图，适合官网 Banner。
```

---

## 示例三：写实摄影

```text
一张写实风格的室内摄影作品，阳光从窗户洒入房间，桌面上放着一杯咖啡和一本打开的书，浅景深，自然光，温暖色调，高级生活方式摄影。
```

---

# 16. Python 调用示例

```python
import requests

url = "https://api.cxsee.com/v1/images/generations"

headers = {
    "Content-Type": "application/json",
    "Authorization": "Bearer sk-xxxxxxxx
	
是的，上一条输出确实断在了 **Python 调用示例** 这里，内容没有完整输出完。

我可以继续补全后半部分。下面从 **Python 调用示例** 开始接着写：

---

# 16. Python 调用示例

```python
import requests

url = "https://api.cxsee.com/v1/images/generations"

headers = {
    "Content-Type": "application/json",
    "Authorization": "Bearer sk-xxxxxxxxxxxxxxxx"
}

payload = {
    "model": "doubao-seedream-4-5-251128",
    "prompt": "一只可爱的卡通猫，圆圆的大眼睛，柔和的浅色背景，简洁插画风格，线条干净，色彩明亮，适合作为社交媒体头像",
    "size": "1920x1920",
    "n": 1
}

response = requests.post(url, headers=headers, json=payload)

print(response.status_code)
print(response.json())
```

---

# 17. JavaScript 调用示例

```javascript
const response = await fetch("https://api.cxsee.com/v1/images/generations", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer sk-xxxxxxxxxxxxxxxx"
  },
  body: JSON.stringify({
    model: "doubao-seedream-4-5-251128",
    prompt: "一只可爱的卡通猫，圆圆的大眼睛，柔和的浅色背景，简洁插画风格，线条干净，色彩明亮，适合作为社交媒体头像",
    size: "1920x1920",
    n: 1
  })
});

const data = await response.json();
console.log(data);
```

---

# 18. 返回图片使用说明

接口成功返回后，生成图片地址位于：

```json
data[0].url
```

例如：

```json
{
  "data": [
    {
      "url": "https://ark-content-generation-v2-cn-beijing.tos-cn-beijing.volces.com/xxx.jpeg",
      "size": "1920x1920"
    }
  ]
}
```

可以直接在浏览器中访问该 URL 下载或展示图片。

需要注意：

```text
返回的图片 URL 通常是临时链接，可能带有过期时间。
```

从测试结果看，返回链接中包含：

```text
X-Tos-Expires=86400
```

表示该链接有效期可能为：

```text
86400 秒，即 24 小时
```

建议业务系统在获取图片 URL 后，及时下载并转存到自己的对象存储或服务器中。

---

# 19. 常见错误说明

## 19.1 模型不支持当前接口

错误示例：

```json
{
  "error": {
    "message": "The parameter `model` specified in the request are not valid: the requested model doubao-seedream-5-0-260128 does not support this api.",
    "type": "BadRequest",
    "param": "model",
    "code": "InvalidParameter"
  }
}
```

原因：

```text
当前传入的 model 不支持 /v1/images/generations 接口。
```

解决方式：

```text
更换为支持图片生成接口的模型，例如 doubao-seedream-4-5-251128，或确认该模型对应的正确接口。
```

---

## 19.2 API Key 无效

可能返回：

```text
401 Unauthorized
```

原因：

```text
Authorization 请求头缺失、格式错误，或 API Key 无效。
```

正确格式：

```http
Authorization: Bearer sk-xxxxxxxxxxxxxxxx
```

---

## 19.3 JSON 格式错误

原因：

```text
请求体不是合法 JSON，例如少了逗号、引号不完整、字段类型错误等。
```

解决方式：

```text
检查 JSON 格式，确保 Content-Type 为 application/json。
```

---

## 19.4 图片尺寸不支持

如果 `size` 设置为模型不支持的尺寸，可能会返回参数错误。

建议优先使用官方支持的尺寸规格，例如：

```text
1K
2K
3K
4K
2048x2048
1920x1920
```

具体以模型实际支持情况为准。

---

# 20. 错误码参考

| HTTP 状态码 | 错误原因 | 处理方式 |
|---|---|---|
| `400` | 请求参数错误 | 检查 `model`、`prompt`、`size`、`n` 等参数 |
| `401` | 鉴权失败 | 检查 API Key 是否正确 |
| `403` | 无模型权限 | 检查当前 Key 是否有模型调用权限 |
| `404` | 接口不存在 | 检查 URL 是否正确 |
| `429` | 请求过于频繁或额度不足 | 降低请求频率或检查账户额度 |
| `500` | 服务端异常 | 稍后重试或联系服务提供方 |

---

# 21. 提示词编写建议

为了获得更好的图像生成效果，建议提示词包含以下信息：

```text
主体 + 风格 + 场景 + 光线 + 构图 + 色彩 + 画质要求
```

例如：

```text
一只可爱的卡通猫，圆圆的大眼睛，坐在浅蓝色背景前，简洁插画风格，柔和光线，中心构图，色彩明亮，线条干净，高质量细节，适合作为头像。
```

比简单提示词：

```text
一只猫
```

效果更稳定。

---

# 22. 推荐提示词模板

## 22.1 卡通头像模板

```text
一个可爱的{主体}头像，圆润造型，简洁插画风格，柔和浅色背景，中心构图，色彩明亮，线条干净，高质量细节，适合作为社交媒体头像。
```

示例：

```text
一个可爱的橘猫头像，圆润造型，简洁插画风格，柔和浅色背景，中心构图，色彩明亮，线条干净，高质量细节，适合作为社交媒体头像。
```

---

## 22.2 商业海报模板

```text
一张{产品/主题}商业宣传海报，现代设计风格，高级质感，主体突出，背景简洁，专业摄影光效，中心构图，适合电商和官网展示。
```

---

## 22.3 写实摄影模板

```text
一张写实摄影风格图片，主体是{主体}，场景位于{场景}，自然光照，浅景深，高级摄影质感，细节清晰，画面干净。
```

---

# 23. 最简可用请求示例

---

# 24. 完整参数示例

```json
{
  "model": "doubao-seedream-4-5-251128",
  "prompt": "一只可爱的卡通猫，圆圆的大眼睛，柔和的浅色背景，简洁插画风格，线条干净，色彩明亮，适合作为社交媒体头像",
  "size": "1920x1920",
  "n": 1,
  "output_format": "jpeg",
  "watermark": false
}
```

> 注意：`output_format` 和 `watermark` 是否生效，需要以当前模型和接口实际支持情况为准。

---

# 25. 安全建议

1. 不要在前端代码中直接暴露 API Key。
2. 不要将真实 API Key 写入公开文档、截图、聊天记录或代码仓库。
3. 建议通过服务端代理调用接口。
4. 建议将 API Key 存放在环境变量中。
5. 如果 API Key 已经泄露，应立即重置或删除。

例如：

```bash
export CXSEE_API_KEY="sk-xxxxxxxxxxxxxxxx"
```

Python 中读取：

```python
import os

api_key = os.getenv("CXSEE_API_KEY")
```

---

# 26. 总结

豆包图像生成 API 的核心调用流程如下：

```text
1. 准备 API Key
2. 选择支持图像生成接口的模型
3. 编写 prompt 提示词
4. 设置 size 和 n
5. 请求 /v1/images/generations
6. 从 data[0].url 获取生成图片地址
```

上一篇：Midjourney 绘画模型格式下一篇：豆包视频（Doubao）模型格式