视频与素材
创建视频
提交视频生成任务
概述
视频生成需要一些时间。创建成功后会返回任务 ID 和 poll_url，通过这个地址查询进度和结果。
查询任务状态
直接请求创建响应中的 poll_url。id 与 task_id 指向同一个任务，也可以通过 GET /v1/tasks/{id} 查询。
音频与媒体输入
音频行为取决于所选模型和操作。没有音频开关，不代表视频必须无声；省略参数也不等于发送 false。
veo3.1和veo3.1-fast按 Gemini API 契约始终生成音频。wan-2.6和wan-2.7的视频生成也不支持关闭声音。省略output_audio；模型详情允许时也可设置为true。hailuo-h3和 Grok 视频模型原生生成音频。不要添加所选模型详情未列出的音频开关。- Seedance 1.5/2.x 与
viduq3-pro/viduq3-turbo默认开启音频，并支持无声输出；PixVerse C1/V5.6/V6 默认关闭音频。仅在当前操作列出该字段时使用output_audio；Vidu 也接受其契约声明的布尔字段audio。 audio_url/audio_urls用于输入或参考音频，不是输出声音开关。视频编辑、动作迁移和风格转换可能保留输入音轨；保留原音不等于静音。
允许值及音频相关价格以模型详情为准。受支持的兼容字段 outputAudio、generate_audio 和布尔 audio 与 output_audio 同时出现时，值必须一致。不要假定同系列各版本、各操作的声音控制相同。
图片、视频和音频建议使用公网可访问的 https URL。部分模型也接受内联 data: URL；文件较大时，URL 会更稳定。
请求体
veo3.1视频模型 ID。可从 Models API 获取当前可用模型，用 operation 选择文生视频、图生视频等生成方式。
PixVerse
- 模型:
pixverse-c1,pixverse-v6,pixverse-v5.6 - 操作:
text-to-video,image-to-video,start-end-to-video,reference-to-video - 音频参数:
output_audio, 默认为false
在 TokenLab 上，上述 PixVerse 模型不接受 operation=video-extension。
HappyHorse
- 模型:
happyhorse-1.0 - 操作:
text-to-video,image-to-video,reference-to-video,video-to-video - 音频参数: 不要传入
output_audio
要生成视频的文本描述。大多数公开视频模型都要求该字段。
生成方式。支持 text-to-video、image-to-video、reference-to-video、start-end-to-video、video-to-video、video-extension、audio-to-video 和 motion-control。省略时会根据输入判断；明确填写可以更早发现不匹配的参数。
图生视频的起始图片。可传公网 https URL；Seedance 也接受处于 ACTIVE 状态的 TokenLab 素材 URI，例如 asset://asset-YYYYMMDDHHMMSS-xxxxx。
以内联 data URL 形式提供的图片（例如 data:image/jpeg;base64,...）。兼容模型支持该方式，但 image_url 的兼容性更广。
参考图列表，数量上限取决于模型。seedance-2.0 和 seedance-2.0-fast 最多支持 9 张参考图、3 段参考视频和 3 段参考音频；图片可以使用公网 https URL 或处于 ACTIVE 状态的 TokenLab 素材 URI。grok-imagine-video 最多接受 7 张参考图，生成时长最高 10 秒；grok-imagine-video-1.5-preview 只支持图生视频。Seedance 的分辨率和素材限制见 Seedance 2.0 视频模型指南。
创建素材返回的 Seedance 素材 ID。素材状态变为 ACTIVE 后，可用于 reference-to-video。作为图生视频首帧时，请改用 image_url: "asset://<material_asset_id>"；首尾帧分别使用 start_image 和 end_image。
多个 Seedance 素材 ID，用于 reference-to-video。它们与 reference_images 共用图片数量上限。作为图生视频首帧时，请将对应素材写入 image_url。
普通图片 URL 作为图片输入，不会自动创建可复用素材。需要复用时先通过素材 API 创建，再使用 TokenLab 素材 ID 或 asset://asset-YYYYMMDDHHMMSS-xxxxx URI。显式素材返回 409 seedance_material_preparing 时，查询响应中的 inactive_asset_ids，待素材变为 ACTIVE 后重试。
可选的参考图角色字段，用于区分 asset 和 style 两类参考图的模型。
仅当所选模型的当前公开详情列出 kling_elements 时使用。请求需包含图片输入和 1–3 个元素；每个元素包含 name、可选 description 和 2–4 个 element_input_urls，并在 prompt 中以 @name 引用。不能与 output_audio=true 组合。
源视频的公网 URL。video-to-video 和 motion-control 使用该字段；部分续写或扩展功能使用 task_id。
用于支持多模态参考条件控制的额外参考视频输入。可传数量取决于模型。对于 seedance-2.0 和 seedance-2.0-fast，TokenLab 当前支持最多 3 段参考视频。
所选模型支持的音频驱动或参考音频操作所用的公开音频 URL。
用于支持多模态参考条件控制的额外参考音频输入。可传数量取决于模型。对于 seedance-2.0 和 seedance-2.0-fast，TokenLab 当前支持最多 3 段参考音频。
部分续写、扩展或衍生功能使用的任务 ID。
部分 video-extension 模型使用的扩展起点。
部分 video-extension 模型使用的扩展次数或倍率。
生成输出视频的时长（秒）。Seedance 1.5/2.0 模型省略时默认 5 秒；传 -1 表示让模型在支持范围内自动选择时长，任务完成前会按保守方式预估费用。
duration 的兼容别名。若同时传 seconds 和 duration，两者必须完全一致。对 Seedance，seconds=-1 与 duration=-1 一样表示自动时长。
视频宽高比，例如 adaptive、16:9、9:16、1:1、4:3、3:4 或 21:9。Seedance 省略时默认为 adaptive。
模型相关的输出分辨率。Seedance 省略时默认 720p；seedance-2.0 支持 480p、720p、1080p 和 4k，seedance-2.0-fast / seedance-2.0-mini 仅支持 480p 和 720p。
仅用于声明了该字段的操作。省略时遵循模型默认行为；只有允许时，false 才表示无声输出。参见上方音频说明和所选模型详情。
是否使用 Seedance 1.5 Pro 草稿模式。不要和 draft_task_id 同时传入。
Seedance 1.5 Pro 草稿晋升任务 ID。传入上一次草稿任务 ID 后创建正式视频；这不是通用视频字段。
aspect_ratio 的兼容别名。若同时传 ratio 和 aspect_ratio，两者必须完全一致。
output_audio 的兼容别名。generate_audio、output_audio、outputAudio 同时出现时，所有值必须一致。
兼容视频模型的执行过期时间（秒）。Seedance 省略时默认 172800 秒。
兼容视频模型的任务优先级，范围 0 到 9。不要把 priority 与 service_tier=flex 组合使用。
兼容视频模型的终端用户安全标识。Seedance 未传该字段时，TokenLab 会使用 user 的值。
default 对 Seedance 2.0 会按兼容 no-op 处理。只有所选模型明确支持时才可使用 flex。
兼容视频模型的可选帧数。Seedance 2.0 模型和 Seedance 1.5 Pro 不支持该字段。
兼容视频模型的固定相机开关。Seedance 2.0 模型不支持该字段。
每秒帧数（1-120），仅在模型公开支持 FPS 控制时生效。
希望在视频生成中避免的内容。
用于可复现生成的随机种子。Seedance 省略时使用 -1 表示随机种子。
提示词遵循强度（0-20），仅在公开模型支持该控制项时生效。
运动强度（0-1），仅在公开模型支持该字段时生效。
start-end-to-video 中使用的起始帧图片 URL 或兼容图片输入。
start-end-to-video 中使用的结束帧图片 URL 或兼容图片输入。
兼容视频模型使用的模型相关尺寸档位参数。
某些模型暴露的水印开关。Seedance 省略时默认 false。
部分特效或编辑模型使用的效果类型。
终端用户的唯一标识符。对 Seedance，如果未传 safety_identifier，TokenLab 会使用该值。
兼容字段
- 主要字段使用 snake_case：
aspect_ratio、output_audio、reference_images和reference_image_type。 - 为了兼容已有调用，TokenLab 也接受
ratio、generate_audio、outputAudio、seconds、referenceImages和referenceImageType。 - 如果主要字段和别名同时出现，两边的值必须一致。
- 如果省略
operation，TokenLab 会根据输入判断生成方式。
媒体输入
image_url、reference_images、video_url和audio_url建议使用公网可访问的httpsURL。- 同一请求尽量统一使用 URL 或内联 base64，避免混用。
- 远程媒体 URL 需要在任务开始处理前保持有效。
Seedance 参数
对于 Seedance 1.5/2.0 模型，统一接口以 TokenLab 字段为主，同时接受兼容别名 seconds、ratio 和 generate_audio。省略 Seedance 参数时会使用这些默认值：duration=5、resolution=720p、aspect_ratio=adaptive、output_audio=true、watermark=false、return_last_frame=false、execution_expires_after=172800、priority=0、seed=-1。
duration=-1 或 seconds=-1 表示让 Seedance 在模型支持范围内自动选择输出时长。TokenLab 会在任务完成前按保守方式预估费用，并在可获得完成任务 usage 时按实际结果结算。service_tier=default 对 Seedance 2.0 作为兼容 no-op 接受；service_tier=flex、frames、camera_fixed 会在所选模型不支持时被拒绝。
Seedance 示例
curl -X POST "https://api.tokenlab.sh/v1/videos/generations" \
-H "Authorization: Bearer sk-your-api-key" \
-H "Content-Type: application/json" \
-d '{
"model": "seedance-2.5",
"prompt": "A sleek product reveal with cinematic camera movement",
"operation": "text-to-video",
"duration": -1,
"aspect_ratio": "adaptive",
"resolution": "720p",
"output_audio": true
}'响应
结果、错误、时间戳和模型字段仅在任务提供时返回。
任务 ID。
与 id 相同的任务 ID。
查询任务状态和结果的地址。
结算完成后返回的账单交易 ID，与任务 ID 不同。
任务状态：pending、processing、completed、failed。
创建任务时的 Unix 时间戳。
所使用的模型。
结果已就绪时可直接使用的视频 URL。
可用时返回单个视频对象，包含 url、duration、width 和 height。
当任务生成多个输出时，可能出现视频数组。
任务失败时返回的错误信息或结构化错误对象。
请求
curl -X POST "https://api.tokenlab.sh/v1/videos/generations" \
-H "Authorization: Bearer sk-your-api-key" \
-H "Content-Type: application/json" \
-d '{
"model": "veo3.1",
"prompt": "A cat walking through a garden, cinematic lighting",
"operation": "text-to-video",
"duration": 4,
"aspect_ratio": "16:9"
}'响应
{
"id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"task_id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"poll_url": "/v1/tasks/ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"status": "pending",
"model": "veo3.1",
"created": 1706000000
}图生视频
response = requests.post(
"https://api.tokenlab.sh/v1/videos/generations",
headers={"Authorization": "Bearer sk-your-api-key"},
json={
"model": "hailuo-2.3-standard",
"prompt": "The scene begins from the provided image and adds gentle natural motion.",
"operation": "image-to-video",
"image_url": "https://example.com/image.jpg",
"duration": 6,
"resolution": "768p"
}
)Kling 3.0 元素引用
仅当所选模型的当前公开详情列出 kling_elements 时使用。请求需包含图片输入和 1–3 个元素；每个元素包含 name、可选 description 和 2–4 个 element_input_urls，并在 prompt 中以 @name 引用。不能与 output_audio=true 组合。
参考图生视频
当模型支持专门的参考条件控制时，请使用 operation=reference-to-video。在 TokenLab 请求中，图片参考素材使用 reference_images，多模态参考视频和参考音频分别使用 video_urls 与 audio_urls。对于 seedance-2.0 和 seedance-2.0-fast，TokenLab 当前支持最多 9 张参考图，外加最多 3 段参考视频和 3 段参考音频。模型选型、4K 边界和 Mini 说明请参考 Seedance 2.0 视频模型指南。duration 只控制生成输出时长，不单独限制参考视频输入时长。 对于 grok-imagine-video，reference-to-video 最多接受 7 个图片参考（reference_images 或 image_urls），且 duration 最高为 10 秒。不要把参考图片与 image_url / image 首帧输入混用。grok-imagine-video-1.5-preview 仅支持图生视频。
response = requests.post(
"https://api.tokenlab.sh/v1/videos/generations",
headers={"Authorization": "Bearer sk-your-api-key"},
json={
"model": "veo3.1",
"prompt": "Keep the same subject identity and palette while adding subtle motion.",
"operation": "reference-to-video",
"reference_images": [
"https://example.com/ref-a.jpg",
"https://example.com/ref-b.jpg"
],
"reference_image_type": "asset",
"duration": 8,
"resolution": "720p",
"aspect_ratio": "9:16"
}
)首尾帧控制
使用 start_image 和 end_image 控制首帧和尾帧：
response = requests.post(
"https://api.tokenlab.sh/v1/videos/generations",
headers={"Authorization": "Bearer sk-your-api-key"},
json={
"model": "viduq2-pro",
"operation": "start-end-to-video",
"start_image": "https://example.com/day.jpg",
"end_image": "https://example.com/night.jpg",
"duration": 5,
"resolution": "720p",
"aspect_ratio": "16:9"
}
)视频转视频
grok-imagine-video 的 video-to-video 接受公网 HTTPS .mp4 URL，可将 resolution 设为 480p 或 720p；该模式不接受 duration 和 aspect_ratio。
使用现有视频作为输入时，将 operation 设为 video-to-video。
response = requests.post(
"https://api.tokenlab.sh/v1/videos/generations",
headers={"Authorization": "Bearer sk-your-api-key"},
json={
"model": "grok-imagine-video",
"operation": "video-to-video",
"video_url": "https://example.com/source.mp4",
"prompt": "Enhance the clip while preserving the original motion."
}
)动作控制
需要主体图片和动作参考视频时，将 operation 设为 motion-control，并分别传入 image_url 和 video_url。
response = requests.post(
"https://api.tokenlab.sh/v1/videos/generations",
headers={"Authorization": "Bearer sk-your-api-key"},
json={
"model": "kling-3.0-motion-control",
"operation": "motion-control",
"prompt": "Keep the subject stable while following the motion reference.",
"image_url": "https://example.com/subject.png",
"video_url": "https://example.com/motion.mp4",
"resolution": "720p"
}
)模型发现
可用模型和生成方式可能调整。通过 Models API 获取当前信息：
curl "https://api.tokenlab.sh/v1/models?recommended_for=video"
curl "https://api.tokenlab.sh/v1/models/veo3.1"audio-to-video、video-extension 等功能只在部分模型中提供，以单个模型的详情响应为准。
授权
BearerAuth API Key 身份验证。在 Dashboard > API > API Keys 中创建或管理 API Key。
位置: header
请求头
单次请求的交付策略。覆盖 API 密钥和 Workspace 的默认设置。自动优先尝试 TokenLab Verified，并在输出、请求接受或持久资源创建之前，可能会切换一次至仅限 Official。
可选值
- "auto"
- "verified"
- "official"
请求体
application/json
响应
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json