TokenLink Docs

视频生成

从文本或参考图生成视频，轮询查询结果并下载

TokenLink 提供统一的异步视频生成 API。由于生成可能需要几分钟，流程是 创建 → 轮询 → 下载，而不是一次请求直接返回。

所有视频端点都在 /videos 下，认证方式为 Authorization: Bearer YOUR_API_KEY。

整体流程

列出模型 ──► 创建任务 ──► 轮询状态 ──► 下载成品
                          ▲
                          └── 或在 callback_url 接收回调
端点方法作用
/videos/modelsGET列出可用视频模型及其能力
/videosPOST创建生成任务（返回 202）
/videos/{job_id}GET查询任务当前状态
/videos/{job_id}/content?index=0GET下载生成的视频

1. 列出视频模型

GET /videos/models

每个模型都会返回它实际支持的参数，因此你可以把 POST /videos 请求体限制在模型支持的范围内。

curl $BASE_API/videos/models \
  -H "Authorization: Bearer YOUR_API_KEY"
{
  "data": [
    {
      "id": "veo-3-fast",
      "name": "veo-3-fast",
      "supported_durations": [4, 6, 8],
      "supported_resolutions": ["720p", "1080p"],
      "supported_aspect_ratios": ["16:9", "9:16"],
      "supported_sizes": [],
      "pricing_skus": { "1080p": "0.12", "720p": "0.08" },
      "allowed_passthrough_parameters": ["provider_options"]
    }
  ]
}
  • pricing_skus 是按分辨率区分的每秒单价，最终按 时长 × 分辨率单价 计费。
  • allowed_passthrough_parameters 列出哪些请求字段会透传给上游厂商。

2. 创建任务

POST /videos

只有 model 是必填，其余参数按模型支持情况填写。

curl $BASE_API/videos \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "veo-3-fast",
    "prompt": "日落时分的未来城市广角镜头，电影感光影",
    "duration": 6,
    "resolution": "1080p",
    "aspect_ratio": "16:9",
    "generate_audio": false
  }'

响应（202 Accepted）：

{
  "id": "675f9c1b2e3a4f5b6c7d8e9f",
  "polling_url": "/videos/675f9c1b2e3a4f5b6c7d8e9f",
  "status": "pending"
}

请保存 id——轮询和下载都要用到。

请求体

字段类型说明
modelstring必填。 来自 /videos/models 的模型 ID
promptstring视频的文本描述
durationinteger时长（秒），取 supported_durations 中的值
resolutionstring480p / 720p / 1080p / 4k
aspect_ratiostring16:9 / 9:16 / 1:1
sizestring厂商特定的输出尺寸
generate_audioboolean是否为片段合成音频
frame_imagesarray参考帧（见 MediaRef）
input_referencesarray输入图片/视频/音频引用（见 MediaRef）
provider_optionsobject厂商特定透传参数（仅当出现在 allowed_passthrough_parameters 中）
callback_urlstring完成时通知的 Webhook 地址（见 Webhook）

媒体引用

frame_images 和 input_references 使用如下结构：

{
  "type": "image_url",
  "url": "https://example.com/ref.png",
  "media_type": "image/png",
  "frame_type": "first_frame"
}
字段说明
typeimage_url / video_url / audio_url
url引用资源的公开 URL（或改用 base64）
base64引用资源的 Base64 编码，url 的替代方案
media_typeMIME 类型，如 image/png
frame_typefirst_frame / last_frame / reference_image

幂等

为避免 POST /videos 重试时创建重复任务，可发送 Idempotency-Key 请求头。复用同一个 key 会返回已有任务而不是新建。

curl $BASE_API/videos \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Idempotency-Key: my-request-123" \
  -H "Content-Type: application/json" \
  -d '{ "model": "veo-3-fast", "prompt": "..." }'

3. 轮询状态

GET /videos/{job_id}
curl $BASE_API/videos/675f9c1b2e3a4f5b6c7d8e9f \
  -H "Authorization: Bearer YOUR_API_KEY"

响应会回显你的请求参数并附上任务状态：

{
  "id": "675f9c1b2e3a4f5b6c7d8e9f",
  "model": "veo-3-fast",
  "status": "completed",
  "duration": 6,
  "resolution": "1080p",
  "outputs": [{ "type": "video", "url": "https://cdn.../clip.mp4", "media_type": "video/mp4" }],
  "completed_at": "2026-09-25T12:00:00Z",
  "expires_at": "2026-10-02T12:00:00Z"
}

状态值

状态含义
pending任务已受理，尚未提交上游
in_progress已提交上游，正在处理
completed视频已就绪——outputs 已填充
failed生成失败——见 error
cancelled任务已取消
expired任务在完成前过期

每隔几秒轮询一次，直到状态离开 pending / in_progress。一个简单的 Python 轮询循环：

import os
import time

import requests

BASE = os.environ["BASE_API"]
HEAD = {"Authorization": "Bearer YOUR_API_KEY"}

job = requests.post(f"{BASE}/videos", headers=HEAD, json={
    "model": "veo-3-fast",
    "prompt": "航拍瀑布的镜头",
    "duration": 6,
    "resolution": "1080p",
    "aspect_ratio": "16:9",
}).json()

while True:
    state = requests.get(f"{BASE}{job['polling_url']}", headers=HEAD).json()
    status = state["status"]
    if status in ("completed", "failed", "cancelled", "expired"):
        break
    time.sleep(5)

print(status)
if status == "completed":
    print(state["outputs"])
else:
    print(state.get("error"))

4. 下载成品

GET /videos/{job_id}/content?index=0
curl "$BASE_API/videos/675f9c1b2e3a4f5b6c7d8e9f/content?index=0" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  --output video.mp4
  • 返回视频字节流（video/mp4）。
  • index 用于在一次任务产出多个视频时选择下载哪个（默认 0）。
  • 只有当状态为 completed 时才能下载，否则返回 4007（任务尚未完成）。
  • 内容 URL 在 expires_at 之前有效（创建后 7 天），过期前需重新下载。

Webhook 回调

创建任务时传入 callback_url 即可跳过轮询。任务完成（或失败）时，TokenLink 会向该 URL POST 一个 JSON 事件：

{
  "type": "video.generation.completed",
  "created_at": "2026-09-25T12:00:00Z",
  "data": {
    "id": "675f9c1b2e3a4f5b6c7d8e9f",
    "status": "completed",
    "model": "veo-3-fast"
  }
}
  • 事件类型为 video.generation.<status>（例如 video.generation.failed）。
  • 请在 30 秒内返回 2xx，未成功会持续重试。

计费

视频按 时长 × 分辨率单价（pricing_skus，见 /videos/models）计费，任务达到 completed 时扣费一次。

错误码

错误码含义
4004额度不足
4006视频任务或内容不存在
4007视频任务存在但尚未完成

全部错误码及处理办法见 错误码表。

本页目录

整体流程1. 列出视频模型2. 创建任务请求体媒体引用幂等3. 轮询状态状态值4. 下载成品Webhook 回调计费错误码