本页目录
Seedream 5.0 Pro API
通过 Seedream 5.0 Pro API，使用提示词或最多 10 张公开 HTTPS 参考图生成一张图片。Imya 统一处理 API Key 鉴权、异步任务、实时积分、错误净化和结果存储。
REST API · v1 · 异步任务
适用场景
用一套 REST 流程完成提示词生图、参考图驱动的创意变体和自动化图像工作流。
产品与广告素材
使用提示词生成产品场景、广告创意和品牌视觉。
参考图驱动的创意变体
使用 1-10 张参考图引导主体、构图或视觉方向。
自动化图像工作流
异步提交任务、查询公开 task ID，并获取 Imya 存储的成品图片。
完成第一次 Seedream 5.0 Pro 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/{task_id}curl https://imya.ai/v1/tasks/task_0123456789abcdef0123456789abcdef \
-H "Authorization: Bearer YOUR_IMYA_API_KEY"请求参数
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| model | string | 是 | 使用 seedream-5-pro。 |
| prompt | string | 是 | 生成说明，3 至 5,000 个字符。 |
| image_urls | string[] | 否 | 1-10 张公开 HTTPS 参考图；文生图时不传。 |
| aspect_ratio | string | 否 | 1:1、4:3、3:4、16:9、9:16、2:3、3:2 或 21:9，默认 1:1。 |
| quality | string | 否 | basic 或 high，默认 basic。 |
| output_format | string | 否 | png 或 jpeg，默认 png。 |
| n | number | 否 | 必须为 1，每次只生成一张图片。 |
返回结构
{
"id": "task_0123456789abcdef0123456789abcdef",
"status": "pending",
"model": "seedream-5-pro",
"credits_reserved": 44
}{
"id": "task_0123456789abcdef0123456789abcdef",
"status": "succeeded",
"model": "seedream-5-pro",
"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 账户已停用或请求不允许。
409同一幂等键被用于不同请求体。
413请求体超过 64 KiB。
422模型参数、提示词或参考图无效。
429API Key 达到速率或并发上限。
5xx请求无法完成。创建新请求前请先查询原任务。
准备开始接入？
创建 Imya API Key 完成第一次调用，或在接入前先用在线生成器测试提示词、参考图和质量设置。