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ình | Trường hợp sử dụng |
|---|---|---|
text-to-video | prompt | Tạo từ văn bản thuần túy |
image-to-video | image_url hoặc image tương thích | Tạo chuyển động từ hình ảnh bắt đầu |
reference-to-video | reference_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-video | start_image, end_image | Kiểm soát khung hình đầu và cuối |
video-to-video | video_url hoặc task_id dành riêng cho mô hình | Chuyển đổi hoặc nâng cấp (upscale) một clip hiện có |
motion-control | image_url cộng với video_url | Áp dụng tham chiếu chuyển động cho một chủ thể |
audio-to-video | audio_url | Các luồng video được điều khiển bằng âm thanh |
video-extension | task_id, extend_at, hoặc các trường mở rộng dành riêng cho mô hình | Tiế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-liteluôn tạo âm thanh. Hãy bỏ quaoutput_audiohoặc gửitrue; giá trịfalsesẽ bị từ chối.wan-2.6vàwan-2.7luôn bao gồm âm thanh. Hãy bỏ quaoutput_audiohoặc gửitrue.wan-3.0vàwan-3.0-primecũng luôn bao gồm âm thanh và không sử dụng bộ chọn âm thanh.hailuo-h3tạ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-provàviduq3-turbotạo âm thanh theo mặc định; hãy gửioutput_audio: false(hoặcaudio: false) để có đầu ra không âm thanh. Các mô hình Seedance và PixVerse sử dụngoutput_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_urlscung 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ửipromptvà mộtvideo_urlHTTPS công khai định dạng.mp4. Một URL kết quả.mp4củ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ọnduration,resolution, hoặcaspect_ratio.
PixVerse và HappyHorse
| Mô hình | Thao tác | Đầu vào | Độ phân giải | Thời lượng | Bộ chọn âm thanh |
|---|---|---|---|---|---|
pixverse-c1, pixverse-v6 | text-to-video, image-to-video, start-end-to-video, reference-to-video | prompt; image_url; start_image + end_image; reference_images | 360p, 540p, 720p, 1080p | Bất kỳ số nguyên từ 1 đến 15 giây | output_audio, mặc định false |
pixverse-v5.6 | text-to-video, image-to-video, start-end-to-video, reference-to-video | Các trường giống như C1 và V6 | 360p, 540p, 720p, 1080p | 5, 8 hoặc 10 giây; 1080p hỗ trợ 5 hoặc 8 giây | output_audio, mặc định false |
happyhorse-1.0 | text-to-video, image-to-video, reference-to-video, video-to-video | prompt; image_url; reference_images; video_url + reference_images | 720p, 1080p | 3 đến 15 giây cho các thao tác tạo; đầu ra video-to-video bị giới hạn ở 15 giây | Khô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
durationmô 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-Keycùng vớiPOST /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 video | Tạo video |
| Nhận trạng thái video | Nhậ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"
}