TokenLab
Lấy khóa API
Tài liệuTham chiếu APITích hợp

Video & tư liệu

Tạo video

Tạo một tác vụ sinh video

POST
/v1/videos/generations

Tổng quan

Việc sinh video là bất đồng bộ. Bạn gửi một yêu cầu, nhận task_id và poll_url, rồi kiểm tra trạng thái định kỳ cho tới khi có kết quả cuối cùng.

Hành vi polling

Để việc kiểm tra trạng thái đáng tin cậy nhất, hãy dùng chính xác poll_url được trả về từ phản hồi tạo tác vụ.

Nếu phản hồi tạo trả về poll_url, hãy gọi đúng URL đó. Khi nó trỏ tới /v1/tasks/{id}, hãy xem đó là endpoint trạng thái cố định chuẩn.

Hành vi mô hình và phương tiện

Hành vi âm thanh phụ thuộc vào mô hình và thao tác. Video vẫn có thể có tiếng dù không cung cấp công tắc âm thanh. Bỏ qua tham số khác với gửi false.

  • veo3.1 và veo3.1-fast luôn tạo âm thanh theo hợp đồng Gemini API. Tạo video bằng wan-2.6 và wan-2.7 cũng không hỗ trợ tắt tiếng. Bỏ qua output_audio hoặc dùng true nếu chi tiết mô hình cho phép.
  • hailuo-h3 và các mô hình video Grok tạo âm thanh gốc. Không thêm công tắc không được liệt kê trong chi tiết mô hình.
  • Seedance 1.5/2.x và viduq3-pro / viduq3-turbo bật âm thanh mặc định và hỗ trợ đầu ra im lặng. PixVerse C1/V5.6/V6 tắt âm thanh mặc định. Chỉ dùng output_audio cho thao tác có khai báo; Vidu cũng chấp nhận trường boolean audio đã khai báo.
  • audio_url / audio_urls cung cấp âm thanh đầu vào hoặc tham chiếu, không phải công tắc đầu ra. Chỉnh sửa video, chuyển động và phong cách có thể giữ lại âm thanh nguồn. Giữ âm thanh gốc không có nghĩa là tắt tiếng.

Xem chi tiết mô hình để biết giá trị hợp lệ và giá âm thanh. Các bí danh được hỗ trợ outputAudio, generate_audio và boolean audio phải khớp với output_audio khi dùng cùng nhau. Mỗi phiên bản và thao tác có thể có điều khiển khác nhau.

Trong môi trường vận hành, nên ưu tiên URL https công khai cho ảnh, video và âm thanh. Các model tương thích vẫn chấp nhận URL data:, nhưng payload base64 lớn sẽ khó retry, kiểm tra và debug hơn.

Phần thân yêu cầu

modelstringmặc định: veo3.1

ID model video. Dùng model ID hiển thị trong TokenLab như veo3.1, wan-2.7, happyhorse-1.0, viduq3, pixverse-v6, hoặc kling-3.0-video; chọn text-to-video, image-to-video, reference-to-video hoặc biến thể khác bằng operation. Xem hướng dẫn video và Models API.

PixVerse

  • Mô hình: pixverse-c1, pixverse-v6, pixverse-v5.6
  • Thao tác: text-to-video, image-to-video, start-end-to-video, reference-to-video
  • Bộ chọn âm thanh: output_audio, mặc định false

Trên TokenLab, các mô hình PixVerse ở trên không chấp nhận operation=video-extension.

HappyHorse

  • Mô hình: happyhorse-1.0
  • Thao tác: text-to-video, image-to-video, reference-to-video, video-to-video
  • Bộ chọn âm thanh: Không gửi output_audio
promptstring

Mô tả văn bản của video cần tạo. Trường này là bắt buộc với hầu hết model video công khai.

operationstring

Tác vụ video cần chạy. Các tác vụ hiện được hỗ trợ gồm text-to-video, image-to-video, reference-to-video, start-end-to-video, video-to-video, video-extension, audio-to-video và motion-control. TokenLab có thể suy luận tác vụ từ dữ liệu đầu vào, nhưng với traffic vận hành bạn vẫn nên truyền operation một cách tường minh.

