异步视频任务

创建接口会先返回任务对象，Seedance 在后台生成视频。创建任务使用模型 API Token，查询任务使用资源 API Key；访问结果 URL 时根据 url_auth 决定是否需要资源 API Key。

端点

能力	方法与路径	使用的密钥
创建任务	`POST /v1/video/tasks`	模型 API Token，`sk-...`
创建媒体直传会话	`POST /v1/media/uploads`	资源 API Key，`ak_...`
确认媒体直传结果	`POST /v1/media/uploads/complete`	资源 API Key，`ak_...`
查询任务	`GET /v1/video/tasks/{task_id}`	资源 API Key，`ak_...`
列出任务	`GET /v1/video/tasks`	资源 API Key，`ak_...`
批量查询	`POST /v1/video/tasks/query`	资源 API Key，`ak_...`

bash

export SUPERTOKEN_BASE_URL="https://api.supertoken.cc"
export SUPERTOKEN_KEY="YOUR_MODEL_API_TOKEN"
export RESOURCE_API_KEY="YOUR_RESOURCE_API_KEY"
export VIDEO_MODEL="adobe-seedance-2.0-480p"

不同模型 ID 范围支持的参考模式和素材数量不同。创建任务前请查看参数与错误，可用模型以控制台模型广场或 GET /v1/models 为准。

创建文生视频任务

下面是一个最小文生视频请求。字段取值和限制见参数与错误。

bash

curl -i -sS "$SUPERTOKEN_BASE_URL/v1/video/tasks" \
  -H "Authorization: Bearer $SUPERTOKEN_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: video-order-20260730-001" \
  -d '{
    "model": "'"$VIDEO_MODEL"'",
    "operation": "generation",
    "input": {
      "prompt": "日出时分，一辆银色概念车沿海岸公路行驶，电影感运镜"
    },
    "output": {
      "duration": 4,
      "aspect_ratio": "16:9",
      "generate_audio": true
    },
    "client_reference_id": "order-20260730-001",
    "metadata": {
      "order_id": "order-20260730-001"
    }
  }'

成功创建返回 HTTP 202 Accepted，并带有任务查询位置和建议轮询间隔：

http

Location: /v1/video/tasks/task_example123
Retry-After: 2

json

{
  "id": "task_example123",
  "object": "video.task",
  "model": "adobe-seedance-2.0-480p",
  "operation": "generation",
  "status": "queued",
  "progress": 0,
  "result": null,
  "error": null,
  "client_reference_id": "order-20260730-001",
  "metadata": {
    "order_id": "order-20260730-001"
  },
  "created_at": 1785373200,
  "started_at": null,
  "completed_at": null,
  "updated_at": 1785373200
}

Idempotency-Key 可选，最长 128 个字符。相同用户使用同一个 Key 和相同请求重试时，会返回原任务并带 Idempotent-Replayed: true；同一个 Key 对应不同请求内容会返回 409 Conflict。

上传本地参考素材

POST /v1/video/tasks 只接受 application/json，参考素材只接受绝对 HTTP/HTTPS URL。不要把 Base64、Data URL、multipart 文件或本地路径放入任务 JSON。

本地文件使用三步直传。第一步只发送文件元数据，SuperToken 返回对象存储的短期预签名地址：

bash

curl -sS "$SUPERTOKEN_BASE_URL/v1/media/uploads" \
  -H "Authorization: Bearer $RESOURCE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "files": [
      {
        "client_id": "motion",
        "kind": "video",
        "filename": "motion.mp4",
        "mime_type": "video/mp4",
        "size_bytes": 1048576
      },
      {
        "client_id": "music",
        "kind": "audio",
        "filename": "music.mp3",
        "mime_type": "audio/mpeg",
        "size_bytes": 524288
      }
    ]
  }'

响应中的 data[] 与请求文件顺序一致：

json

{
  "object": "media.upload.session.list",
  "data": [
    {
      "id": "upload_video_example",
      "client_id": "motion",
      "kind": "video",
      "method": "PUT",
      "upload_url": "https://object-storage.example.com/presigned/...",
      "headers": {
        "Content-Type": "video/mp4"
      },
      "expires_at": 1785374100
    }
  ]
}

第二步由客户端直接把文件 PUT 到 upload_url。必须使用响应给出的 method 和全部 headers：

bash

curl -sS "$UPLOAD_URL" \
  -X PUT \
  -H "Content-Type: video/mp4" \
  --data-binary @motion.mp4

文件流量直接进入对象存储，不经过 SuperToken。第三步向 SuperToken 确认上传：

