视频与素材
创建视频
提交视频生成任务
概述
视频生成是异步的。创建成功后会返回任务 id(与 task_id 相同)和 poll_url。用这个 ID 调用 GET /v1/tasks/{id},直到 status 变为 completed 或 failed,再读取 video_url。参见查询视频状态。
- 结果文件保存 30 天。需要更久保存时请自行下载;参见数据保留。
- 排队中的 Seedance 任务可通过取消任务取消。
- 任务被接受时可能预留费用,任务完成或失败后结算。参见计费与价格。
- 超时后要安全重试创建请求,请发送
Idempotency-Key请求头。
每个模型接受的操作和字段不同。GET /v1/models/{model}(获取模型)会按操作列出可用字段、分辨率、时长和宽高比。超出该列表的字段或取值会返回 400 并给出可用取值。请自行设置 duration、resolution、aspect_ratio 和 output_audio:省略时 TokenLab 使用该模型在当前操作下的默认值;没有匹配的默认值时请求返回 400,并指出需要设置的字段。
音频与媒体输入
音频行为取决于所选模型和操作。没有音频开关,不代表视频必须无声;省略参数也不等于发送 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 同时出现,值必须一致。不要假定同系列各版本、各操作的声音控制相同。
图片、视频和音频请使用公网可访问的 https URL,并在任务开始前保持有效。媒体 URL 最长 8,192 个字符。部分模型也接受内联 data: 图片 URL(每个字段最多 2,000,000 个字符);文件较大时 URL 更稳定。不要在同一请求中混用内联 base64 和远程 URL。
请求体
veo3.1视频模型 ID。用模型列表(recommended_for=video)查看当前视频模型,并显式传入所选模型。
PixVerse
- 模型:
pixverse-c1,pixverse-v6,pixverse-v5.6 - 操作:
text-to-video,image-to-video,start-end-to-video,reference-to-video - 音频参数:
output_audio
在 TokenLab 上,上述 PixVerse 模型不接受 operation=video-extension。
HappyHorse
- 模型:
happyhorse-1.0,happyhorse-1.1 - 操作:
text-to-video,image-to-video,reference-to-video;happyhorse-1.0还支持video-to-video - 音频参数: 不要传入
output_audio
要生成视频的文本描述,最多 10,000 个字符。大多数操作需要该字段;哪些操作不需要,以模型详情为准。
生成方式:text-to-video、image-to-video、reference-to-video、start-end-to-video、video-to-video、video-extension 或 motion-control。每个模型只支持其中一部分,其余返回 400 unsupported_operation。省略时 TokenLab 根据输入判断:带 extend_at 或 extend_times 的 task_id 为 video-extension,参考图或素材为 reference-to-video,end_image 为 start-end-to-video,视频输入为 video-to-video,图片输入(image、image_url、image_urls 或 start_image)为 image-to-video,其余为 text-to-video。建议明确填写,字段不匹配时能更早失败。
首帧图片的公网可访问 URL。Seedance 2.0 模型也可以传入 asset://asset-YYYYMMDDHHMMSS-xxxxx,将处于 ACTIVE 状态的 TokenLab 素材用作首帧。为获得最广的模型支持,建议使用 https URL。
以内联 data URL 形式提供的图片(例如 data:image/jpeg;base64,...)。只有部分模型接受;image_url 支持的模型更多。
列出该字段的模型所用的图片 URL。数量上限见 reference_images。
reference-to-video 的参考图,可以是 https URL 或 data URL。数量上限取决于模型:
seedance-2.0、seedance-2.0-fast和seedance-2.0-mini:图片参考合计最多 9 张,包含素材。超出返回400 too_many_seedance_reference_images。seedance-2.5:image_urls与reference_images合计最多 30 张图片。grok-imagine-video:最多 7 张,且duration最高为 10 秒。grok-imagine-video-1.5和grok-imagine-video-1.5-preview不接受参考图。- 其他模型:见模型详情。超出上限返回
400 too_many_items。
Seedance 2.0 模型也接受处于 ACTIVE 状态的 TokenLab 素材的 asset://asset-YYYYMMDDHHMMSS-xxxxx。模型选型、4K 边界和 Mini 说明请参考 Seedance 2.0 视频模型指南。对 grok-imagine-video,不要把参考图与 image_url 或 image 混用。
首帧图片。与 end_image 一起传入时为 start-end-to-video;不带 end_image 时为 image-to-video,在契约列出它的模型上与 image 作用相同。接受公网 URL 或 data URL;Seedance 2.0 模型也接受 asset://asset-YYYYMMDDHHMMSS-xxxxx。
start-end-to-video 的尾帧图片,接受的输入与 start_image 相同。
创建素材返回的 TokenLab Seedance 素材 ID。仅 Seedance 2.0 模型接受,其他模型返回 400 unsupported_seedance_material_asset_model。素材必须为 ACTIVE 且属于你的账号。该字段是通用参考输入;如需明确指定首帧、尾帧或参考图语义,请改为把 asset://<material_asset_id> 放入 start_image、end_image 或 reference_images。
最多 9 个 TokenLab Seedance 素材 ID。它们计入 Seedance 2.0 模型的 9 张图片参考上限。
普通图片 URL 会作为图片输入传递,不会创建可复用素材。可复用素材请通过素材 API 创建,再使用其 TokenLab ID 或 asset://asset-YYYYMMDDHHMMSS-xxxxx URI。如果显式素材返回 409 seedance_material_preparing,请查看返回的 inactive_asset_ids,待这些素材变为 ACTIVE 后重试。
源视频的公网可访问 URL,用于需要源视频的操作:video-to-video、video-extension 和 motion-control(限列出该字段的模型)。
列出该字段的模型所用的源视频或参考视频。seedance-2.5 的 video_url 与 video_urls 合计最多 10 段视频。其他模型见模型详情。
音频参考或音频驱动操作所用的公网音频 URL(限列出该字段的模型)。它是输入,不是输出声音开关。
列出该字段的模型所用的参考音频。seedance-2.5 的 audio_url 与 audio_urls 合计最多 10 段音频,并允许只有音频参考、没有提示词的请求。对 seedance-2.5,参考音频与参考视频合计最长 30 秒。
你的工作区中某个已有任务的 ID,用于列出该字段的模型的 video-extension。不属于你的工作区的任务返回 403 task_not_owned。
video-extension 从源视频的第几秒开始。grok-imagine-video 必填。
video-extension 要增加的秒数(限列出该字段的模型)。grok-imagine-video 取 6 或 10。
输出时长(秒)。可用取值取决于模型和操作,其他值返回 400 invalid_duration。Seedance 模型也接受 -1,表示让模型在其范围内自行选择,任务完成前会按保守方式预估费用。部分操作不接受时长,例如 motion-control 和 grok-imagine-video 的 video-to-video。
duration 的兼容别名。若两者同时传入,必须完全一致。
宽高比,例如 16:9、9:16、1:1、4:3、3:4、21:9,或 adaptive(Seedance)。可用取值取决于模型和操作,其他值返回 400 invalid_aspect_ratio。
输出分辨率,例如 480p、720p、1080p 或 4k。可用取值取决于模型和操作,部分模型还使用 360p、540p 或 768p。其他值返回 400 invalid_resolution。
仅用于列出该字段的操作。省略时遵循模型默认行为;只有模型允许时,false 才表示无声输出。参见上方音频说明和所选模型详情。
容器格式,mp4 或 mov,限列出该字段的模型,例如 seedance-2.5。未列出该字段的模型请省略。
同时以 last_frame_url 返回最后一帧。仅 Seedance 模型。
水印开关,限列出该字段的模型(Seedance 模型)。
希望在视频生成中避免的内容,最多 5,000 个字符,限列出该字段的模型。
用于可复现生成的随机种子,限列出该字段的模型。Seedance 2.0 模型接受 -1 表示随机种子;seedance-2.5 不接受该字段。
每秒帧数(1-120),限列出该字段的模型。
帧数,限列出该字段的模型。Seedance 模型不接受。
任务在队列中等待多久(秒)后过期,范围 3600 到 259200,用于 Seedance 模型。
任务优先级,范围 0 到 9,用于 Seedance 模型。不要与 service_tier=flex 组合使用。
default 在 Seedance 2.0 和 2.5 模型上按兼容 no-op 接受;这些模型会拒绝 flex。
终端用户安全标识(最多 128 个字符),用于 Seedance 模型。未传时,TokenLab 使用 user 的值。
模型生成时可使用的工具,用于 Seedance 2.0 和 2.5 模型。支持的工具为 {"type": "web_search"}。
终端用户的唯一标识符。对 Seedance,如果未传 safety_identifier,TokenLab 也会使用该值。
兼容字段
- 主要字段使用 snake_case:
aspect_ratio、output_audio和reference_images。 - 为了兼容已有调用,TokenLab 也接受
ratio、generate_audio、outputAudio、seconds和referenceImages。 - 如果同时传入主要字段及其别名,两者的值必须一致;不一致时返回
400,错误码为conflicting_audio_selector、conflicting_duration或conflicting_aspect_ratio。
Seedance 参数
Seedance 模型(seedance-2.0、seedance-2.0-fast、seedance-2.0-mini 和 seedance-2.5)使用上面的 TokenLab 字段,同时接受兼容别名 seconds、ratio 和 generate_audio。各版本的差异:
| Seedance 2.0 模型 | seedance-2.5 | |
|---|---|---|
| 分辨率 | seedance-2.0:480p、720p、1080p、4k。seedance-2.0-fast 和 seedance-2.0-mini:480p、720p | 480p、720p |
| 时长 | -1,4 到 15 秒 | -1,4 到 30 秒 |
| 宽高比 | 1:1、3:4、4:3、9:16、16:9、21:9、adaptive | 文生视频和参考图生视频相同。图生视频、首尾帧、视频编辑和视频扩展需用 adaptive;视频编辑还需 duration=-1 |
| 输出格式 | mp4 | mp4 或 mov |
seed | 接受 | 不接受 |
| 参考输入 | 图片参考 9 张,包含素材(仅这些模型接受素材) | 合计 30 张图片、10 段视频和 10 段音频 |
这些取值以模型详情为准。请显式传入 duration、resolution、aspect_ratio 和 output_audio,不要依赖默认值;模型的 recommended_request 给出了一个典型请求。
duration=-1 或 seconds=-1 表示让 Seedance 在模型范围内自动选择输出时长。TokenLab 会在任务完成前按保守方式预估费用,并在可获得完成任务 usage 时按实际结果结算。这些模型会拒绝 service_tier=flex 和 frames。
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,与 task_id 相同。
用于调用 GET /v1/tasks/{id} 查询的任务 ID。
该任务的状态地址 /v1/tasks/{id}。用你的 API Key 调用。
任务状态:pending、processing、completed、failed。新任务通常为 pending。
任务创建时的 Unix 时间戳。
使用的模型。
结算已完成时的 TokenLab 计费交易 ID,与任务 ID 不同。
视频 URL,仅在创建响应已包含结果时返回。通常从状态响应读取。
任务失败时的错误信息或结构化错误对象。
错误
| 状态与错误码 | 含义 |
|---|---|
400 invalid_request | 字段格式不对、超出范围或缺失。error.param 指明字段。出现“Set aspect_ratio explicitly”之类的消息,表示该省略字段在本次请求下没有默认值。 |
400 unsupported_operation、unsupported_parameter、invalid_resolution、invalid_duration、invalid_aspect_ratio、invalid_parameter_value、too_many_items、prompt_too_long | 请求不符合模型在该操作下接受的内容。错误通常会列出可用取值。 |
400 invalid_parameter | 某个输入与操作不匹配,例如对 text-to-video 传了图片。 |
400 conflicting_audio_selector、conflicting_duration、conflicting_aspect_ratio | 别名与主要字段取值不一致。 |
400 unpriceable_selection | 所选组合没有价格。请调整 resolution、duration、aspect_ratio 或音频设置。 |
400 too_many_seedance_reference_images、unsupported_seedance_material_asset_model | Seedance 2.0 模型的图片参考过多,或把素材发给了其他模型。 |
402 | 余额不足。 |
403 task_not_owned | task_id 属于其他工作区。 |
409 seedance_material_preparing、seedance_material_route_unavailable | 素材尚未 ACTIVE,或所选模型无法使用所提供的素材。 |
429 | 超出速率限制。参见速率限制。 |
请求
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,
"resolution": "720p",
"aspect_ratio": "16:9"
}'响应
{
"id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"task_id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"poll_url": "/v1/tasks/ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"status": "pending",
"model": "veo3.1",
"created": 1706000000
}图生视频
import requests
response = requests.post(
"https://api.tokenlab.sh/v1/videos/generations",
headers={"Authorization": "Bearer sk-your-api-key"},
json={
"model": "hailuo-2.3",
"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"
}
)参考图生视频
当模型支持专门的参考条件控制时,请使用 operation=reference-to-video。图片参考放在 reference_images;支持参考视频和参考音频的模型分别使用 video_urls 与 audio_urls。duration 只控制生成输出时长,不限制参考视频输入的时长。各模型的数量上限见上方 reference_images。
import requests
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, palette, and framing while adding subtle natural motion.",
"operation": "reference-to-video",
"reference_images": [
"https://example.com/ref-a.jpg",
"https://example.com/ref-b.jpg"
],
"duration": 8,
"resolution": "720p",
"aspect_ratio": "9:16"
}
)首尾帧控制
使用 start_image 和 end_image 控制首帧和尾帧:
import requests
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"
}
)视频转视频
当模型接受已有视频作为主要输入时,使用 operation=video-to-video。对 grok-imagine-video,请在 video_url 中传公网 HTTPS .mp4 URL,并传入编辑用的 prompt,同时省略 resolution、duration 和 aspect_ratio。
import requests
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=video-extension 接着已有结果继续生成。传入你的工作区中某个任务的 task_id 和 prompt;其余字段取决于模型。grok-imagine-video 还需要 extend_at,extend_times 取 6 或 10。veo3.1 和 veo3.1-fast 接受 task_id 和 prompt。Seedance 模型在该操作下列出 video_url、video_urls 和 task_id。
动作控制
当模型需要主体图片和动作参考视频时,使用 operation=motion-control。传入 image_url 和 video_url;resolution 必填。
import requests
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 identity stable while following the motion reference.",
"image_url": "https://example.com/subject.png",
"video_url": "https://example.com/motion.mp4",
"resolution": "720p"
}
)模型发现
公开视频模型清单和支持的操作会随时间变化。接入特定模型的流程前,请先用模型 API 确认当前支持情况:
curl "https://api.tokenlab.sh/v1/models?recommended_for=video"
curl "https://api.tokenlab.sh/v1/models/veo3.1"依赖模型特有的操作或字段前,请先阅读模型详情响应。video-extension 和 motion-control 等操作因模型而异;请以模型详情为准,不要依赖本页的静态示例。
授权
BearerAuth API Key 身份验证。在 Dashboard > API > API Keys 中创建或管理 API Key。
位置: header
请求头
单次请求的交付策略。覆盖 API 密钥和 Workspace 的默认设置。自动优先尝试 TokenLab Verified,并在输出、请求接受或持久资源创建之前,可能会切换一次至仅限 Official。
可选值
- "auto"
- "verified"
- "official"
可选键,用于确保创建请求可安全重试。请为每个任务发送一个新的唯一值(如 UUID)。使用相同键和相同请求体的重试将返回原始创建请求的结果(通常是原始任务),而不会创建、分发或扣除第二个任务。若使用已接受的键但请求体不同,则会返回 409 错误。超过 255 个字符的键将被忽略,此时该请求不具备幂等性保护。请参阅 安全地使用幂等键进行重试。
1 <= length <= 255请求体
application/json
响应
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json