image_urlstring

URL công khai của ảnh đầu vào cho luồng image-to-video. Để có độ tương thích rộng nhất giữa các model, nên ưu tiên image_url.

imagestring

Ảnh inline dưới dạng URL data: (ví dụ: data:image/jpeg;base64,...). Các model tương thích có hỗ trợ, nhưng trong môi trường vận hành thì image_url thường ổn định hơn.

reference_imagesarray

Ảnh tham chiếu cho các luồng có conditioning chuyên biệt. Số lượng hỗ trợ phụ thuộc vào model. Với seedance-2.0 và seedance-2.0-fast, TokenLab hiện hỗ trợ tối đa 9 ảnh tham chiếu, cùng thêm tối đa 3 video tham chiếu và 3 audio tham chiếu. Để chọn mô hình, hiểu ranh giới 4K và ghi chú Mini, xem hướng dẫn mô hình video Seedance 2.0. Nên ưu tiên URL công khai https; các model tương thích cũng chấp nhận URL data:. Với grok-imagine-video, reference-to-video chấp nhận tối đa 7 tham chiếu ảnh và duration tối đa là 10 giây. grok-imagine-video-1.5-preview chỉ hỗ trợ image-to-video và không nhận ảnh tham chiếu.

material_asset_idstring

ID material Seedance của TokenLab được trả về bởi Tạo Tài nguyên Vật liệu. Dùng sau khi material là ACTIVE với các model Seedance có thể dùng thư viện material TokenLab.

material_asset_idsarray

Nhiều ID material Seedance của TokenLab. Chúng dùng chung giới hạn ảnh tham chiếu Seedance với reference_images; model đã chọn phải có thể dùng thư viện material TokenLab.

URL ảnh thông thường được dùng làm đầu vào và không tự tạo material tái sử dụng. Hãy tạo material qua API material rồi dùng ID TokenLab hoặc URI asset://asset-YYYYMMDDHHMMSS-xxxxx. Nếu material chỉ định trả về 409 seedance_material_preparing, hãy kiểm tra inactive_asset_ids và thử lại khi chúng chuyển sang ACTIVE.

reference_image_typestring

Trường tùy chọn cho những model phân biệt ảnh tham chiếu kiểu asset và style.

kling_elementsarray

Chỉ dùng kling_elements khi chi tiết công khai hiện tại của model có trường này. Gửi ảnh và 1–3 phần tử gồm name, description tùy chọn, 2–4 element_input_urls; tham chiếu bằng @name trong prompt. Không kết hợp với output_audio=true.

video_urlstring

URL công khai của video nguồn. Bắt buộc với các luồng video-to-video dựa trên URL video và với motion-control; một số luồng phái sinh dùng task_id thay thế.

video_urlsarray

Đầu vào video tham chiếu bổ sung cho các model hỗ trợ conditioning tham chiếu đa phương thức. Số lượng hỗ trợ phụ thuộc vào model. Với seedance-2.0 và seedance-2.0-fast, TokenLab hiện hỗ trợ tối đa 3 video tham chiếu.

audio_urlstring

URL âm thanh công khai cho thao tác điều khiển bằng âm thanh hoặc tham chiếu âm thanh được mô hình hỗ trợ.

audio_urlsarray

Đầu vào audio tham chiếu bổ sung cho các model hỗ trợ conditioning tham chiếu đa phương thức. Số lượng hỗ trợ phụ thuộc vào model. Với seedance-2.0 và seedance-2.0-fast, TokenLab hiện hỗ trợ tối đa 3 audio tham chiếu.

task_idstring

Định danh tác vụ dùng cho một số luồng tiếp tục, mở rộng hoặc phái sinh.

extend_atinteger

Vị trí bắt đầu mở rộng theo đặc thù từng model trong một số luồng video-extension.

extend_timesstring