bash

curl -sS "$SUPERTOKEN_BASE_URL/v1/media/uploads/complete" \
  -H "Authorization: Bearer $RESOURCE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "upload_ids": [
      "upload_video_example",
      "upload_audio_example"
    ]
  }'

确认接口会核对对象大小和 MIME，返回可放入 reference_images、reference_videos 或 reference_audios 的临时 HTTPS URL：

json

{
  "object": "media.upload.list",
  "data": [
    {
      "id": "upload_video_example",
      "client_id": "motion",
      "kind": "video",
      "url": "https://media.example.com/media/tmp/uploads/motion.mp4",
      "mime_type": "video/mp4",
      "size_bytes": 1048576,
      "temporary": true,
      "expires_at": 1785460500
    }
  ]
}

预签名地址与返回的素材 URL 都是临时地址，应尽快完成上传和任务创建。创建任务时只传最终确认返回的 url，不要传 upload_url 或上传会话 ID。

使用首帧和尾帧

下面的示例使用 frame 模式，input.image 表示首帧，input.reference_images[0] 表示尾帧。使用前请在模型 ID 范围差异中确认所选模型支持该模式。

bash

curl -sS "$SUPERTOKEN_BASE_URL/v1/video/tasks" \
  -H "Authorization: Bearer $SUPERTOKEN_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: frame-video-20260730-001" \
  -d '{
    "model": "adobe-seedance-2.0-720p",
    "operation": "generation",
    "input": {
      "prompt": "镜头从白天的山谷平滑过渡到星空下的营地，保持地形一致",
      "reference_mode": "frame",
      "image": {
        "url": "https://images.example.com/valley-day.jpg"
      },
      "reference_images": [
        {
          "url": "https://images.example.com/valley-night.jpg"
        }
      ]
    },
    "output": {
      "duration": 6,
      "aspect_ratio": "16:9",
      "generate_audio": false
    }
  }' | jq .

只需要首帧时，保留 input.image 并省略 reference_images。

Seedance 2.5 首尾帧

Seedance 2.5 的 frame 模式同样按顺序使用首帧和尾帧，但模型名必须选择公开的 480p 或 720p SKU。该模式不能同时传参考视频或参考音频：

json

{
  "model": "leonardo-seedance-2.5-720p",
  "operation": "generation",
  "input": {
    "prompt": "从 @start 的清晨湖面平滑过渡到 @end 的夜间灯会，保持建筑和机位连续",
    "reference_mode": "frame",
    "image": {
      "url": "https://media.example.com/lake-morning.jpg",
      "name": "start"
    },
    "reference_images": [
      {
        "url": "https://media.example.com/lake-night.jpg",
        "name": "end"
      }
    ]
  },
  "output": {
    "duration": 15,
    "aspect_ratio": "16:9",
    "generate_audio": true
  }
}

使用多媒体参考素材

下面的示例使用 media 模式组合图片、视频和音频。不同模型 ID 范围支持的素材类型和数量不同，请先查看模型 ID 范围差异。素材的 name 必须唯一，可在提示词中使用 @name 引用。

json

{
  "model": "adobe-seedance-2.0-720p",
  "operation": "generation",
  "input": {
    "prompt": "保持 @product 的外观，采用 @motion 的运镜，并配合 @music 的节奏",
    "reference_mode": "media",
    "reference_images": [
      {
        "url": "https://media.example.com/product-front.png",
        "name": "product"
      }
    ],
    "reference_videos": [
      {
        "url": "https://media.example.com/camera-motion.mp4",
        "name": "motion"
      }
    ],
    "reference_audios": [
      {
        "url": "https://media.example.com/music.mp3",
        "name": "music"
      }
    ]
  },
  "output": {
    "duration": 4,
    "aspect_ratio": "9:16",
    "generate_audio": true
  }
}

参考素材格式、时长限制、计费和错误码统一见参数与错误。

Seedance 2.0 / Fast 图片加音频参考

Seedance 2.0 / Fast 最多接受一个参考音频，且音频必须搭配图片或视频。调用方只传 URL，不传音频时长：

json

{
  "model": "leonardo-seedance-2.0-fast-480p",
  "operation": "generation",
  "input": {
    "prompt": "保持 @character 的外观，并让动作配合 @rhythm 的节奏",
    "reference_mode": "media",
    "reference_images": [
      {
        "url": "https://media.example.com/character.png",
        "name": "character"
      }
    ],
    "reference_audios": [
      {
        "url": "https://media.example.com/rhythm.wav",
        "name": "rhythm"
      }
    ]
  },
  "output": {
    "duration": 4,
    "aspect_ratio": "16:9",
    "generate_audio": true
  }
}

