本页目录
Seedream API：Seedream 5.0 Pro
通过 Seedream API 调用 Seedream 5.0 Pro，使用提示词或最多 10 张公开 HTTPS 参考图生成一张图片。Imya 统一处理 API Key 鉴权、异步任务、实时积分、错误净化和结果存储。
REST API · v1 · 异步任务
适用场景
用一套 REST 流程完成提示词生图、参考图驱动的创意变体和自动化图像工作流。
产品与广告素材
使用提示词生成产品场景、广告创意和品牌视觉。
参考图驱动的创意变体
使用 1-10 张参考图引导主体、构图或视觉方向。
自动化图像工作流
异步提交任务、查询公开 task ID，并获取 Imya 存储的成品图片。
完成第一次 Seedream API 调用
创建任务并保存公开 task ID，然后查询任务，直到成功或失败。
- 1
创建 API Key
在 Imya 账户设置中生成一枚密钥。
- 2
选择输入方式
仅提交提示词，或再添加 1-10 张参考图。
- 3
获取结果
使用公开 task ID 查询，最快每 5 秒一次。
身份验证与幂等
通过 Bearer Token 发送 Imya API Key。每个生成 POST 还必须携带唯一 Idempotency-Key，网络重试不会重复创建任务或扣费。
Authorization: Bearer YOUR_IMYA_API_KEY
Content-Type: application/json
Idempotency-Key: YOUR_UNIQUE_REQUEST_KEY创建图片生成任务
不传 image_urls 即为文生图；传入 1-10 张公开 HTTPS 图片即为参考图生成。服务端会返回本次实时 credits_reserved。
/v1/images/generationscurl https://imya.ai/v1/images/generations \
-H "Authorization: Bearer YOUR_IMYA_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: seedream-product-shot-001" \
-d '{
"model": "seedream-5-pro",
"prompt": "A premium skincare bottle on pale stone, soft morning light",
"aspect_ratio": "4:3",
"quality": "basic",
"output_format": "png",
"n": 1
}'curl https://imya.ai/v1/images/generations \
-H "Authorization: Bearer YOUR_IMYA_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: seedream-edit-001" \
-d '{
"model": "seedream-5-pro",
"prompt": "Keep the product shape and place it in a warm studio",
"image_urls": ["https://cdn.example.com/input/product.png"],
"aspect_ratio": "4:3",
"quality": "high",
"output_format": "jpeg",
"n": 1
}'查询任务
返回最新任务状态、最终积分、已存储图片或净化后的错误。建议查询间隔至少 5 秒；更频繁的请求仍占用速率额度，但不会刷新上游状态。
/v1/tasks/{id}curl https://imya.ai/v1/tasks/task_0123456789abcdef0123456789abcdef \
-H "Authorization: Bearer YOUR_IMYA_API_KEY"请求参数
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| model | string | 是 | 使用 seedream-5-pro。 |
| prompt | string | 是 | 生成说明，3 至 3,000 个字符。 |
| image_urls | string[] | 否 | 1-10 张公开 HTTPS 参考图；文生图时不传。 |
| aspect_ratio | string | 否 | 1:1、4:3、3:4、16:9、9:16、2:3 或 3:2，默认 1:1。 |
| quality | string | 否 | basic 或 high，默认 basic；16:9 和 9:16 只支持 basic。 |
| output_format | string | 否 | png 或 jpeg，默认 png。 |
| n | number | 否 | 必须为 1，每次只生成一张图片。 |
返回结构
{
"id": "task_0123456789abcdef0123456789abcdef",
"status": "pending",
"model": "seedream-5-pro",
"created_at": "2026-07-15T08:00:00.000Z",
"updated_at": "2026-07-15T08:00:00.000Z",
"credits_reserved": 44
}{
"id": "task_0123456789abcdef0123456789abcdef",
"status": "succeeded",
"model": "seedream-5-pro",
"created_at": "2026-07-15T08:00:00.000Z",
"updated_at": "2026-07-15T08:00:38.000Z",
"credits_reserved": 44,
"credits_used": 44,
"data": [
{
"url": "https://cdn.imya.ai/generated/example.png"
}
]
}新任务返回 HTTP 202；完全相同的幂等重试返回 HTTP 200，并带 Idempotent-Replayed: true。任务变为 succeeded 前，成功图片会先转存到 Imya 管理的存储。失败任务可能返回 generation_failed、refund_pending 或 media_deleted。
实时积分计费
basic 和 high 的基础价都是 35 积分，服务端再应用 API Key 所属用户的当前套餐系数。示例是普通账户按 1.25 倍计算并取整为 44 积分；客户端必须使用返回的 credits_reserved。如果任务 30 分钟仍未完成，Imya 会将其判定失败，并只退还一次符合条件的积分，不延长积分原到期日。
查看积分套餐任务状态
pending任务已接收，正在等待处理。
processing模型正在生成图片。
succeeded生成完成，data 中包含已存储图片。
failed生成失败，请读取净化后的 error 对象。
错误码
400缺少 Idempotency-Key 或 JSON 格式错误。
401API Key 缺失或无效。
402账户积分不足。
403API 账户已停用或请求不允许。
404任务不存在，或不属于当前账户。
409同一幂等键被用于不同请求体。
413请求体超过 64 KiB。
415Content-Type 必须是 application/json。
422模型参数、提示词或参考图无效。
429API Key 达到速率或并发上限。
5xx请求无法完成。创建新请求前请先查询原任务。
Imya 公共 API 统一规则
以下规则适用于所有公开图片和视频生成接口；模型独有参数和价格仍以本页参数表为准。
扣费与安全重试
新任务被接受时，服务端会原子扣除 credits_reserved 显示的准确积分。使用相同 Idempotency-Key 和相同请求体重试，只会返回原任务，不会再次扣费。
超时与退款
任务在 30 分钟内没有进入最终状态时会失败。符合条件的积分只退一次，而且保留原积分到期日。
速率与并发限制
每个 API Key 每 60 秒最多请求 120 次；同一账户最多同时运行 5 个图片任务或 3 个视频任务。429 返回可能包含 Retry-After；如有该字段请遵守。
轮询与任务归属
使用创建任务时返回的 id 查询 GET /v1/tasks/{id}，建议间隔至少 5 秒。更频繁的请求仍会占用 API Key 速率额度，但不会刷新上游状态。只有创建任务的账户可以读取；当前不提供 webhook、SDK 或批量提交。
错误与内容安全
公开错误会经过净化，不会暴露上游凭据、内部地址或基础设施信息。不安全提示词可能在生成前以 prompt_blocked 拒绝。
图片结果保留
免费账户的图片结果保存 7 天，有效付费或 Lifetime 账户最长保存 30 天。删除后响应的 status 为 failed、error.code 为 media_deleted，而不是没有数据的成功状态。
Seedream API 生产环境接入指南
稳定的 Seedream 5.0 Pro 接入应当被当作一个小型异步任务系统，而不是一次长时间 HTTP 请求。将模型选项放在配置中，保存每个 Imya 任务返回的 id，并让重试结果可预期。以下做法覆盖从本地示例进入生产环境时最重要的环节。
以模型契约选择参数
提交前，请根据本页参数表校验每个请求。开发阶段先使用最小的受支持输入和输出设置，只在产品确实需要时才提高质量、尺寸、时长或参考图数量。对用户提供的提示词和文件，应先在自己的服务端检查长度、文件类型和大小。
参考图流程需保持图片顺序，并确认用户有权使用每张上传图片。
设计可恢复的异步流程
提交图片任务后，将返回的 id 和业务任务一起保存，再由后台工作器查询状态。建议 GET /v1/tasks/{id} 的轮询间隔至少 5 秒；更频繁的请求仍占用 API Key 速率额度，但不会刷新上游状态。公开状态只有 pending、processing、succeeded 和 failed。任务有 30 分钟硬截止时间，因此工作器应在收到终态或到达边界时停止。当前不提供 webhook、SDK 或批量提交，请使用 HTTP 请求和轮询接入。
- 01更新页面前，先持久化 id、status、credits_reserved 和请求标识。
- 02遇到短暂网络错误时退避重试，429 按 Retry-After 执行，不要因传输错误自动创建新的付费任务。
- 03同一账户最多同时运行 5 个图片任务；每个 API Key 每 60 秒最多 120 次请求。
让扣费与重试结果确定
新任务被接受时，credits_reserved 返回的准确积分会被原子扣除。每次有意创建新任务时生成一个 Idempotency-Key，并与请求一起保存。相同 Key 和相同请求体重放时，只会返回原任务，不会再次扣费。如果用户更改了请求，应创建新 Key。
当失败任务符合退款条件时，Imya 只退回一次积分，并保留原积分到期日。公开 status 仍是 failed：结算处理中时 error.code 为 refund_pending，退款完成后响应会出现 credits_refunded。按 id 对账，不要由客户端自行发放积分。
保护密钥、任务归属和生成结果
将 API Key 保留在服务端，绝不要写入浏览器或移动端安装包。将每个返回的 id 与创建它的登录用户或工作区关联，展示结果前验证归属。公开错误已经净化；排查时记录自己的请求 ID 和任务 id，不要暴露提示词、私密媒体地址或凭据。
免费账户的图片结果保存 7 天，有效付费或 Lifetime 账户最长保存 30 天。媒体被删除后，响应的 status 为 failed，error.code 为 media_deleted。如果产品需要更长期保留，应在得到用户同意并符合隐私政策的前提下，复制到自己控制的存储中。
生产上线清单
- 提交前校验模型专用字段。
- 每个预期任务保存一个幂等 Key 和请求体。
- 持久化任务状态，并以不短于 5 秒的间隔轮询。
- 实施账户并发与 API Key 速率限制。
- 明确处理四种公开 status；status 为 failed 时检查 error.code 中的 media_deleted 或 refund_pending，并用 credits_refunded 确认退款完成。
- 密钥仅留在服务端，并定义结果保留政策。
常见问题
工作器应多久轮询一次？
间隔不得短于 5 秒。任务仍在处理时，可以使用更慢的退避轮询。
什么时候扣积分？
新任务被接受时，credits_reserved 的准确积分会被原子扣除。
重试会重复扣费吗？
相同 Idempotency-Key 和完全相同的请求体重放时不会，系统会返回原任务。
任务最终失败后怎么做？
向用户显示清晰的产品错误，保留 id 用于支持，并让服务端完成符合条件的一次性退款。通过 credits_refunded 确认结果，不要等待一个不存在的 refunded 状态。
准备开始接入？
创建 Imya API Key 完成第一次调用，或在接入前先用在线生成器测试提示词、参考图和质量设置。