Hệ số hoặc số lần lặp theo đặc thù từng model trong một số luồng video-extension.

durationinteger

Thời lượng video đầu ra được tạo, tính bằng giây. Với các model Seedance 1.5/2.0, nếu bỏ qua trường này thì dùng 5; gửi -1 cho phép model chọn trong phạm vi hỗ trợ, và chi phí được ước tính thận trọng cho đến khi tác vụ hoàn tất.

secondsinteger

Alias tương thích của duration. Nếu gửi cả seconds và duration, hai giá trị phải giống nhau. Với Seedance, seconds=-1 có cùng ý nghĩa thời lượng tự động như duration=-1.

aspect_ratiostring

Tỉ lệ khung hình chuẩn, ví dụ adaptive, 16:9, 9:16, 1:1, 4:3, 3:4 hoặc 21:9. Seedance mặc định dùng adaptive khi bỏ qua.

resolutionstring

Độ phân giải đầu ra phụ thuộc vào model. Seedance mặc định dùng 720p; seedance-2.0 hỗ trợ 480p, 720p, 1080p và 4k, còn seedance-2.0-fast và seedance-2.0-mini bị giới hạn ở 480p và 720p.

output_audioboolean

Bộ chọn âm thanh cho thao tác có khai báo trường này. Bỏ qua sẽ dùng mặc định của mô hình; false chỉ yêu cầu đầu ra im lặng khi được phép. Xem giải thích ở trên và chi tiết mô hình.

draftboolean

Cờ workflow Draft của Seedance 1.5 Pro. Dùng draft=true với các model Seedance hỗ trợ tác vụ draft. Không gửi cùng draft_task_id.

draft_task_idstring

ID tác vụ draft Seedance 1.5 Pro dùng để nâng lên bản final. Gửi ID tác vụ draft trước đó để tạo video cuối cùng; đây không phải field video chung.

ratiostring

Alias tương thích của aspect_ratio. Nếu gửi cả ratio và aspect_ratio, hai giá trị phải giống nhau.

generate_audioboolean

Alias tương thích của output_audio. Nếu generate_audio, output_audio và outputAudio cùng xuất hiện, tất cả giá trị phải khớp.

execution_expires_afterinteger

Thời gian hết hạn thực thi tùy chọn, tính bằng giây, cho các model video tương thích. Seedance mặc định dùng 172800 giây khi bỏ qua.

priorityinteger

Mức ưu tiên tác vụ tùy chọn từ 0 đến 9 cho các model video tương thích. Không kết hợp priority với service_tier=flex.

safety_identifierstring

Định danh an toàn người dùng cuối tùy chọn cho các model video tương thích. Nếu bỏ qua với Seedance, TokenLab dùng user khi có.

service_tierstring

default được chấp nhận như no-op tương thích cho các model Seedance 2.0. flex chỉ được dùng khi model đã chọn hỗ trợ.

framesinteger

Số frame tùy chọn cho các model video tương thích. Model Seedance 2.0 và Seedance 1.5 Pro không hỗ trợ trường này.

camera_fixedboolean

Selector camera cố định tùy chọn cho các model video tương thích. Model Seedance 2.0 không hỗ trợ trường này.

fpsinteger

Số khung hình trên giây (1-120). Chỉ có tác dụng ở những model công khai hỗ trợ điều khiển FPS.

negative_promptstring

Những gì bạn muốn tránh trong video được tạo ra.

seedinteger

Seed ngẫu nhiên để tạo có thể tái lập. Seedance dùng -1 làm seed ngẫu nhiên khi bỏ qua.

cfg_scalenumber

Mức bám theo prompt (0-20) ở những model hỗ trợ kiểu điều khiển này.

motion_strengthnumber

Cường độ chuyển động (0-1) ở những model hỗ trợ trường này.

start_imagestring

URL ảnh khung hình đầu tiên, hoặc đầu vào ảnh tương thích, cho start-end-to-video.

end_imagestring

URL ảnh khung hình cuối cùng, hoặc đầu vào ảnh tương thích, cho start-end-to-video.