Seedance 2.0 视频加音频参考

参考音频也可以搭配视频，不要求同时提供图片：

json

{
  "model": "leonardo-seedance-2.0-720p",
  "operation": "generation",
  "input": {
    "prompt": "沿用 @motion 的运镜并匹配 @music 的节奏",
    "reference_mode": "media",
    "reference_videos": [
      {
        "url": "https://media.example.com/motion.mp4",
        "name": "motion"
      }
    ],
    "reference_audios": [
      {
        "url": "https://media.example.com/music.mp3",
        "name": "music"
      }
    ]
  },
  "output": {
    "duration": 4,
    "aspect_ratio": "9:16",
    "generate_audio": true
  }
}

Seedance 2.0 / Fast 会按真实文件检测 MP3/WAV 时长。单个音频为 2–15 秒、最多 15 MB，全部参考音频总时长最多 15 秒。这里的 reference_audios 是生成参考；generate_audio 决定成片是否有音轨。

Seedance 2.5 多媒体参考

Seedance 2.5 的 media 模式当前最多接受 30 张图片、10 个视频和 10 个音频。参考视频单个 3–10 秒，全部参考视频总时长最多 30.2 秒；参考音频单个 2–15 秒，全部参考音频总时长最多 30.2 秒。音频仍需搭配至少一张图片或一个视频：

json

{
  "model": "leonardo-seedance-2.5-480p",
  "operation": "generation",
  "input": {
    "prompt": "保持 @character 的造型，沿用 @motion 的运动节奏，并参考 @voice 的声音表现",
    "reference_mode": "media",
    "reference_images": [
      {
        "url": "https://media.example.com/character.png",
        "name": "character"
      }
    ],
    "reference_videos": [
      {
        "url": "https://media.example.com/motion.mp4",
        "name": "motion"
      }
    ],
    "reference_audios": [
      {
        "url": "https://media.example.com/voice.wav",
        "name": "voice"
      }
    ]
  },
  "output": {
    "duration": 15,
    "aspect_ratio": "9:16",
    "generate_audio": true
  }
}

请求中不要添加视频或音频时长字段。平台会探测真实文件，并在上传后按当前模型能力复核；若当前模型能力更窄，创建任务会返回具体的参数错误，不应通过减少校验来强行提交。

查询任务

bash

export TASK_ID="task_example123"

curl -sS "$SUPERTOKEN_BASE_URL/v1/video/tasks/$TASK_ID" \
  -H "Authorization: Bearer $RESOURCE_API_KEY" | jq .

状态	含义	建议动作
`queued`	任务已创建并等待执行	按 `Retry-After` 建议间隔继续查询
`in_progress`	正在生成	继续轮询，不要高频请求
`succeeded`	已完成	从 `result.videos[]` 读取视频结果
`failed`	任务失败	查看 `error.code`、`error.message` 和 `error.retryable`

成功任务示例：

json

{
  "id": "task_example123",
  "object": "video.task",
  "model": "adobe-seedance-2.0-480p",
  "operation": "generation",
  "status": "succeeded",
  "progress": 100,
  "result": {
    "videos": [
      {
        "asset_id": "asset_example123",
        "index": 0,
        "url": "https://media.example.com/results/video.mp4?token=...",
        "mime_type": "video/mp4",
        "duration_ms": 4000,
        "temporary": true,
        "url_auth": "none"
      }
    ]
  },
  "error": null,
  "client_reference_id": "order-20260730-001",
  "metadata": {
    "order_id": "order-20260730-001"
  },
  "created_at": 1785373200,
  "started_at": 1785373202,
  "completed_at": 1785373268,
  "updated_at": 1785373268
}

下载视频

先检查 result.videos[].url_auth：

`url_auth`	下载方式
`none`	直接请求 `url`，不附加 SuperToken 密钥
`resource_api_key`	请求 `url` 时发送 `Authorization: Bearer ak_...`

当结果返回 url_auth: "none" 时，完整保留 URL 查询参数并直接下载：

bash

export VIDEO_URL="https://media.example.com/results/video.mp4?token=..."

curl -L "$VIDEO_URL" --output seedance-result.mp4

若响应为 url_auth: "resource_api_key"，才在请求该 URL 时携带资源 API Key：

bash

curl -L "$VIDEO_URL" \
  -H "Authorization: Bearer $RESOURCE_API_KEY" \
  --output seedance-result.mp4

