异步任务

Seedance 2.0 的所有视频生成请求都是异步的。提交后 API 立即返回一个任务 ID，实际的视频生成在后台完成。你可以：

轮询：定期调用本页接口查询进度
Webhook：在提交任务时携带 callback_url，系统主动推送结果。详见 Webhooks

查询任务状态

GET https://api.evolink.ai/v1/tasks/{task_id}

路径参数

参数	类型	必填	说明
`task_id`	string	是	生成接口返回的任务 ID

cURL 示例

curl https://api.evolink.ai/v1/tasks/task-unified-1774857405-abc123 \
  -H "Authorization: Bearer YOUR_API_KEY"

任务生命周期

pending  →  processing  →  completed
                      ↘    failed
                      ↘    cancelled

状态	含义
`pending`	任务已创建，正在排队等待处理
`processing`	正在生成中，`progress` 会持续更新
`completed`	生成完成，`results` 数组中包含视频 URL
`failed`	生成失败，不扣费
`cancelled`	任务被主动取消

响应示例

Pending（刚提交）

{
    "id": "task-unified-1774857405-abc123",
    "object": "video.generation.task",
    "created": 1774857405,
    "model": "seedance-2.0-text-to-video",
    "status": "pending",
    "progress": 0,
    "type": "video",
    "task_info": {
        "can_cancel": true,
        "estimated_time": 165,
        "video_duration": 5
    },
    "usage": {
        "billing_rule": "per_second",
        "credits_reserved": 50,
        "user_group": "default"
    }
}

Processing（生成中）

{
    "id": "task-unified-1774857405-abc123",
    "object": "video.generation.task",
    "created": 1774857405,
    "model": "seedance-2.0-text-to-video",
    "status": "processing",
    "progress": 65,
    "type": "video",
    "task_info": {
        "can_cancel": true
    }
}

Completed（已完成）

{
    "id": "task-unified-1774857405-abc123",
    "object": "video.generation.task",
    "created": 1774857405,
    "model": "seedance-2.0-text-to-video",
    "status": "completed",
    "progress": 100,
    "results": [
        "https://cdn.example.com/videos/task-unified-1774857405-abc123.mp4"
    ],
    "type": "video",
    "task_info": {
        "can_cancel": false
    }
}

视频 URL 有效期 24 小时。 请务必在到期前下载并转存到你自己的存储（OSS / S3 / R2 等）。

Failed（失败）

{
    "id": "task-unified-1774857405-abc123",
    "object": "video.generation.task",
    "created": 1774857405,
    "model": "seedance-2.0-text-to-video",
    "status": "failed",
    "progress": 0,
    "type": "video",
    "task_info": {
        "can_cancel": false
    }
}

失败的任务 不会扣费。

响应字段

字段	类型	说明
`id`	string	任务 ID
`object`	string	固定为 `video.generation.task`
`created`	integer	任务创建的 Unix 时间戳
`model`	string	实际使用的 model ID（与提交时一致）
`status`	string	当前状态，见生命周期表
`progress`	integer	0–100 百分比
`results`	array<string>	仅 `completed` 状态下存在，包含视频 URL
`type`	string	输出类型，固定为 `video`
`task_info.can_cancel`	boolean	当前是否允许取消
`task_info.estimated_time`	integer	预计还需多少秒
`task_info.video_duration`	integer	请求的视频时长（秒）
`usage.billing_rule`	string	固定为 `per_second`
`usage.credits_reserved`	number	预扣积分
`usage.user_group`	string	用户组

轮询最佳实践

间隔 5 秒 是轮询频率与响应延迟的较好平衡
短视频（4–6 秒）的总生成时间通常在 1–3 分钟内，长视频或复杂多模态任务可能更久
生产环境推荐使用 Webhooks 替代轮询。callback_url 可将请求数降到最低，也更省成本
不要把 progress 当作精确的剩余时间预估 —— 它只是一个进度指示，模型在不同阶段进展速度不同

Python 完整示例

import os
import time
import requests

API_KEY = os.environ["EVOLINK_API_KEY"]
headers = {"Authorization": f"Bearer {API_KEY}"}

# 提交任务
response = requests.post(
    "https://api.evolink.ai/v1/videos/generations",
    headers={**headers, "Content-Type": "application/json"},
    json={
        "model": "seedance-2.0-text-to-video",
        "prompt": "雨后的东京街头，霓虹灯倒映在湿漉漉的路面上",
        "duration": 6,
        "quality": "720p"
    }
)
task_id = response.json()["id"]

# 轮询状态
while True:
    result = requests.get(
        f"https://api.evolink.ai/v1/tasks/{task_id}",
        headers=headers
    ).json()

    status = result["status"]
    print(f"[{status}] progress={result.get('progress', 0)}%")

    if status == "completed":
        print(f"Video URL: {result['results'][0]}")
        break
    if status in ("failed", "cancelled"):
        print(f"Task ended with status: {status}")
        break

    time.sleep(5)