sizestring

Bậc kích thước theo đặc thù model cho các model video tương thích.

watermarkboolean

Công tắc watermark tùy chọn cho các model có hỗ trợ. Seedance mặc định dùng false khi bỏ qua.

effect_typestring

Bộ chọn hiệu ứng theo đặc thù model trong một số luồng chỉnh sửa hoặc hiệu ứng chuyên biệt.

userstring

Định danh duy nhất của người dùng cuối. Với Seedance, TokenLab cũng dùng giá trị này làm safety_identifier khi trường đó bị bỏ qua.

Ghi chú tương thích

  • Các trường công khai chuẩn dùng snake_case: reference_images, reference_image_type, và output_audio.
  • Các trường công khai chuẩn tiếp tục dùng snake_case: aspect_ratio, output_audio, reference_images và reference_image_type.
  • Để tương thích, TokenLab cũng chấp nhận ratio, generate_audio, outputAudio, seconds, referenceImages và referenceImageType.
  • Nếu trường chuẩn và trường alias cùng được gửi, giá trị phải khớp; alias xung đột sẽ bị từ chối trước khi tạo tác vụ.

Thực hành tốt cho đầu vào media

  • Với image_url, reference_images, video_url, và audio_url, hãy ưu tiên URL https công khai.
  • Nếu có thể, tránh trộn base64 inline và URL từ xa trong cùng một yêu cầu.
  • Hãy giữ URL media từ xa hợp lệ đủ lâu để bao phủ quá trình retry và tạo task bất đồng bộ.

Tham số Seedance

Với các model Seedance 1.5/2.0, endpoint thống nhất dùng tên trường TokenLab và cũng chấp nhận alias tương thích seconds, ratio và generate_audio. Khi bỏ qua selector Seedance, các giá trị mặc định là: duration=5, resolution=720p, aspect_ratio=adaptive, output_audio=true, watermark=false, return_last_frame=false, execution_expires_after=172800, priority=0 và seed=-1.

duration=-1 hoặc seconds=-1 cho phép Seedance chọn thời lượng đầu ra trong phạm vi model hỗ trợ. TokenLab ước tính chi phí thận trọng trước khi tác vụ hoàn tất, rồi quyết toán theo usage của tác vụ đã hoàn tất khi có. service_tier=default được chấp nhận như no-op tương thích cho Seedance 2.0; service_tier=flex, frames và camera_fixed bị từ chối khi model đã chọn không hỗ trợ.

Ví dụ 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
  }'

Phản hồi

Các trường kết quả, lỗi, thời gian và model được trả về khi tác vụ cung cấp chúng.

idstring

Mã định danh chuẩn của tác vụ bất đồng bộ. Khi cả id và task_id cùng xuất hiện, hãy xem chúng là cùng một tác vụ.

task_idstring

Định danh tác vụ duy nhất để kiểm tra trạng thái.

poll_urlstring

URL kiểm tra trạng thái được khuyến nghị cho tác vụ này. Hãy dùng đúng đường dẫn này khi kiểm tra trạng thái.

billing_transaction_idstring

ID giao dịch billing của TokenLab khi việc settlement đã hoàn tất. Đây là mã giao dịch dùng cho dashboard/đối soát và tách biệt với id / task_id bất đồng bộ.

statusstring

Trạng thái tác vụ: pending, processing, completed, failed.

createdinteger

Dấu thời gian Unix khi tác vụ được tạo.

modelstring

Model được sử dụng.

videoobject

Payload video đơn với url, duration, width, và height khi có.

videosarray

Nhiều payload video khi tác vụ tạo trả về hơn một kết quả.

errorstring | object

Thông báo lỗi (nếu thất bại).

Yêu cầu

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": "veo3.1",
    "prompt": "A cat walking through a garden, cinematic lighting",
    "operation": "text-to-video",
    "duration": 4,
    "aspect_ratio": "16:9"
  }'

Phản hồi

Response
{
  "id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "task_id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "poll_url": "/v1/tasks/ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "status": "pending",
  "model": "veo3.1",
  "created": 1706000000
}

