视频生成任务

接口概览

视频生成是异步操作：

1. 调用 POST /v1/videos/tasks 提交任务
2. 保存响应中的公开任务 ID
3. 调用 GET /v1/tasks/{task_id} 查询状态和结果

Base URL 为 https://api.rokoapi.com/v1。所有请求都要携带 Authorization: Bearer $API_KEY。

提交响应在兼容期同时返回 id 和 task_id，两者值相同。新代码应读取 task_id；原来读取 id 的代码无需修改。生产环境应为每次业务操作设置唯一的 Idempotency-Key。相同 Key 和相同请求重试时会重放第一次响应，不会创建第二个上游任务；完整规则见图像生成任务的幂等提交说明，该规则同样适用于图片、视频和音频统一任务端点。

Seedance 视频交付与永久保存

Seedance 系列视频生成成功后，RokoAPI 会在后台将结果转存到自己的媒体存储。转存完成前，查询响应保持 state: "in_progress"，不会返回第三方视频地址。请继续轮询同一任务，不要重复提交生成请求。

转存完成后，响应返回 state: "completed"、result_url 和 expires_at（无到期时间时为 0 或省略）。assets 中的视频 URL 与主结果地址一致。OpenAI 视频兼容查询通过 metadata.url 返回视频地址，并提供顶层 expires_at。

视频转存后在 RokoAPI 自有 R2 中永久保存，不自动过期或清理。用户可随时访问返回的结果链接。 expires_at 为 0 或省略，表示没有自动到期时间。

转存期间系统自动重试，重试不会重新生成视频或重复收取生成费用。如果查询返回 archive_status: "failed"，请保留任务 ID 联系支持；不要通过反复提交生成任务来重试下载。

已适配模型

实际可用范围以 /v1/models、控制台渠道配置和密钥所属分组为准。用户只选择产品模型；RokoAPI 根据 generation_type、素材字段和渠道能力自动选择文生、图生、参考生或编辑路由。供应商内部模型名不会出现在用户响应、计费模型或使用日志中。

TTAPI 渠道目前按能力处理模式，而不是假定所有模型都支持所有生成方式：

请求显式指定上游不支持的模式或声音开关时，接口返回 400，不会静默忽略参数后提交计费任务。未传 generation_type 时，0 个素材推断为文生、1 张图片推断为图生，多个图片或视频/音频素材推断为参考生。

Vidu Q4 Preview 与 Q3 系列通过 Vidu 官方渠道调用，渠道基址为 https://api.vidu.cn，并按模型能力选择官方的图生、参考生、文生或首尾帧端点：

Vidu 请求统一使用 image_urls 提供图片素材。Q4 图生必须传 1 张图并继承输入图比例，不要传 aspect_ratio；Q4 参考生传 1～15 张图，并可用 audio_urls 传 0～3 个 MP3 声音参考。Q3 一张图片为图生，两张图片并指定 generation_type: "start-end" 为首尾帧，参考生可传 1～7 张图片。RokoAPI 会在渠道适配层转换为 Vidu 官方协议，调用方不需要发送供应商字段 images 或 sounds。

文生视频

curl https://api.rokoapi.com/v1/videos/tasks \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: YOUR_UNIQUE_REQUEST_ID" \
  -d '{
    "model": "seedance-2.0",
    "generation_type": "text",
    "prompt": "A cinematic sunrise over snow mountains",
    "duration": 8,
    "quality": "720p",
    "aspect_ratio": "16:9",
    "generate_audio": true
  }'

图生与参考生视频

通常通过 image_urls、video_urls 和 audio_urls 传入可由公网直接下载的素材：

{
  "model": "seedance-2.0",
  "generation_type": "reference",
  "prompt": "Keep the character identity and create a slow camera orbit",
  "image_urls": ["https://example.com/character.png"],
  "video_urls": ["https://example.com/motion.mp4"],
  "duration": 6,
  "quality": "720p",
  "aspect_ratio": "16:9"
}

例外：Wan 2.7 与 TTAPI Wan 3.0 图生视频使用 image_start 和可选的 image_end；Grok 1.5 根据 image_urls 数量自动选择模式（0 张为文生、1 张为图生、2～7 张为参考生）。

Vidu 首尾帧示例：

{
  "model": "viduq3-pro",
  "generation_type": "start-end",
  "prompt": "Keep the subject consistent and move the camera forward",
  "image_urls": [
    "https://example.com/start.png",
    "https://example.com/end.png"
  ],
  "duration": 5,
  "quality": "1080p",
  "generate_audio": true
}

Vidu Q4 Preview 多参考示例：

{
  "model": "viduq4-preview",
  "generation_type": "reference",
  "prompt": "Keep the character identity and continue walking forward",
  "image_urls": [
    "https://example.com/character.png",
    "https://example.com/style.png"
  ],
  "audio_urls": ["https://example.com/dialogue.mp3"],
  "duration": 8,
  "quality": "2K",
  "aspect_ratio": "3:4",
  "generate_audio": true
}