不要根据模型名猜测鉴权方式。temporary: true 表示结果地址不应被当作永久公开链接；地址过期后不会刷新或归档，需要长期保存时请及时转存。

duration_ms 当前由已验证的请求时长回显，用于展示和审计，不表示 SuperToken 下载媒体后重新探测了真实时长，也不会触发二次计费。

完整 Python 轮询示例

下面只使用 Python 标准库：sk-... 创建任务，ak_... 查询任务。

python

import json
import os
import time
import urllib.error
import urllib.request

base_url = os.environ.get("SUPERTOKEN_BASE_URL", "https://api.supertoken.cc").rstrip("/")
model_key = os.environ["SUPERTOKEN_KEY"]
resource_key = os.environ["RESOURCE_API_KEY"]


def request_json(method, path, token, body=None, headers=None):
    data = None if body is None else json.dumps(body).encode("utf-8")
    request = urllib.request.Request(
        f"{base_url}{path}",
        data=data,
        method=method,
        headers={
            "Authorization": f"Bearer {token}",
            "Content-Type": "application/json",
            **(headers or {}),
        },
    )
    with urllib.request.urlopen(request, timeout=60) as response:
        return json.load(response), response.headers


task, response_headers = request_json(
    "POST",
    "/v1/video/tasks",
    model_key,
    {
        "model": "adobe-seedance-2.0-480p",
        "operation": "generation",
        "input": {"prompt": "一架纸飞机穿过明亮的现代图书馆，平滑跟拍"},
        "output": {"duration": 4, "aspect_ratio": "16:9"},
        "client_reference_id": "python-video-001",
    },
    {"Idempotency-Key": "python-video-001"},
)

task_id = task["id"]
poll_seconds = int(response_headers.get("Retry-After", "2"))
print("created:", task_id)

while task["status"] not in {"succeeded", "failed"}:
    time.sleep(max(poll_seconds, 2))
    task, _ = request_json(
        "GET", f"/v1/video/tasks/{task_id}", resource_key
    )
    print(task["status"], task["progress"])

if task["status"] == "failed":
    raise RuntimeError(task["error"])

for video in task["result"]["videos"]:
    print(video["url"], video["url_auth"])

不希望持续轮询时，可以启用 Webhook。Webhook 到达后仍可用任务查询接口核对最终状态。

列表与批量查询

按条件列出批量查询

bash

curl -sS \
  "$SUPERTOKEN_BASE_URL/v1/video/tasks?status=succeeded&operation=generation&limit=20" \
  -H "Authorization: Bearer $RESOURCE_API_KEY" | jq .

bash

curl -sS "$SUPERTOKEN_BASE_URL/v1/video/tasks/query" \
  -H "Authorization: Bearer $RESOURCE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "task_ids": [
      "task_example123",
      "task_example456"
    ]
  }' | jq .

列表接口支持 status、operation、client_reference_id、created_after、created_before、after 和 limit。limit 默认为 20，范围为 1 到 100；批量查询一次最多传入 100 个任务 ID，响应的 missing 会列出未找到的 ID。

任务会同时出现在控制台的“任务日志”；成功视频会进入“资源管理中心 → 资源列表”，可以按任务 ID、模型和资源类型筛选。

GPT-Image-2

Gemini Images

Seedance

Kling 3.0

Veo 3.1

MiniMax H3

异步视频任务

端点

创建文生视频任务

上传本地参考素材

使用首帧和尾帧

Seedance 2.5 首尾帧

使用多媒体参考素材

Seedance 2.0 / Fast 图片加音频参考

Seedance 2.0 视频加音频参考

Seedance 2.5 多媒体参考

查询任务

下载视频

完整 Python 轮询示例

列表与批量查询

下一步

异步视频任务 ​

端点 ​

创建文生视频任务 ​

上传本地参考素材 ​

使用首帧和尾帧 ​

Seedance 2.5 首尾帧 ​

使用多媒体参考素材 ​

Seedance 2.0 / Fast 图片加音频参考 ​

Seedance 2.0 视频加音频参考 ​

Seedance 2.5 多媒体参考 ​

查询任务 ​

下载视频 ​

完整 Python 轮询示例 ​

列表与批量查询 ​

下一步 ​

异步视频任务

端点

创建文生视频任务

上传本地参考素材

使用首帧和尾帧

Seedance 2.5 首尾帧

使用多媒体参考素材

Seedance 2.0 / Fast 图片加音频参考

Seedance 2.0 视频加音频参考

Seedance 2.5 多媒体参考

查询任务

下载视频

完整 Python 轮询示例

列表与批量查询

下一步