Seedream
Endpoint: POST https://tokenhub-intl.tencentcloudmaas.com/v1/wand/si-image/generation认证: Tokenhub API Key / Bearer
Seedream 是图片生成模型,支持文生图和参考图编辑。5.0 Pro 支持图层分解,5.0 Lite 支持组图生成。
基本信息
| 项目 | 值 |
|---|---|
| 调用路径 | Tokenhub API |
| 支持解除护栏 | 不支持 |
各版本支持规格
| 版本 | 分辨率 | 比例 | 参考图 |
|---|---|---|---|
seedream-image-v5.0-pro | 1K / 1.5K / 2K | 提示词 / 指定 size | 最多 10 张 |
seedream-image-v5.0-lite | 2K / 3K / 4K | 提示词 / 指定 size | 最多 14 张 |
图片生成
API 说明
Seedream 图片生成(基于参考图的图片生成)API 支持基于参考图的图片生成、文生图和图片编辑。使用参考图和文本提示词生成图片;若未提供图片,则执行文生图。
API: POST https://tokenhub-intl.tencentcloudmaas.com/v1/wand/si-image/generation
请求参数
| 参数 | 必填 | 类型 | 说明 |
|---|---|---|---|
| model | 必填 | string | 模型 ID。取值:seedream-image-v5.0-pro, seedream-image-v5.0-lite |
| prompt | 必填 | string | 文本提示词,最大长度为 600 个字符。若未传入 images,则基于该文本执行文生图。提示词推荐长度:中文提示词建议不超过 300 个字符,英文提示词建议不超过 600 个单词。过长会导致信息分散,模型可能遗漏细节而只关注核心内容,生成的图片中可能缺失部分元素。 |
| images | 选填 | array[string] | 参考图:seedream-image-v5.0-pro 最多支持 10 个 张图片,seedream-image-v5.0-lite 最多支持 14 个 张图片。输入图片信息支持 URL 或 Base64 编码。 图片 URL:图片 URL 必须可访问。 Base64 编码:使用 data:image/<image_format>;base64,<Base64_encoded_string> 格式。<image_format> 必须为小写。 例如:data:image/png;base64,<base64_image>。 |
| layer_decomposition | 选填 | boolean | 控制是否启用图层分解功能的开关。图层分解会把单张图片中的参考对象、背景、文本及其他内容,自动分解为与底图 1 个 相互独立、可单独编辑的最多 16 个图层。每个图层都是带 Alpha 通道的 PNG 图片。支持的模型:seedream-image-v5.0-pro |
| size | 选填 | string | 图片尺寸。seedream-image-v5.0-pro(图片生成场景)支持以下两种方式,二者不能同时使用。方式 1(推荐):指定分辨率档位,并在提示词中用自然语言描述图片的宽高比、形态或用途。随后由模型决定生成图片的尺寸。 默认值: 2K 有效值:1K、1.5K、2K 方式 2:以像素为单位指定宽度和高度(width x height)。总像素值范围:[1280x720( 921600),2048x2048x1.1025(4624220)] 宽高比取值范围:[1/16,16]seedream-image-v5.0-pro(图层分解场景)仅支持指定分辨率档位的方式。输出图片的分辨率规则如下。 底图:输出底图的分辨率与 size 指定的分辨率一致。 输出底图的宽高比与待分割原图的宽高比一致。 图层:每个输出图层的分辨率接近 size 指定的分辨率。 每个输出图层的宽高比与该图层在原图中的宽高比一致。size 的默认值及可选值:默认值:auto 有效值: 1K、1.5K、2K、auto(按输入图片的尺寸和宽高比输出)seedream-image-v5.0-lite 支持以下两种方式,二者不能同时使用。方式 1:指定分辨率,并在提示词中用自然语言描述图片的宽高比、形态或用途。随后由模型决定生成图片的尺寸。 有效值: 2K、3K、4K 方式 2:以像素为单位指定生成图片的宽度和高度。默认值: 2048x2048 总像素值范围:[2560x1440(3686400),4096x4096(16777216)] 宽高比取值范围:[1/16,16] |
| optimize_prompt_options | 选填 | object | 提示词优化配置。 |
| optimize_prompt_options.mode | 选填 | string | 优化模式。standard:标准模式。生成质量更高的内容,但耗时更长。fast:高速模式。生成内容更快,但质量略低于 standard 模式。seedream-image-v5.0-lite 目前不支持该模式。 |
| output_format | 选填 | string | 图片格式。指定生成图片的文件格式。可选值:png jpeg |
| background | 选填 | string | 图片 Alpha 通道。控制是否生成带 Alpha 通道的图片。可选值:transparent:透明背景模式。输出透明背景的图片。opaque:不透明背景模式。生成普通纯色背景图片。支持的模型:seedream-image-v5.0-pro |
| response_format | 选填 | string | 响应格式。指定生成图片的返回形式。支持以下两种返回方式。url:返回图片下载链接。链接在图片生成后 24 小时 内有效。请立即下载图片。b64_json:以 JSON 字符串形式返回经 Base64 编码的图片数据。 |
| sequential_image_generation | 选填 | string | 组图模式。 控制是否禁用组图功能(根据输入生成的一组相互关联的图片)。auto:自动模式。 由模型根据用户提供的提示词决定是否返回图片组以及组内图片数量。disabled:禁用组图功能。 模型仅生成 1 个 张图片。支持的模型: seedream-image-v5.0-lite |
| sequential_image_generation_options | 选填 | object | 组图配置。组图功能的配置,仅当 sequential_image_generation 设为 auto 时生效。支持的模型:seedream-image-v5.0-lite |
| sequential_image_generation_options.max_images | 选填 | integer | 最大生成图片数。指定本次请求可生成的最大图片数量。取值范围:[1, 15]。 |
| tools | 选填 | object | 工具配置。支持的模型:seedream-image-v5.0-lite |
| tools.type | 选填 | string | 工具类型。指定要使用的工具类型。web_search:联网搜索功能。 |
| watermark | 选填 | boolean | 水印开关。指定是否在生成图片上添加水印。false:不添加水印。true:在图片右下角添加 "AI-generated" 水印。 |
请求示例
基于参考图的图片生成
curl -X POST 'https://tokenhub-intl.tencentcloudmaas.com/v1/wand/si-image/generation' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"model": "seedream-image-v5.0-pro",
"images": [
"https://mpstestmodel-1315536146.cos.ap-singapore.myqcloud.com/justin/wiki-examples/reference-cup.png"
],
"prompt": "a cat sitting on a windowsill at sunset",
"size": "2048x2048"
}'文生图(不使用 images)
curl -X POST 'https://tokenhub-intl.tencentcloudmaas.com/v1/wand/si-image/generation' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"model": "seedream-image-v5.0-pro",
"prompt": "a cat sitting on a windowsill at sunset",
"size": "2048x2048"
}'响应参数
| 字段 | 类型 | 说明 |
|---|---|---|
| created_at | string | 任务创建时间。 |
| data | object | 返回的图片内容。 |
| data[].output_format | string | 输出格式。 |
| data[].size | string | 图片尺寸。 |
| data[].url | string | 图片 URL。 |
| data[].b64_json | string | 图片 Base64 数据。 |
| request_id | string | 用于排查问题的唯一请求标识符。 |
| model | string | 所使用的图片生成模型。 |
| tokenhub_usage | object | 用量。 |
| tokenhub_usage.total_tokens | integer | 本次任务消耗的 token 数,用于计费/结算。 |
响应示例
{
"created": 1787309367,
"data": [
{
"output_format": "jpeg",
"size": "2048x2048",
"url": "https://xxxxxxx.jpg"
}
],
"model": "doubao-seedream-5-0-pro-260628",
"tokenhub_usage": {
"total_tokens": 60000
},
"request_id": "f781d9dc-9792-43d8-82f3-90de51a1ff44"
}附录
统一错误码
| 错误码 | 错误信息 | 说明 |
|---|---|---|
| BadRequest | 请求有误 | 无效请求。 |
| FieldLacking | 字段缺失或为空 | 缺少必填字段。 |
| FieldUnwanted | 多余的字段 | 传入了多余的字段。 |
| FieldInvalid | 无效字段 | 输入参数未通过校验。 |
| FieldItemCountOutOfRange | 字段项数超出范围 | 字段项数超过限制(例如图片数量超过限制)。 |
| PageSizeOutOfRange | 页面大小超出范围 | 图片尺寸/参数超过限制。 |
| ImageFormatInvalid | 无效的图片格式 | 图片格式不满足要求。 |
| ImageSizeInvalid | 无效的图片尺寸 | 图片尺寸过大或过小。 |
| ImageDownloadFailure | 图片下载失败 | 未能从 URL 下载图片。请确认链接。 |
| TaskPromptPolicyViolation | 提示词违反策略 | 提示词触发了安全审核和风险控制。 |
| CreationPolicyViolation | 生成内容违反策略 | 生成的内容触发了风险控制。 |
| AuditSubmitIllegal | 提交无效 | 输入未通过安全审核。 |
| CreditInsufficient | 额度不足 | 额度不足。 |
| ModelUnavailable | 模型不可用 | 模型无法使用。 |
| Unauthorized | 未认证 | 未通过认证(请确认 Authorization)。 |
| Forbidden | 被禁止 | 请求没有权限。 |
| TaskNotFound | 未找到任务 | 未找到 task_id。 |
| QuotaExceeded | 配额超限 | 超过并发执行限制。 |
| TooManyRequests | 请求过多 | 请求频率过高。 |
| InternalServiceFailure | 内部服务故障 | 内部服务器错误。 |
图片资源的通用限制
参考图:seedream-image-v5.0-pro 最多支持 10 个 张图片,seedream-image-v5.0-lite 最多支持 14 个 张图片。支持图片 URL 或 Base64 字符串(Base64 字符串必须包含 data:image/png;base64, 前缀)。支持的格式包括 jpeg/png/webp/bmp/tiff/gif/heic/heif。最小像素尺寸为 14 x 14,总像素数不能超过 36 million,宽高比必须小于 1:16 或大于 16:1。每张图片不能超过 30 MB,POST 正文不能超过 20 MB。
FAQ
1. 区分文生图和图生图的方法是什么?
同一个 API 同时支持两种模式。传入 image 时,会基于图片中的参考对象启用基于参考图的图片生成;省略 images 时,则仅凭提示词执行文生图。seedream-image-v5.0-pro 同时支持这两种模式。
2. 生成的图片链接有过期时间吗?
生成结果是 12 小时 后过期的临时地址。任务成功后请立即下载。