视频编辑

{
  "model": "wan-2.7",
  "generation_type": "edit",
  "prompt": "Change the background to a rainy neon street",
  "video_urls": ["https://example.com/input.mp4"],
  "image_urls": ["https://example.com/style.png"],
  "duration": 0,
  "quality": "720p"
}

Wan 2.7 编辑中的 duration: 0 表示跟随输入视频。Gemini Omni 编辑跟随输入视频，不要发送 duration 或 aspect_ratio。

Midjourney 视频延长

Midjourney Video 每次生成或延长固定增加 5 秒。延长时传入已完成的上游任务 ID，并从父任务返回的四个视频中选择 0～3 的索引：

{
  "model": "midjourney-video",
  "generation_type": "extend",
  "input_reference": "PARENT_JOB_ID",
  "metadata": {
    "index": 0,
    "animate_mode": "auto",
    "manual": "low",
    "bs": 4,
    "resolution": "sd"
  }
}

延长接口会继承父任务分辨率；metadata.resolution 仅用于预估费用，可填写父任务实际的 sd 或 hd。省略时会按 HD 预留，任务完成后再按 TTAPI 返回的实际 quota 结算。

生成数量可使用统一参数 n，允许值为 1、2、4，默认 4；也兼容 TTAPI 原生的 metadata.bs。两者同时提供时必须一致。

参数边界

请求中的额外模型参数会按供应商协议转换，包括 negative_prompt、generate_audio、content_filter、sound、prompt_extend 和 model_params。RokoAPI 会先校验时长、画质、画幅、素材数量、声音能力和回调地址等已知边界。除 Midjourney Video 用 n 选择 1、2、4 个输出外，其余视频模型不支持 n。

回调与查询

可选的 callback_url 必须是公开 HTTPS 地址，最长 2048 个字符，不能指向 localhost 或内网 IP。即使配置了回调，也建议保留轮询作为容错：

curl https://api.rokoapi.com/v1/tasks/task_public_id \
  -H "Authorization: Bearer $API_KEY"

查询响应中的 state 固定为 queued、in_progress、completed、failed 或 unknown，推荐新代码使用；旧的 status 字段继续保留。结果链接可能有有效期，生产环境应及时下载并转存。

计费说明

模型采用统一 v2 美元表达式计费，可在一个公式中组合输出秒数、输入参考视频秒数、输入图片数量、音频开关、分辨率、画质、生成方式和 Token 用量。提交时按经过校验的参数预扣；任务完成后根据实际 Token 或输出时长结算。

前端或第三方项目不应直接解析、执行 billing_expr。请从 GET /api/catalog/models 读取目标模型的 pricing_display，按 dimensions 展示参数档位、按 rates 展示每秒价格，并使用 formula 说明总价计算方式。pricing_display.expr_hash 变化表示后台价格规则已经更新，客户端应立即丢弃旧缓存。完整字段和降级规则见模型与定价。

以下为固定售价快照，已经包含对应上游公示成本价的 10% 服务费，单位均为美元。价格不会随上游积分实时变化；管理员审核上游调价后再更新本表和后台表达式。

Seedance 2.0 系列

Fast 与 Mini 的活动价来自 EvoLink 2026-08-07 调价，活动结束后不会自动改变 RokoAPI 售价，届时以后台审核后的新快照为准。

Grok 1.5 Fast（TTAPI 非官转）

grok-imagine-video-1.5 对外名称当前路由到 TTAPI 非官转的 grok-imagine-video-1.5-fast，按任务时长分档，不使用截图中官转渠道的按秒价格：

7 秒和 11 秒不受上游支持；480p、720p 同价，最终以 TTAPI 任务结果返回的实际 quota 结算。

其他按秒视频模型

Kling O3 同时按分辨率和声音开关计费：

Vidu Q4 Preview 与 Q3 官方模型

Vidu 官方返回的实际 credits 是最终结算依据。下表为后台复杂表达式在提交前使用的预估售价，已经按 1 credit = $0.00446 换算并包含 10% 服务费：

Q4 另提供 2K（$0.1864/秒）与 4K（$0.3827/秒）。开启音画同出时，Q4 每个任务的预估费用另加 15 credits（$0.07359）。实际任务费用为 provider_credits × $0.004906；上表仅用于上游尚未返回 credits 时的安全预扣，完成后会自动补扣或退还差额。

Sora 2 系列

Gemini Omni Token 价格

参考视频时长只有在系统完成媒体元数据校验或取得可信用量后才参与最终结算。完整价格以定价页和后台当前配置为准。上游价格来源可参阅 EvoLink 模型目录、Vidu 模型映射和Vidu 价格表。