Chuyển đến nội dung chính

​
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

Đầu ra âm thanh phụ thuộc vào model. Trong TokenLab, các request Veo 3 và Seedance mặc định bật âm thanh khi bỏ qua output_audio. Khi model hỗ trợ điều khiển âm thanh, dùng output_audio để bật hoặc tắt rõ ràng. Các alias outputAudio và generate_audio được chấp nhận để tương thích và phải khớp với output_audio khi gửi nhiều hơn một trường. 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

​
model
string
mặ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
​
prompt
string
bắt buộc
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.
​
operation
string
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_url
string
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.
​
image
string
Ả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_images
array
Ả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_id
string
ID material Seedance của TokenLab được trả về bởi Create Material Asset hoặc luồng chuẩn bị hình ảnh tự động. Dùng sau khi material là ACTIVE với các model Seedance có thể dùng thư viện material TokenLab.
​
material_asset_ids
array
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.
Khi model Seedance đã chọn có thể dùng thư viện material của TokenLab, TokenLab chuẩn bị các field hình ảnh (image, image_url, image_urls, reference_images, start_image, end_image) thành material có thể tái sử dụng trước khi tạo video. Nếu chưa hoàn tất trong 60 giây, API trả về 409 seedance_material_preparing với auto_material_asset_ids; hãy thử lại sau khi các material này chuyển sang ACTIVE. Nếu model đã chọn không thể dùng thư viện material, input hình ảnh thông thường tiếp tục đi theo luồng hình ảnh thông thường và ID material tường minh sẽ trả về lỗi khả dụng material.
​
reference_image_type
string
Trường tùy chọn cho những model phân biệt ảnh tham chiếu kiểu asset và style.
​
kling_elements
array
Định nghĩa tham chiếu phần tử Kling 3.0. Chỉ hỗ trợ với kling-3.0-video cho request có điều kiện ảnh. Khai báo 1-3 phần tử; mỗi phần tử có name, description tùy chọn và element_input_urls gồm 2-4 URL ảnh. Tham chiếu phần tử trong prompt bằng @name. Không kết hợp kling_elements với output_audio=true; hãy bỏ output_audio hoặc đặt thành false khi dùng tham chiếu phần tử.
​
video_url
string
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_urls
array
Đầ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_url
string
URL công khai của âm thanh cho các model hỗ trợ audio-to-video.
​
audio_urls
array
Đầ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_id
string
Đị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_at
integer
Vị trí bắt đầu mở rộng theo đặc thù từng model trong một số luồng video-extension.
​
extend_times
string
Hệ số hoặc số lần lặp theo đặc thù từng model trong một số luồng video-extension.
​
duration
integer
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.
​
seconds
integer
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_ratio
string
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.
​
resolution
string
Độ 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_audio
boolean
Công tắc đầu ra âm thanh chuẩn phụ thuộc vào model. Veo 3 và Seedance mặc định là true khi bỏ qua. kling-3.0-video chấp nhận selector này cho request không dùng tham chiếu phần tử và mặc định tạo đầu ra không tiếng khi bỏ qua. Không kết hợp output_audio=true với kling_elements.
​
draft
boolean
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_id
string
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.
​
ratio
string
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_audio
boolean
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_after
integer
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.
​
priority
integer
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_identifier
string
Đị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_tier
string
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ợ.
​
frames
integer
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_fixed
boolean
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.
​
fps
integer
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_prompt
string
Những gì bạn muốn tránh trong video được tạo ra.
​
seed
integer
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_scale
number
Mức bám theo prompt (0-20) ở những model hỗ trợ kiểu điều khiển này.
​
motion_strength
number
Cường độ chuyển động (0-1) ở những model hỗ trợ trường này.
​
start_image
string
URL ảnh khung hình đầu tiên, hoặc đầu vào ảnh tương thích, cho start-end-to-video.
​
end_image
string
URL ảnh khung hình cuối cùng, hoặc đầu vào ảnh tương thích, cho start-end-to-video.
​
size
string
Bậc kích thước theo đặc thù model cho các model video tương thích.
​
watermark
boolean
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_type
string
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.
​
user
string
Đị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.0",
    "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

​
id
string
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_id
string
Định danh tác vụ duy nhất để kiểm tra trạng thái.
​
poll_url
string
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_id
string
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ộ.
​
status
string
Trạng thái ban đầu: pending.
​
created
integer
Dấu thời gian Unix khi tác vụ được tạo.
​
model
string
Model được sử dụng.
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
}

​
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,
        "aspect_ratio": "16:9"
    }
)

​
Kling 3.0 Elements

Dùng kling_elements với kling-3.0-video khi cần tham chiếu phần tử. Cung cấp request có điều kiện ảnh (image_url, image_urls, start_image hoặc end_image) và tham chiếu từng phần tử trong prompt bằng @name. Không kết hợp kling_elements với output_audio=true; hãy bỏ output_audio hoặc đặt thành false khi dùng tham chiếu phần tử. 
response = requests.post("https://api.tokenlab.sh/v1/videos/generations",
    headers=headers,
    json={
        "model": "kling-3.0-video",
        "prompt": "Place @hero_bag on a studio turntable with soft product lighting.",
        "operation": "image-to-video",
        "image_url": "https://example.com/studio-start.png",
        "duration": 5,
        "resolution": "720p",
        "kling_elements": [
            {
                "name": "hero_bag",
                "description": "black leather handbag",
                "element_input_urls": [
                    "https://example.com/bag-front.png",
                    "https://example.com/bag-side.png"
                ]
            }
        ]
    }
)

​
Ả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",
        "prompt": "Smooth transition from day to night",
        "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. TokenLab chuyển nó thành body REST video.url của xAI. 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.",
        "resolution": "720p"
    }
)

​
Đ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" \
  -H "Authorization: Bearer sk-your-api-key"

curl "https://api.tokenlab.sh/v1/models/veo3.1" \
  -H "Authorization: Bearer sk-your-api-key"
Đọc tokenlab.capabilities, tokenlab.supported_operations, GET /v1/models và GET /v1/models/{model} 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.