视频任务

第 3 版 · 更新于 2026-11-12 · 阅读约 8 分钟

通过 Runtoken 提交和查询异步视频任务。

准备工作#

开始前，请准备：

• 平台 API Key 和可用的视频模型 ID。
• 所选模型的原生 JSON 请求体及 HTTP 客户端。
• 用于本次提交的幂等键，以及保存任务标识的位置。

接口与鉴权#

请求发送至 https://api.runtoken.net，并携带 Authorization: Bearer YOUR_PLATFORM_KEY。将 YOUR_PLATFORM_KEY 替换为在控制台创建的平台 API Key。

• 创建任务：POST /v1/video/generations，请求体必须是 JSON 对象。
• 查询任务：GET /v1/video/generations/{task_id}，路径中填写提交响应返回的原生任务 ID。

提交和查询时，按以下规则设置请求头。

原生任务 ID 与平台任务引用用途不同。返回信息中同时包含两者时，应一并保存；不要把平台任务引用填入路径中的 {task_id}。

创建任务#

参考下方原生请求示例，按所选模型的请求格式准备本地 JSON 文件。以下命令直接发送该文件，不预设某一家厂商的请求体结构。

curl -i 'https://api.runtoken.net/v1/video/generations' \
  -H 'Authorization: Bearer YOUR_PLATFORM_KEY' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: YOUR_IDEMPOTENCY_KEY' \
  --data-binary '@YOUR_VIDEO_REQUEST.json'

运行命令前，请替换以下占位值。

通过 model 字段选择模型的请求格式，应在该字段中填写平台模型目录中的 ID。提示词、参考素材、时长、分辨率等字段遵循所选模型的要求，不要在模型家族之间直接复制参数名或枚举值。

curl 通过 @ 读取本地文件，--data-binary 将文件内容作为请求体发送。-i 会同时显示响应头和响应体，便于在响应头返回任务引用时将其保存。

将提交响应、原生任务 ID、可用的平台任务引用、幂等键和提交的 JSON 一并保存。任务标识在响应中的具体位置以所选模型的响应说明为准，网关没有为所有厂商统一成同一个 JSON 字段。

支持的模型家族与原生请求示例#

Runtoken 支持 Seedance、MiniMax Hailuo、Alibaba Wan 和 Kling 的异步视频接入。各家族采用不同的原生请求结构，使用示例前，请先从平台模型目录选择可用的具体版本。

以下示例用于说明请求结构，不是一组通用默认配置。时长、分辨率、音频和生成模式等选项，取决于所选模型版本及其平台配置。

字节跳动 Seedance#

Seedance 使用原生 contents/generations/tasks 异步协议。文本提示词放在 content 数组中的文本项内。

{
  "model": "YOUR_MODEL_ID",
  "content": [
    {
      "type": "text",
      "text": "A cinematic shot of a train crossing a mountain bridge"
    }
  ],
  "generate_audio": true
}

将 YOUR_MODEL_ID 替换为平台模型 ID。采用此请求格式时，将 JSON 保存为 YOUR_VIDEO_REQUEST.json，再通过上方创建命令提交。

解析计费条件时，如果省略 generate_audio，平台按启用音频处理，但不会向请求体补入该字段。因此，这一计费行为不代表模型生成行为的默认承诺。

当前不支持编辑或派生任务、回调、非空 tools 和 draft。音频与分辨率选项需要匹配平台配置的计费条件。

MiniMax Hailuo#

Hailuo 使用 MiniMax 的异步 video_generation 协议。以下结构将提示词和生成选项放在请求体顶层。

{
  "model": "YOUR_MODEL_ID",
  "prompt": "A cinematic shot of a train crossing a mountain bridge",
  "duration": 6,
  "resolution": "1080P"
}

将 YOUR_MODEL_ID 替换为平台模型 ID，并将请求体保存为 YOUR_VIDEO_REQUEST.json，供上方创建命令读取。

部分版本要求首帧图像，或采用不同的分辨率取值。请按所选版本补充必需字段，不要将这一纯文本结构用于所有 Hailuo 模型。

相应计费规则需要从完成结果中取得可核验的时长与输入图像信息。计费规则能够处理某类用量，不代表模型的输入图像上限或免费额度。

阿里云 Wan#

Wan 使用百炼的异步视频合成协议，请求体将输入内容与生成参数分开组织。

