适用场景

豆包图片生成 API 基于字节跳动 Seedream 3.0 大模型，专为中英文混合提示词优化，平均出图时间 3~4 秒，适合以下场景：

• 内容创作：为博客、公众号、社交媒体一键生成配图，节省设计师人力。
• 营销素材：生成广告创意图、商品概念图、活动海报。
• 设计辅助：快速产出构图参考、风格化草图，支持迭代调整。
• 应用集成：接入聊天机器人、AI 图片工具、自媒体自动化流程。

接口能力边界

• 请求方式：POST
• 请求地址：https://v1.apizero.cn/api/doubao-image
• QPS 限制：2 次/秒，超限会返回 429 错误。
• 图片尺寸：支持 6 种主流分辨率
  • 方形：1024x1024（默认）
  • 宽屏：1792x1024（16:9）、1920x1080（全高清）
  • 竖屏：1024x1792（9:16）
  • 其他：1280x720、720x1280
• 提示词长度：建议 50~300 字符，中英文混合效果尤佳。
• 图片直链有效期：返回的 URL 为字节云 TOS 临时链接，24 小时后失效，务必及时下载或转存。

鉴权与请求参数

鉴权方式

在请求头中携带 API Key：

X-API-Key: YOUR_API_KEY

请求体字段详解

请求体为 JSON 对象，支持以下两个字段：

参数名	类型	是否必填	说明	示例值
prompt	string	是	图片描述文本，支持中英文混合。越具体效果越好，建议包含主体、风格、构图、光线、氛围。长度建议 50~300 字符。	"一只赛博朋克猫在雨夜的霓虹街头，低角度，电影感，Wong Kar-Wai 风格"
size	string	否	图片尺寸，默认 1024x1024。可选值见上文。	"1792x1024"

提示词最佳实践：推荐结构化描述：主体 + 风格 + 构图 + 光线 + 氛围。例如：

“一只赛博朋克猫在雨夜的霓虹街头，低角度，电影感，Wong Kar-Wai 风格”

还可以指定材质、镜头、色调、画家风格等，例如 "水彩画，柔和的粉色调，逆光"。

curl 请求示例

以下是一个完整的 curl 请求，注意替换 YOUR_API_KEY：

curl -sS -X POST \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "一只赛博朋克猫在雨夜的霓虹街头，低角度，电影感，Wong Kar-Wai 风格",
    "size": "1024x1024"
  }' \
  "https://v1.apizero.cn/api/doubao-image"

如果使用 Python 的 requests 库：

import requests

api_key = "YOUR_API_KEY"
url = "https://v1.apizero.cn/api/doubao-image"
payload = {
    "prompt": "一只赛博朋克猫在雨夜的霓虹街头，低角度，电影感，Wong Kar-Wai 风格",
    "size": "1024x1024"
}
headers = {
    "X-API-Key": api_key,
    "Content-Type": "application/json"
}

resp = requests.post(url, json=payload, headers=headers)
print(resp.json())

响应结构解读

成功时 HTTP 状态码为 200，返回 JSON 结构如下：

{
  "code": 0,
  "msg": "成功",
  "request_id": "mqx8x12345abc",
  "data": {
    "created": 1777940499,
    "expires_in": 86400,
    "prompt": "一只赛博朋克猫在雨夜的霓虹街头，低角度，电影感，Wong Kar-Wai 风格",
    "size": "1024x1024",
    "tokens": 4096,
    "url": "https://ark-content-generation-v2-cn-beijing.tos-cn-beijing.volces.com/doubao-seedream-3-0-t2i/021777940499xxx_0.jpeg?X-Tos-Algorithm=TOS4-HMAC-SHA256&X-Tos-Expires=86400&X-Tos-Signature=..."
  }
}

字段说明

字段	类型	说明
code	integer	业务状态码，0 表示成功，非 0 表示错误。
msg	string	状态描述，成功时为“成功”。
request_id	string	本次请求的唯一标识符，用于排查问题。
data.created	integer	图片创建时间的 Unix 时间戳（秒）。
data.expires_in	integer	URL 有效时长（秒），固定为 86400（24 小时）。
data.prompt	string	实际使用的提示词（与请求一致）。
data.size	string	实际生成的图片尺寸。
data.tokens	integer	本次请求消耗的 tokens 数（与图片尺寸有关）。
data.url	string	图片临时直链，24 小时内有效。

tokens 消耗参考

• 方形 1024×1024：约 4096 tokens
• 宽屏 1792×1024 / 1920x1080：约 7168 tokens
• 竖屏 1024×1792 / 720x1280：约 7168 tokens（具体以文档为准）

常见错误处理

错误现象	可能原因	解决方案
HTTP 401	API Key 无效或缺失	检查请求头 X-API-Key 是否正确，重新生成 Key。
HTTP 429	请求频率超过 QPS 2/s	加入本地速率限制或退避重试。
HTTP 400	请求体参数错误（如 prompt 为空、size 非法）	校验 prompt 长度在 50~300 之间，size 为可选值之一。
HTTP 500	服务端临时异常	等待后重试，建议指数退避（最多 3 次）。
图片 URL 返回 404	超过 24 小时有效期	重新生成图片，并在本地保存文件。

工程化注意事项

1. 图片 URL 有效期管理

返回的 url 是字节云 TOS 临时直链，24 小时后永久失效。生产环境中建议：

• 异步下载图片到本地服务器或对象存储（如阿里云 OSS、腾讯云 COS）。
• 在数据库中记录图片的本地存储路径或新的永久 URL。
• 不要在页面中直接引用此直链超过 24 小时。

2. 速率控制

API 的 QPS 限制为 2 次/秒。如果并发请求超过此限制，会返回 429。推荐实现：

• 使用信号量或令牌桶算法控制请求速率。
• 遇到 429 后等待至少 500ms 再重试。
• 如果批量生成，建议使用队列串行调用。

3. 提示词优化

• 生成插画时，可加入风格词如“水彩”、“油画”、“漫画”、“电影感”等。
• 中文提示词效果已经很好，不必强行翻译为英文。
• 如果生成结果不理想，调整词语顺序或增加细节描述。

4. 错误重试策略

对于 5xx 错误，建议采用指数退避：

• 第一次重试等待 1 秒
• 第二次重试等待 2 秒
• 第三次重试等待 4 秒
• 最多重试 3 次

对于 4xx 错误（如 400、401、429），不要盲目重试，应先检查参数或速率。

5. 安全考虑

• 不要把 API Key 硬编码在客户端代码中，应通过后端服务代理。
• 请求和响应中不要包含敏感数据。
• 生成的内容遵守平台合规要求。

参考文档

• 豆包图片生成 API 官方文档
• 原始 Markdown 版本

---

本文档仅作为技术参考，实际请求以接口最新文档为准。