Image sang video

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"
    }
)

Thành phần Kling 3.0

Chỉ dùng kling_elements khi chi tiết công khai hiện tại của model có trường này. Gửi ảnh và 1–3 phần tử gồm name, description tùy chọn, 2–4 element_input_urls; tham chiếu bằng @name trong prompt. Không kết hợp với output_audio=true.

Ảnh tham chiếu sang video

Hãy dùng operation=reference-to-video khi model hỗ trợ conditioning tham chiếu chuyên biệt. Trong chi tiết model của TokenLab, ảnh tham chiếu dùng reference_images, còn video và audio tham chiếu đa phương thức dùng video_urls và audio_urls. Với seedance-2.0 và seedance-2.0-fast, TokenLab hiện hỗ trợ tối đa 9 ảnh tham chiếu, cùng thêm tối đa 3 video tham chiếu và 3 audio tham chiếu. Để chọn mô hình, hiểu ranh giới 4K và ghi chú Mini, xem hướng dẫn mô hình video Seedance 2.0. duration chỉ điều khiển độ dài đầu ra được tạo; nó không đặt ra giới hạn riêng cho thời lượng video tham chiếu đầu vào. Với grok-imagine-video, reference-to-video chấp nhận tối đa 7 tham chiếu ảnh (reference_images hoặc image_urls) và duration tối đa là 10 giây. Không kết hợp ảnh tham chiếu với đầu vào khung đầu image_url / image. grok-imagine-video-1.5-preview chỉ hỗ trợ image-to-video.

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"
        ],
        "reference_image_type": "asset",
        "duration": 8,
        "resolution": "720p",
        "aspect_ratio": "9:16"
    }
)

Điều khiển khung đầu và cuối

Hãy dùng start_image và end_image để kiểm soát khung hình đầu tiên và cuối cùng.

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"
    }
)

Video sang video

Với video-to-video của grok-imagine-video, hãy gửi URL HTTPS công khai dạng .mp4 trong video_url. Bạn có thể đặt resolution là 480p hoặc 720p; luồng chỉnh sửa này không nhận duration và aspect_ratio.

Nếu model nhận một video có sẵn làm đầu vào chính, hãy dùng 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."
    }
)

Điều khiển chuyển động

Nếu model cần cả ảnh chủ thể lẫn video tham chiếu chuyển động, hãy dùng operation=motion-control. TokenLab sẽ chuẩn hóa dạng công khai image_url + video_url về định dạng request mà model yêu cầu.

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"
    }
)

Khám phá model

Inventory video công khai và các thao tác được hỗ trợ thay đổi theo thời gian. Hãy dùng Models API làm nguồn sự thật trước khi tích hợp một luồng đặc thù theo model:

curl "https://api.tokenlab.sh/v1/models?recommended_for=video"

curl "https://api.tokenlab.sh/v1/models/veo3.1"

Đọc tokenlab.capabilities và tokenlab.supported_operations trong response chi tiết model. Các thao tác như audio-to-video và video-extension phụ thuộc từng model; hãy xác nhận trạng thái hiện tại ở đó thay vì dựa vào ví dụ tĩnh trên trang này.

Xác thực

BearerAuth
AuthorizationBearer <token>

Xác thực bằng Khóa API. Tạo hoặc quản lý khóa API trong Dashboard > API > API Keys.

Vị trí: header

Header

X-TokenLab-Delivery-Policy?string

Chính sách phân phối theo yêu cầu. Ghi đè các mặc định của API key và Workspace. Tự động thử TokenLab Verified trước và có thể chuyển đổi một lần sang Official chỉ trước khi xuất, chấp nhận yêu cầu hoặc tạo tài nguyên cố định.

Giá trị hợp lệ

  • "auto"
  • "verified"
  • "official"

Nội dung yêu cầu

application/json

Phản hồi

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

Lấy Trạng thái Nhạc

Trước

Tạo tác vụ (Tương thích Volc)

Tiếp