TokenLab

Hướng dẫn media

Tạo video

Tạo video từ văn bản, hình ảnh, âm thanh hoặc các clip có sẵn

Việc tạo video là không đồng bộ (asynchronous). POST /v1/videos/generations trả về một ID tác vụ và thường là một poll_url. Hãy thực hiện GET /v1/tasks/{id} với ID đó cho đến khi video hoàn tất.

Gửi các URL HTTP(S) công khai hoặc các URL dữ liệu được hỗ trợ trong các trường hình ảnh mà mô hình bạn chọn chấp nhận. Các đầu vào này tuân theo đường dẫn phương tiện thông thường và không tự động tạo ra các ID tài liệu có thể tái sử dụng.

Khi một tài liệu rõ ràng vẫn đang trong quá trình chuẩn bị, POST /v1/videos/generations sẽ trả về 409 seedance_material_preparing cùng với inactive_asset_ids. Hãy thăm dò các tài sản đó cho đến khi trạng thái là ACTIVE, sau đó thử lại với cùng các ID tài liệu đó. Nếu một tài sản ở trạng thái FAILED, hãy kiểm tra error_message và sửa hoặc nhập lại tài sản đó trước khi thử lại.

Chọn một API

Sử dụng /v1/videos/generations cho một tích hợp video mới. Các khách hàng Seedance 2.0 hiện tại đã gửi các yêu cầu content[] hoặc Action của Volcengine có thể giữ nguyên định dạng đó thông qua /api/v3. Cả hai API đều sử dụng khóa TokenLab Bearer, nhưng các trường và giá trị trạng thái của chúng khác nhau.

Chọn nội dung cần tạo

Thiết lập operation một cách rõ ràng để API có thể xác thực các trường phù hợp cho công việc.

Thao tácĐầu vào bắt buộc hoặc điển hìnhTrường hợp sử dụng
text-to-videopromptTạo từ văn bản thuần túy
image-to-videoimage_url hoặc image tương thíchTạo chuyển động từ hình ảnh bắt đầu
reference-to-videoreference_images và tùy chọn video_urls / audio_urls trên các mô hình được hỗ trợGiữ nguyên danh tính, phong cách hoặc tham chiếu tài sản
start-end-to-videostart_image, end_imageKiểm soát khung hình đầu và cuối
video-to-videovideo_url hoặc task_id dành riêng cho mô hìnhChuyển đổi hoặc nâng cấp (upscale) một clip hiện có
motion-controlimage_url cộng với video_urlÁp dụng tham chiếu chuyển động cho một chủ thể
audio-to-videoaudio_urlCác luồng video được điều khiển bằng âm thanh
video-extensiontask_id, extend_at, hoặc các trường mở rộng dành riêng cho mô hìnhTiếp tục một video đã tạo

Chọn một mô hình

curl "https://api.tokenlab.sh/v1/models?recommended_for=video" \
  -H "Authorization: Bearer sk-your-api-key"

Sử dụng ID mô hình do TokenLab trả về, sau đó chọn loại tạo video bằng operation và các đầu vào phương tiện tương ứng. Không sử dụng tên thao tác làm ID mô hình.

Đọc chi tiết mô hình đã chọn trước khi dựa vào các trường chuyên biệt như reference_images, kling_elements, output_audio, duration, resolution, hoặc aspect_ratio.

Tạo video

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": "A calm cinematic shot of a cat walking through a sunlit garden",
    "resolution": "720p",
    "duration": 4,
    "aspect_ratio": "16:9"
  }'

Sử dụng các URL https cho phương tiện có thể được truy xuất từ internet. Các URL tạm thời phải duy trì hiệu lực cho đến khi TokenLab tạo xong tác vụ.

Các trường dành riêng cho mô hình

Hành vi âm thanh phụ thuộc vào mô hình được chọn và thao tác. Một video có thể chứa âm thanh ngay cả khi không có bộ chọn âm thanh nào được hiển thị. Việc bỏ qua bộ chọn khác với việc gửi false.

  • veo3.1, veo3.1-fast, và veo3.1-lite luôn tạo âm thanh. Hãy bỏ qua output_audio hoặc gửi true; giá trị false sẽ bị từ chối.
  • wan-2.6 và wan-2.7 luôn bao gồm âm thanh. Hãy bỏ qua output_audio hoặc gửi true. wan-3.0 và wan-3.0-prime cũng luôn bao gồm âm thanh và không sử dụng bộ chọn âm thanh.
  • hailuo-h3 tạo âm thanh gốc và không có công tắc tắt tiếng. Không gửi bộ chọn âm thanh mà chi tiết mô hình không liệt kê.
  • viduq3-pro và viduq3-turbo tạo âm thanh theo mặc định; hãy gửi output_audio: false (hoặc audio: false) để có đầu ra không âm thanh. Các mô hình Seedance và PixVerse sử dụng output_audio; hãy gửi tham số này một cách rõ ràng thay vì dựa vào mặc định. Chỉ sử dụng tham số này cho các thao tác có liệt kê nó.
  • audio_url / audio_urls cung cấp âm thanh đầu vào hoặc âm thanh tham chiếu. Chúng không phải là các công tắc đầu ra âm thanh. Chỉnh sửa video, chuyển động (motion transfer) và chuyển đổi phong cách (style transfer) có thể giữ lại bản nhạc đầu vào; việc bảo toàn âm thanh nguồn không có nghĩa là tắt tiếng nó.

