本页目录
Seedance 2.0 API
通过一套异步 API 创建 Seedance 2.0 文生视频和图生视频任务。首个公开版本暂不开放参考视频生成或视频编辑。
REST API · v1 · 异步任务
完成第一次调用
选择文生视频或图生视频，使用唯一 Idempotency-Key，然后轮询返回的 task ID。
- 1
创建 API Key
在 imya 账户设置中生成一枚密钥。
- 2
选择模式
仅使用 text-to-video 或 image-to-video。
- 3
获取结果
轮询 task ID，直到任务成功或失败。
身份验证与幂等
API Key 通过 Bearer Token 发送。每个生成 POST 还必须带唯一 Idempotency-Key，安全重试不会重复创建任务或扣费。
Authorization: Bearer YOUR_IMYA_API_KEY
Content-Type: application/json
Idempotency-Key: YOUR_UNIQUE_REQUEST_KEY创建视频生成任务
创建异步 Seedance 任务，并返回服务端根据本次请求实时计算的 credits_reserved。
/v1/videos/generations# Text to video
curl https://imya.ai/v1/videos/generations \
-H "Authorization: Bearer YOUR_IMYA_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: seedance-t2v-order-001" \
-d '{
"model": "seedance-2.0",
"mode": "text-to-video",
"prompt": "A coastal train passing cliffs at sunrise",
"duration": 5,
"resolution": "720p",
"aspect_ratio": "16:9",
"generate_audio": true
}'
# Image to video
curl https://imya.ai/v1/videos/generations \
-H "Authorization: Bearer YOUR_IMYA_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: seedance-i2v-order-001" \
-d '{
"model": "seedance-2.0",
"mode": "image-to-video",
"prompt": "Wind moves the fabric as the camera arcs right",
"image_url": "https://cdn.example.com/first-frame.jpg",
"duration": 8,
"resolution": "1080p",
"aspect_ratio": "16:9",
"generate_audio": true
}'查询任务
返回最新任务状态、最终积分、生成的 MP4 或净化后的错误。建议轮询间隔至少 5 秒；更频繁的请求仍占用速率额度，但不会刷新上游状态。视频结果链接可能是临时的，请及时下载；API 不保证视频保留 7/30 天。
/v1/tasks/{id}curl https://imya.ai/v1/tasks/task_0123456789abcdef0123456789abcdef \
-H "Authorization: Bearer YOUR_IMYA_API_KEY"请求参数
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| model | string | 是 | 使用 seedance-2.0。 |
| mode | string | 是 | text-to-video 或 image-to-video。 |
| prompt | string | 是 | 生成说明，长度为 3 到 5,000 个字符。 |
| image_url | string | 条件必填 | 公开 HTTPS 首帧，仅图生视频必填。 |
| last_frame_url | string | 否 | 图生视频可选公开 HTTPS 尾帧。 |
| duration | number | 否 | 4 到 15 秒整数，默认 5 秒。 |
| resolution | string | 否 | 480p、720p 或 1080p，默认 720p。 |
| aspect_ratio | string | 否 | 可选 auto、16:9、9:16、1:1、4:3、3:4、3:2、2:3 或 21:9，默认为 16:9。 |
| generate_audio | boolean | 否 | 是否生成音频，默认 true。 |
| web_search | boolean | 否 | 仅文生视频可用，默认 false。 |
返回结构
{
"id": "task_0123456789abcdef0123456789abcdef",
"status": "processing",
"model": "seedance-2.0",
"created_at": "2026-07-15T08:00:00.000Z",
"updated_at": "2026-07-15T08:00:00.000Z",
"credits_reserved": 625
}{
"id": "task_0123456789abcdef0123456789abcdef",
"status": "succeeded",
"model": "seedance-2.0",
"created_at": "2026-07-15T08:00:00.000Z",
"updated_at": "2026-07-15T08:03:12.000Z",
"credits_reserved": 625,
"credits_used": 625,
"data": [
{
"url": "https://media.example.com/generated/example.mp4"
}
]
}实时积分计费
服务端会根据模式、分辨率、时长和 API Key 所属用户的当前套餐计算 credits_reserved。当前 Imya 积分计算不会因音频或网络搜索开关改变。返回示例中的数字只用于展示结构；客户端必须使用本次响应返回的值，不要缓存或自行写死 Seedance 价格。
任务状态
pending任务已接收，正在等待处理。
processing模型正在生成视频。
succeeded生成完成，data 中包含 MP4。
failed生成失败，请读取净化后的 error 对象。
错误码
400缺少 Idempotency-Key 或 JSON 格式错误。
401API Key 缺失或无效。
402账户积分不足。
403API 账户已停用。
404任务不存在，或不属于当前账户。
409同一幂等键被用于不同请求体。
413请求体超过 64 KiB。
415Content-Type 必须是 application/json。
422模式、提示词、图片、时长、分辨率或比例无效。
429达到速率或并发任务上限。
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，而不是没有数据的成功状态。
Seedance 2.0 API 生产环境接入指南
稳定的 Seedance 2.0 接入应当被当作一个小型异步任务系统，而不是一次长时间 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同一账户最多同时运行 3 个视频任务；每个 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，不要暴露提示词、私密媒体地址或凭据。
不要假设视频有固定的保留时间。任务成功后，如果产品需要保留结果，应在得到用户同意并符合隐私政策的前提下，复制到自己控制的存储中，并把媒体地址失效当作正常生命周期事件处理。
生产上线清单
- 提交前校验模型专用字段。
- 每个预期任务保存一个幂等 Key 和请求体。
- 持久化任务状态，并以不短于 5 秒的间隔轮询。
- 实施账户并发与 API Key 速率限制。
- 明确处理四种公开 status；status 为 failed 时检查 error.code 中的 media_deleted 或 refund_pending，并用 credits_refunded 确认退款完成。
- 密钥仅留在服务端，并定义结果保留政策。
常见问题
工作器应多久轮询一次？
间隔不得短于 5 秒。任务仍在处理时，可以使用更慢的退避轮询。
什么时候扣积分？
新任务被接受时，credits_reserved 的准确积分会被原子扣除。
重试会重复扣费吗？
相同 Idempotency-Key 和完全相同的请求体重放时不会，系统会返回原任务。
任务最终失败后怎么做？
向用户显示清晰的产品错误，保留 id 用于支持，并让服务端完成符合条件的一次性退款。通过 credits_refunded 确认结果，不要等待一个不存在的 refunded 状态。
接入前想先测试 Seedance？
打开 Seedance 2.0 在线工具，比较文生视频和图生视频。
在线试用 Seedance 2.0