媒体指南
视频生成
用文字、图片、音频或已有视频生成新视频
视频生成需要一些时间。POST /v1/videos/generations 会返回任务 ID,通常还会提供 poll_url。用这个 ID 调用 GET /v1/tasks/{id} 查询,完成后即可取得视频。
可以在所选模型支持的图片字段中传入公网 HTTP(S) URL 或支持的 data URL。这些输入按普通媒体路径处理,不会自动创建可复用的素材 ID。
显式指定的素材仍在准备时,POST /v1/videos/generations 返回 409 seedance_material_preparing,并通过 inactive_asset_ids 列出相关素材。查询这些素材直到 ACTIVE,再用相同素材 ID 重试。如果素材为 FAILED,先根据 error_message 修正或重新导入。
选择 API
新接入可以直接使用 /v1/videos/generations。已有 Seedance 2.0 客户端如果发送的是火山 content[] 或 Action 请求,可以继续通过 /api/v3 使用原格式。两种 API 都使用 TokenLab Bearer API 密钥,但字段和状态值不同。
选择生成类型
请明确填写 operation,这样 API 才能按对应的生成类型校验参数。
operation | 必需或常用输入 | 用途 |
|---|---|---|
text-to-video | prompt | 仅从文本生成 |
image-to-video | image_url 或兼容的 image | 让起始图片动起来 |
reference-to-video | reference_images,支持时可加 video_urls / audio_urls | 参考人物、风格或素材 |
start-end-to-video | start_image, end_image | 控制第一帧和最后一帧 |
video-to-video | video_url 或特定模型的 task_id | 转换或放大现有剪辑 |
motion-control | image_url 加 video_url | 让主体参考一段视频的动作 |
audio-to-video | audio_url | 根据音频生成视频 |
video-extension | task_id、extend_at 或模型专属续写字段 | 续写已有视频 |
选择模型
curl "https://api.tokenlab.sh/v1/models?recommended_for=video" \
-H "Authorization: Bearer sk-your-api-key"model 必须使用 TokenLab 返回的模型 ID,生成类型则通过 operation 和对应媒体字段选择。不要把某种操作名称当成模型 ID。
发送 reference_images、kling_elements、output_audio、duration、resolution 或 aspect_ratio 前,请确认所选模型支持这些字段。
创建视频
curl https://api.tokenlab.sh/v1/videos/generations \
-H "Authorization: Bearer sk-your-api-key" \
-H "Content-Type: application/json" \
-d '{
"model": "veo3.1",
"operation": "text-to-video",
"prompt": "一只猫在阳光明媚的花园中漫步的宁静电影镜头",
"resolution": "720p",
"duration": 4,
"aspect_ratio": "16:9"
}'媒体可以从互联网访问时,使用 https URL。临时 URL 必须保持有效,直到 TokenLab 完成任务创建。
修正被拒绝的参数
POST /v1/videos/generations 返回 400 时,param 指出被拒绝的字段,同时列出该字段在当前所选模型下接受的取值,下一次请求不必再猜:
| 字段 | 含义 |
|---|---|
allowed_durations | 模型支持的 duration 或 seconds 取值,单位为秒 |
allowed_resolutions | 模型详情里列出的 resolution 取值 |
supported_operations | 模型详情里列出的 operation 名称 |
recommended_request | 一条使用允许取值的请求;直接发送它,或换成同一列表里的其他取值 |
这些列表属于所选模型。请从错误正文或模型详情(GET /v1/models/{id})读取;其他模型的取值不适用。
例如,向一个支持 4、6、8 秒的模型发送 seconds: 20,返回的正文里 param 是 "duration",allowed_durations 是 ["4", "6", "8"],recommended_request 保留 prompt 并把 duration 设为 4。
如果该操作还需要只有你能提供的输入,例如 image-to-video 的图像,错误正文会省去 recommended_request,并在 required_selectors 与 hint 里说明缺少的输入。
operation 名称不合法时,请求在读取模型详情之前就被拒绝;同一个 supported_operations 列表说明应改发哪些名称。允许取值按操作划分,所以修正 duration 或 resolution 时请继续带上 operation。
模型专属字段
音频行为取决于所选模型和操作。没有音频开关,不代表视频必须无声;省略参数也不等于发送 false。
veo3.1、veo3.1-fast和veo3.1-lite始终生成音频。省略output_audio或传true;传false会被拒绝。wan-2.6和wan-2.7始终包含音频。省略output_audio或传true。wan-3.0和wan-3.0-prime同样始终包含音频,且没有音频开关。hailuo-h3原生生成音频,没有静音开关。不要添加模型详情未列出的音频开关。viduq3-pro和viduq3-turbo默认生成音频;需要无声输出时传output_audio: false(或audio: false)。Seedance 和 PixVerse 模型使用output_audio;请显式传入,不要依赖默认值。仅在当前操作列出该字段时使用。audio_url/audio_urls用于输入或参考音频,不是输出声音开关。视频编辑、动作迁移和风格转换可能保留输入音轨;保留原音不等于静音。
允许值及音频相关价格以模型详情为准。模型列出这些别名时,outputAudio、generate_audio 和布尔 audio 与 output_audio 同时出现,值必须一致。不要假定同系列各版本、各操作的声音控制相同。
- Seedance 2.0 的 4K、Fast/Mini 分辨率和多媒体参考输入见 Seedance 2.0 视频模型。
grok-imagine-video的 video-to-video 使用prompt和公网 HTTPS.mp4video_url;之前任务返回的 TokenLab.mp4结果 URL 也可使用。此操作不使用duration、resolution或aspect_ratio选项。
PixVerse 与 HappyHorse
| 模型 | 操作 | 输入 | 分辨率 | 时长 | 音频参数 |
|---|---|---|---|---|---|
pixverse-c1, pixverse-v6 | text-to-video, image-to-video, start-end-to-video, reference-to-video | prompt; image_url; start_image + end_image; reference_images | 360p, 540p, 720p, 1080p | 1 至 15 秒的整数 | output_audio |
pixverse-v5.6 | text-to-video, image-to-video, start-end-to-video, reference-to-video | 与 C1、V6 相同 | 360p, 540p, 720p, 1080p | 5、8 或 10 秒;1080p 支持 5 或 8 秒 | output_audio |
happyhorse-1.0 | text-to-video, image-to-video, reference-to-video, video-to-video | prompt; image_url; reference_images; video_url + reference_images | 720p, 1080p | 生成操作为 3 至 15 秒;视频转视频输出最长 15 秒 | 不要传入 output_audio |
happyhorse-1.1 | text-to-video, image-to-video, reference-to-video | prompt; image_url; reference_images | 720p, 1080p | 3 至 15 秒 | 不要传入 output_audio |
在 TokenLab 上,上述 PixVerse 模型不接受 operation=video-extension。
curl https://api.tokenlab.sh/v1/videos/generations \
-H "Authorization: Bearer sk-your-api-key" \
-H "Content-Type: application/json" \
-d '{
"model": "pixverse-v6",
"operation": "image-to-video",
"prompt": "A slow camera move through a neon-lit street",
"image_url": "https://example.com/start.jpg",
"resolution": "1080p",
"duration": 5,
"output_audio": true
}'获取生成结果
用创建响应中的 id 或 task_id 调用 GET /v1/tasks/{id},直到任务变为 completed 或 failed。
视频完成后,响应可能按模型和数量返回 video_url、video 或 videos。billing_transaction_id 用于核对费用,不是任务 ID。
视频结果 URL 是 TokenLab 媒体结果 URL,以文件类型结尾(例如 .mp4),有效期 30 天。media_retention.items 提供每项的保存状态和 expires_at;如果未能及时确定保存状态,响应可能省略 media_retention,URL 仍可使用。失败或进行中的任务,其视频 URL 字段为空。异步任务快照另有生命周期。参见数据保留。
常见问题
- 新代码不要使用按类型划分的状态路径(如
/v1/videos/generations/{id}),请调用GET /v1/tasks/{id}。 - 模型没有明确支持时,不要把首帧字段和参考图生成混在同一个请求中。
- 不要假设
duration描述输入参考视频的长度;它通常控制生成输出的长度。 POST /v1/videos/generations请带上Idempotency-Key。超时后用同一个键原样重发,即可拿到原来的任务。没有带键时,确认没有任务再重新提交。
API 参考
Hailuo H3-Max 可根据文本、首帧或首尾帧生成 5–15 秒的 480p 或 768p 视频,主打快速生成,适用于将镜头构想迅速转为短片。
{
"model": "hailuo-h3-max",
"operation": "text-to-video",
"prompt": "A slow camera move through a quiet garden",
"resolution": "768p",
"duration": 5,
"aspect_ratio": "16:9"
}