Hãy kiểm tra chi tiết mô hình để biết các giá trị được phép và giá phí phụ thuộc vào âm thanh. Ở những nơi mô hình liệt kê chúng, các bí danh outputAudio, generate_audio, và boolean audio phải khớp với output_audio khi được kết hợp. Đừng mặc định rằng mọi phiên bản hoặc thao tác trong một dòng mô hình đều chia sẻ các điều khiển âm thanh giống nhau.

  • Đối với dòng Seedance 2.0, hãy đọc hướng dẫn về các mô hình video Seedance 2.0 trước khi sử dụng đầu ra 4K, giới hạn độ phân giải Fast/Mini, hoặc các đầu vào tham chiếu đa phương thức.
  • Đối với grok-imagine-video (video-to-video), hãy gửi prompt và một video_url HTTPS công khai định dạng .mp4. Một URL kết quả .mp4 của TokenLab từ một tác vụ trước đó cũng có thể hoạt động. Thao tác này không sử dụng các bộ chọn duration, resolution, hoặc aspect_ratio.

PixVerse và HappyHorse

Mô hìnhThao tácĐầu vàoĐộ phân giảiThời lượngBộ chọn âm thanh
pixverse-c1, pixverse-v6text-to-video, image-to-video, start-end-to-video, reference-to-videoprompt; image_url; start_image + end_image; reference_images360p, 540p, 720p, 1080pBất kỳ số nguyên từ 1 đến 15 giâyoutput_audio, mặc định false
pixverse-v5.6text-to-video, image-to-video, start-end-to-video, reference-to-videoCác trường giống như C1 và V6360p, 540p, 720p, 1080p5, 8 hoặc 10 giây; 1080p hỗ trợ 5 hoặc 8 giâyoutput_audio, mặc định false
happyhorse-1.0text-to-video, image-to-video, reference-to-video, video-to-videoprompt; image_url; reference_images; video_url + reference_images720p, 1080p3 đến 15 giây cho các thao tác tạo; đầu ra video-to-video bị giới hạn ở 15 giâyKhông gửi output_audio

Trên TokenLab, các mô hình PixVerse ở trên không chấp nhận 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
  }'

Nhận video đã hoàn thành

Gọi GET /v1/tasks/{id} với id hoặc task_id từ phản hồi tạo tác vụ cho đến khi tác vụ ở trạng thái completed hoặc failed.

Các tác vụ video hoàn tất có thể trả về video_url, video, hoặc videos tùy thuộc vào mô hình và số lượng đầu ra. Hãy coi billing_transaction_id là định danh thanh toán, không phải là định danh tác vụ.

Các URL kết quả video là các URL phương tiện của TokenLab kết thúc bằng loại tệp, chẳng hạn như .mp4, và có hiệu lực trong 30 ngày. media_retention.items báo cáo trạng thái lưu trữ của từng mục và expires_at; phản hồi có thể bỏ qua media_retention khi trạng thái lưu trữ không được xác định kịp thời, và URL vẫn hoạt động. Các tác vụ thất bại hoặc đang thực hiện sẽ trả về các trường URL video trống. Các bản chụp nhanh tác vụ không đồng bộ có vòng đời riêng. Xem Lưu giữ dữ liệu.

Các lỗi thường gặp

  • Không sử dụng các đường dẫn trạng thái theo phương thức như /v1/videos/generations/{id} trong mã mới; hãy thăm dò GET /v1/tasks/{id}.
  • Không kết hợp các trường khung hình đầu tiên với các luồng tham chiếu hình ảnh chuyên dụng trừ khi chi tiết mô hình cho phép.
  • Đừng cho rằng duration mô tả độ dài của video tham chiếu đầu vào; nó thường kiểm soát độ dài đầu ra được tạo.
  • Gửi Idempotency-Key cùng với POST /v1/videos/generations. Sau khi hết thời gian chờ, hãy gửi cùng một yêu cầu với cùng một khóa để nhận lại tác vụ ban đầu. Nếu không có khóa, hãy kiểm tra xem tác vụ đã được tạo trước đó hay chưa trước khi thử lại.

Tham chiếu API

Chủ đềTham chiếu
Tạo videoTạo video
Nhận trạng thái videoNhận trạng thái video
Nhận trạng thái tác vụNhận trạng thái tác vụ
Hủy tác vụHủy tác vụ
Thanh toán & Giá cảThanh toán & Giá cả

Hailuo H3-Max tạo các video dài 5–15 giây ở độ phân giải 480p hoặc 768p từ văn bản, một khung hình đầu tiên, hoặc khung hình đầu và cuối. Quy trình tập trung vào tốc độ của nó rất hữu ích để nhanh chóng biến ý tưởng cảnh quay thành một clip ngắn.

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

Trên trang này