适用场景与能力边界豆包图片生成 API 基于字节跳动豆包 Seedream 3.0 大模型提供高质量文生图服务。其核心能力包括影视级画质擅长摄影、插画、电影感构图对中文场景理解精准。多种尺寸支持 6 种主流分辨率覆盖方形、宽屏、竖屏等常见比例。中文友好原生理解中文语意无需翻译为英文即可生成符合描述的图片。适用场景内容创作博客插图、海报、Banner、社交媒体配图。营销素材广告图、商品概念图、宣传背景。设计辅助灵感参考、构图草稿、风格化展示。应用集成聊天机器人自动配图、自媒体工具、AI 应用后台。能力边界平均出图时间 3~4 秒但受网络和模型负载影响可能波动。QPS 限制为 2 次/秒超过后返回 429 状态码。生成的图片 URL 为字节云 TOS 临时直链有效期为 24 小时由expires_in字段指定单位秒。提示词建议长度50~300 字符越具体效果越好。鉴权与请求方式调用该 API 需要携带 API Key 进行鉴权。请求方式为 HTTP POSTContent-Type 推荐使用application/json。Header 参数参数名必填类型说明Authorization是stringAPI Key需在控制台申请。实际传参时使用X-API-Key头值为 API Key。Content-Type否string建议设为application/json。也可通过form-urlencoded或 query string 传参但不推荐。请求地址POST https://v1.apizero.cn/api/doubao-image请求参数详解请求体为 JSON 对象包含以下字段字段名类型必填描述示例值promptstring是图片描述文本支持中英文混合。建议 50~300 字符越具体越好。一只赛博朋克猫在雨夜的霓虹街头低角度电影感Wong Kar-Wai 风格sizestring否图片尺寸默认1024x1024。可选值见下表。1792x1024size 可选值尺寸比例典型用途1024x10241:1方形适配大多数平台默认值1792x102416:9宽屏适合横幅、视频封面1024x17929:16竖屏适合手机壁纸、Story1280x72016:9720p 分辨率节省 tokens720x12809:16竖屏 720p1920x108016:9全高清细节更丰富不同尺寸消耗的 tokens 不同方型约 4096 tokens宽屏 1792x1024 或 1080p 约 7168 tokens具体以实际响应中的tokens字段为准。请求示例curl以下示例使用 curl 发起请求。请将$APIZERO_API_KEY替换为你在控制台获取的 API Key。基本请求方形图片curl -sS \ -X POST \ -H X-API-Key: $APIZERO_API_KEY \ -H Content-Type: application/json \ -d { prompt: 一只赛博朋克猫在雨夜的霓虹街头低角度电影感Wong Kar-Wai 风格, size: 1024x1024 } \ https://v1.apizero.cn/api/doubao-image宽屏 16:9 示例curl -sS \ -X POST \ -H X-API-Key: $APIZERO_API_KEY \ -H Content-Type: application/json \ -d { prompt: 清晨阳光洒在雪山湖泊上雾气缭绕4K摄影超写实, size: 1792x1024 } \ https://v1.apizero.cn/api/doubao-image使用环境变量管理 API Key建议将 API Key 存入环境变量避免硬编码export APIZERO_API_KEYyour_key_here curl -sS -X POST -H X-API-Key: $APIZERO_API_KEY -H Content-Type: application/json -d {prompt:...,size:...} https://v1.apizero.cn/api/doubao-image返回字段解读成功响应HTTP 200的 JSON 结构如下{ code: 0, 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-AlgorithmTOS4-HMAC-SHA256X-Tos-Expires86400X-Tos-Signature... }, msg: 成功, request_id: mqx8x12345abc }各字段含义字段类型说明codeint状态码0 表示成功。非 0 表示失败。data.createdint图片生成时间的 Unix 时间戳秒。data.expires_inintURL 有效时长固定 86400 秒24 小时。data.promptstring回显传入的提示词。data.sizestring回显请求的尺寸。data.tokensint本次请求消耗的 tokens 数可用于计费参考。data.urlstring生成的图片直链仅 24 小时内可访问。msgstring状态描述成功时为“成功”。request_idstring请求唯一标识便于排查问题。重要data.url是临时直链过期后返回 403。务必在有效期内下载到本地或转存到自己的对象存储如阿里 OSS、腾讯 COS。错误处理常见错误码HTTP 状态码codemsg 示例原因与解决40110001认证失败API Key 无效或未携带。检查X-API-Key头是否正确。40010002参数错误请求体 JSON 格式错误或缺少必填字段。检查prompt是否存在size 是否为有效值。42910005请求过于频繁QPS 超过 2 次/秒。降低调用频率或加入请求队列。50020000服务器内部错误服务暂时异常。可等待后重试若持续出现请联系技术支持。错误响应示例{ code: 10002, msg: 参数错误, request_id: abc123 }排查建议使用-v参数运行 curl 查看完整请求与响应头。确认 API Key 未包含多余的空格或换行。对prompt进行 JSON 转义避免特殊字符破坏格式。工程化注意事项1. 图片 URL 生命周期管理expires_in为 86400 秒24 小时。生产环境建议异步下载图片到本地服务器或直接转存到对象存储。在数据库中记录图片的原始 URL、过期时间以及本地存储路径。不要在前端直接暴露临时直链供长时间使用否则 24 小时后会断图。2. 调用频率控制QPS 为 2超出返回 429。解决方案使用令牌桶或信号量限制客户端请求速率。对突发请求采用队列缓冲批量处理。在代码中加入指数退避重试策略。3. 提示词优化策略推荐结构主体 风格 构图 光线 氛围。例如“一只赛博朋克猫在雨夜的霓虹街头低角度电影感Wong Kar-Wai 风格”。可指定材质、镜头、色调、画家风格如“仿宫崎骏风格”、“胶片质感”。长度控制在 50~300 字符过长可能截断或产生无关细节。避免中英文混杂过度优先使用中文。4. 计费理解tokens字段反映每次请求消耗的资源不同尺寸 tokens 不同。方型 1024x1024 约 4096 tokens宽屏 1792x1024 约 7168 tokens。实际扣费以平台用量说明为准。建议在开发阶段使用较小尺寸以节省资源。5. 安全性API Key 置于环境变量或密钥管理服务禁止硬编码在前端或公开仓库。服务端做代理转发避免前端直接请求 API暴露 Key。对用户输入的prompt做长度和内容过滤防止恶意超长文本。参考文档豆包图片生成 API 文档原始文档raw