视频与素材

创建视频

提交视频生成任务

POST
/v1/videos/generations

概述

视频生成是异步的。创建成功后会返回任务 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。

请求体

modelstring默认值: 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
promptstring

要生成视频的文本描述,最多 10,000 个字符。大多数操作需要该字段;哪些操作不需要,以模型详情为准。

operationstring

生成方式: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。建议明确填写,字段不匹配时能更早失败。

image_urlstring

首帧图片的公网可访问 URL。Seedance 2.0 模型也可以传入 asset://asset-YYYYMMDDHHMMSS-xxxxx,将处于 ACTIVE 状态的 TokenLab 素材用作首帧。为获得最广的模型支持,建议使用 https URL。

imagestring

以内联 data URL 形式提供的图片(例如 data:image/jpeg;base64,...)。只有部分模型接受;image_url 支持的模型更多。

image_urlsarray

列出该字段的模型所用的图片 URL。数量上限见 reference_images。

reference_imagesarray

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 混用。

start_imagestring

首帧图片。与 end_image 一起传入时为 start-end-to-video;不带 end_image 时为 image-to-video,在契约列出它的模型上与 image 作用相同。接受公网 URL 或 data URL;Seedance 2.0 模型也接受 asset://asset-YYYYMMDDHHMMSS-xxxxx。

end_imagestring

start-end-to-video 的尾帧图片,接受的输入与 start_image 相同。

material_asset_idstring

创建素材返回的 TokenLab Seedance 素材 ID。仅 Seedance 2.0 模型接受,其他模型返回 400 unsupported_seedance_material_asset_model。素材必须为 ACTIVE 且属于你的账号。该字段是通用参考输入;如需明确指定首帧、尾帧或参考图语义,请改为把 asset://<material_asset_id> 放入 start_image、end_image 或 reference_images。

material_asset_idsarray

最多 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 后重试。

video_urlstring

源视频的公网可访问 URL,用于需要源视频的操作:video-to-video、video-extension 和 motion-control(限列出该字段的模型)。

video_urlsarray

列出该字段的模型所用的源视频或参考视频。seedance-2.5 的 video_url 与 video_urls 合计最多 10 段视频。其他模型见模型详情。

audio_urlstring

音频参考或音频驱动操作所用的公网音频 URL(限列出该字段的模型)。它是输入,不是输出声音开关。

audio_urlsarray

列出该字段的模型所用的参考音频。seedance-2.5 的 audio_url 与 audio_urls 合计最多 10 段音频,并允许只有音频参考、没有提示词的请求。对 seedance-2.5,参考音频与参考视频合计最长 30 秒。

task_idstring

你的工作区中某个已有任务的 ID,用于列出该字段的模型的 video-extension。不属于你的工作区的任务返回 403 task_not_owned。

extend_atinteger

video-extension 从源视频的第几秒开始。grok-imagine-video 必填。

extend_timesstring

video-extension 要增加的秒数(限列出该字段的模型)。grok-imagine-video 取 6 或 10。

durationinteger

输出时长(秒)。可用取值取决于模型和操作,其他值返回 400 invalid_duration。Seedance 模型也接受 -1,表示让模型在其范围内自行选择,任务完成前会按保守方式预估费用。部分操作不接受时长,例如 motion-control 和 grok-imagine-video 的 video-to-video。

secondsinteger

duration 的兼容别名。若两者同时传入,必须完全一致。

aspect_ratiostring

宽高比,例如 16:9、9:16、1:1、4:3、3:4、21:9,或 adaptive(Seedance)。可用取值取决于模型和操作,其他值返回 400 invalid_aspect_ratio。

resolutionstring

输出分辨率,例如 480p、720p、1080p 或 4k。可用取值取决于模型和操作,部分模型还使用 360p、540p 或 768p。其他值返回 400 invalid_resolution。

output_audioboolean

仅用于列出该字段的操作。省略时遵循模型默认行为;只有模型允许时,false 才表示无声输出。参见上方音频说明和所选模型详情。

output_formatstring

容器格式,mp4 或 mov,限列出该字段的模型,例如 seedance-2.5。未列出该字段的模型请省略。

return_last_frameboolean

同时以 last_frame_url 返回最后一帧。仅 Seedance 模型。

watermarkboolean

水印开关,限列出该字段的模型(Seedance 模型)。

negative_promptstring

希望在视频生成中避免的内容,最多 5,000 个字符,限列出该字段的模型。

seedinteger

用于可复现生成的随机种子,限列出该字段的模型。Seedance 2.0 模型接受 -1 表示随机种子;seedance-2.5 不接受该字段。

fpsinteger

每秒帧数(1-120),限列出该字段的模型。

framesinteger

帧数,限列出该字段的模型。Seedance 模型不接受。

execution_expires_afterinteger

任务在队列中等待多久(秒)后过期,范围 3600 到 259200,用于 Seedance 模型。

priorityinteger

任务优先级,范围 0 到 9,用于 Seedance 模型。不要与 service_tier=flex 组合使用。

service_tierstring

default 在 Seedance 2.0 和 2.5 模型上按兼容 no-op 接受;这些模型会拒绝 flex。

safety_identifierstring

终端用户安全标识(最多 128 个字符),用于 Seedance 模型。未传时,TokenLab 使用 user 的值。

toolsarray

模型生成时可使用的工具,用于 Seedance 2.0 和 2.5 模型。支持的工具为 {"type": "web_search"}。

userstring

终端用户的唯一标识符。对 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、720p480p、720p
时长-1,4 到 15 秒-1,4 到 30 秒
宽高比1:1、3:4、4:3、9:16、16:9、21:9、adaptive文生视频和参考图生视频相同。图生视频、首尾帧、视频编辑和视频扩展需用 adaptive;视频编辑还需 duration=-1
输出格式mp4mp4 或 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
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
  }'

响应

结果、错误、时间戳和模型字段仅在任务提供时返回。

idstring

任务 ID,与 task_id 相同。

task_idstring

用于调用 GET /v1/tasks/{id} 查询的任务 ID。

poll_urlstring

该任务的状态地址 /v1/tasks/{id}。用你的 API Key 调用。

statusstring

任务状态:pending、processing、completed、failed。新任务通常为 pending。

createdinteger

任务创建时的 Unix 时间戳。

modelstring

使用的模型。

billing_transaction_idstring

结算已完成时的 TokenLab 计费交易 ID,与任务 ID 不同。

video_urlstring

视频 URL,仅在创建响应已包含结果时返回。通常从状态响应读取。

errorstring | object

任务失败时的错误信息或结构化错误对象。

错误

状态与错误码含义
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_modelSeedance 2.0 模型的图片参考过多,或把素材发给了其他模型。
402余额不足。
403 task_not_ownedtask_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"
  }'

响应

Response
{
  "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
AuthorizationBearer <token>

API Key 身份验证。在 Dashboard > API > API Keys 中创建或管理 API Key。

位置: header

请求头

X-TokenLab-Delivery-Policy?string

单次请求的交付策略。覆盖 API 密钥和 Workspace 的默认设置。自动优先尝试 TokenLab Verified,并在输出、请求接受或持久资源创建之前,可能会切换一次至仅限 Official。

可选值

  • "auto"
  • "verified"
  • "official"
Idempotency-Key?string

可选键,用于确保创建请求可安全重试。请为每个任务发送一个新的唯一值(如 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