{
  "model": "YOUR_MODEL_ID",
  "input": {
    "prompt": "A cinematic shot of a train crossing a mountain bridge"
  },
  "parameters": {
    "size": "1280*720",
    "duration": 5
  }
}

将 YOUR_MODEL_ID 替换为平台模型 ID，并将请求体保存为 YOUR_VIDEO_REQUEST.json，供上方创建命令读取。

网关会在发送给上游的请求中自动设置 X-DashScope-Async: enable，无需将这个上游请求头加入网关提交示例。

完成结果的用量依据包括视频数量、输入视频时长和输出视频时长。平台的 Wan 后台轮询间隔不少于 15 秒，这不代表客户端查询接口的通用间隔要求。

Kling#

当前 Kling 接入支持文生视频。它的原生请求体使用厂商模型名称，与其他示例中的平台 model 字段不同。

{
  "model_name": "YOUR_UPSTREAM_MODEL_NAME",
  "prompt": "A cinematic shot of a train crossing a mountain bridge",
  "duration": "5",
  "aspect_ratio": "16:9",
  "mode": "std"
}

将 YOUR_UPSTREAM_MODEL_NAME 替换为所选接入要求的厂商模型名称，不要与平台模型目录中的 ID 混用。

Kling 请求还需携带 X-Platform-Model: YOUR_MODEL_ID，其中 YOUR_MODEL_ID 填写平台模型 ID。

Kling 需使用所选接入提供的模型专属提交地址及路由配置；仅有这段 JSON 还不构成完整提交命令。X-Platform-Model 不能替代鉴权请求头或幂等键。

当前不支持视频输入或视频编辑。按时长计费时，完成结果必须包含且仅包含一条具有可核验时长的视频输出。model_name、duration 和 mode 是否适用，仍取决于厂商版本。

查询任务#

将提交响应返回的原生任务 ID 填入查询路径。

curl 'https://api.runtoken.net/v1/video/generations/YOUR_NATIVE_TASK_ID' \
  -H 'Authorization: Bearer YOUR_PLATFORM_KEY'

将 YOUR_NATIVE_TASK_ID 替换为返回的原生任务 ID，YOUR_PLATFORM_KEY 替换为平台 API Key。

如果该 ID 存在歧义，在同一查询请求中补充平台任务引用。

curl 'https://api.runtoken.net/v1/video/generations/YOUR_NATIVE_TASK_ID' \
  -H 'Authorization: Bearer YOUR_PLATFORM_KEY' \
  -H 'X-Video-Task-Ref: YOUR_VIDEO_TASK_REF'

将 YOUR_VIDEO_TASK_REF 替换为提交时保存的平台任务引用，其他占位值含义与上一示例相同。

Runtoken 会在后台轮询任务。查询响应保留厂商原生 JSON，因此客户端需要按所选模型的结构读取状态、错误和输出字段。仅收到 HTTP 响应，不能判断视频是否生成成功。

查询已有任务与创建新任务应分开处理，避免应用在查询时再次提交生成请求。

失败与重试#

先判断异常发生在提交、查询还是生成阶段，再采取对应操作。

客户端连接中断并不能证明任务失败。尤其不要在超时后自动生成新的幂等键，再次提交同一任务。

输入与结果#

向用户开放素材上传或生成选项前，先确认模型版本和支持的生成模式。文生视频接入成功，不代表该模型同时支持图生视频或视频编辑。

按原生响应格式读取结果，不假设所有模型共用 video_url 字段、统一的状态枚举或相同的媒体限制。

当前限制#

当前视频 API 接受 JSON 对象，采用异步任务方式。以下能力尚未开放：

• 流式视频生成，包括 stream: true 请求。
• 回调。
• 派生或续接任务。
• 视频工具。

当前 Kling 接入仅支持文生视频，不能据此推断它支持图生视频、视频输入或编辑。

用量与计费#

任务受理不代表生成完成或计费结算。视频计费需要可核验的用量依据，具体规则取决于模型及其在平台上配置的价格。

销售价格以平台模型目录为准。厂商官方价格，以及示例中的时长或分辨率，都不能作为 Runtoken 的收费承诺。模型权限、账户余额、任务限额和幂等检查仍然适用。

下一步#

通用网关行为见接入指南，其他媒体接口见图像和音频。