Hướng dẫn media
Di chuyển Seedance từ Volcengine
Giữ nguyên định dạng yêu cầu Volcengine và chuyển đổi Seedance sang TokenLab
Nếu ứng dụng của bạn hiện đang sử dụng API Seedance của Volcengine, bạn có thể giữ nguyên các đường dẫn REST, phần thân content[], các trường phản hồi, callback và các Action tài nguyên dạng PascalCase. Chỉ cần thay đổi API host và thay thế việc ký yêu cầu AK/SK bằng API key của TokenLab.
Những thay đổi
| Thay đổi | Client Volcengine hiện tại | TokenLab |
|---|---|---|
| Base URL | Endpoint Volcengine của bạn | https://api.tokenlab.sh/ |
| Xác thực | Ký yêu cầu AK/SK | Authorization: Bearer <TOKENLAB_API_KEY> |
| Truyền tải tác vụ | Các đường dẫn REST /api/v3/contents/generations/tasks chính thức | Được giữ nguyên |
| Action tài nguyên/xác thực | Các tham số truy vấn Action và Version | Được giữ nguyên |
| Phần thân tác vụ | content[] theo kiểu Volcengine | Được giữ nguyên |
| Phần thân tài nguyên | Các trường PascalCase như GroupId và ProjectName | Được giữ nguyên |
| Kết quả bất đồng bộ | Vòng đời tác vụ Volcengine | ID tác vụ cgt-... của TokenLab với cơ chế polling và callback tùy chọn |
Các yêu cầu chỉ được ký bằng AK/SK sẽ trả về 401 AuthenticationError. Mọi yêu cầu gửi đến TokenLab phải bao gồm Authorization: Bearer <TOKENLAB_API_KEY>.
Chọn endpoint
| Client hiện tại | Endpoint TokenLab |
|---|---|
| Client tác vụ REST Volcengine | /api/v3/contents/generations/tasks và các đường dẫn tác vụ của nó |
| Client Action tài nguyên hoặc xác thực | POST /?Action=...&Version=2024-01-01 hoặc POST /api/v3?Action=...&Version=2024-01-01 |
Đối với các tác vụ video, hãy giữ nguyên phương thức REST, đường dẫn và phần thân JSON hiện tại. Các yêu cầu về tài nguyên và xác thực tiếp tục sử dụng các tham số truy vấn Action và Version. Endpoint Action cũng chấp nhận các Action tác vụ CreateContentsGenerationsTasks, GetContentsGenerationsTask, ListContentsGenerationsTasks và DeleteContentsGenerationsTasks; hãy sử dụng các đường dẫn REST cho công việc mới.
Các đường dẫn tác vụ chính thức
| Phương thức và đường dẫn | Mục đích |
|---|---|
POST /api/v3/contents/generations/tasks | Tạo tác vụ video |
GET /api/v3/contents/generations/tasks/{id} | Đọc một tác vụ |
GET /api/v3/contents/generations/tasks | Liệt kê các tác vụ |
DELETE /api/v3/contents/generations/tasks/{id} | Hủy một tác vụ đang chờ xử lý. Tác vụ đã bắt đầu sẽ trả về 409 task_not_cancellable |
Các REST client có thể sử dụng các tham chiếu tương đương sau:
- Tạo tác vụ (Tương thích Volc)
- Lấy tác vụ (Tương thích Volc)
- Liệt kê tác vụ (Tương thích Volc)
- Hủy tác vụ (Tương thích Volc)
Quy tắc phần thân yêu cầu
content[]chấp nhận các mụctext,image_url,video_url,audio_urlvàdraft_task.- Đối với
image_url, hãy bỏ quarolehoặc sử dụngfirst_framecho tính năng image-to-video. Sử dụnglast_framecùng với một khung hình đầu tiên, hoặcreference_imagecho tính năng reference-to-video. - Một URI tài nguyên công khai như
asset://asset-YYYYMMDDHHMMSS-xxxxxcó thể được sử dụng ở nơi mà quy trình Seedance đã chọn chấp nhận vai trò phương tiện đó. - Phần thân REST chỉ chấp nhận các trường chính thức, bao gồm
model,content,ratio,duration,resolution,generate_audio,watermark,return_last_frame,seed,execution_expires_aftervàsafety_identifier. Các giá trị mặc định khác nhau theo model.generate_audiolàfalsecho các modelseedance-2.0vàtruechoseedance-2.5, còndurationlà5cho các modelseedance-2.0và-1choseedance-2.5. Định dạng REST này chấp nhận các giá trịresolutionlà480p,720pvà1080p(480pvà720pchoseedance-2.5) nhưng không chấp nhận4k, vốn chỉ được API/v1/videos/generationshợp nhất hỗ trợ.seedance-2.5từ chốiseed,framesvàcamera_fixed. callback_urlchấp nhận một endpoint HTTP(S) công khai. TokenLab gửi cùng một phần thân truy vấn tác vụ cho các trạng tháiqueued,running,succeeded,failedvàexpired; chỉ cósucceededvàfailedtuân theo hành vi chính thức: thời gian chờ 5 giây và thử lại khi endpoint của bạn không xác nhận thông báo.
Ví dụ REST tối giản
curl 'https://api.tokenlab.sh/api/v3/contents/generations/tasks' \
-H "Authorization: Bearer $TOKENLAB_API_KEY" \
-H "Idempotency-Key: $CLIENT_JOB_ID" \
-H "Content-Type: application/json" \
-d '{
"model": "seedance-2.5",
"content": [
{"type":"text","text":"A cinematic product reveal"},
{"type":"image_url","role":"reference_image","image_url":{"url":"https://example.com/reference.png"}}
],
"ratio": "16:9",
"duration": 5,
"resolution": "720p"
}'Lưu trữ ID cgt-... được trả về. Thực hiện polling cho đến khi status trở thành succeeded, failed, cancelled hoặc expired; đừng coi phản hồi tạo tác vụ là video đã hoàn thành. Nếu bạn cung cấp callback_url, hãy cho phép các thông báo succeeded hoặc failed lặp lại và tiếp tục polling như một phương thức khôi phục.
Giữ riêng biệt các kiểu v1 và v3
Không sử dụng lại cấu trúc phản hồi /v1/tasks/{id} cho endpoint này. API v1 hợp nhất báo cáo các trạng thái pending, processing, completed và failed; API v3 tương thích với Volc báo cáo queued, running, succeeded, failed, cancelled và expired. Phản hồi v3 chính thức cũng biểu diễn duration dưới dạng chuỗi JSON và bỏ qua trường error trên các tác vụ không thất bại.
Để khôi phục an toàn sau khi hết thời gian chờ tạo hoặc ngắt kết nối, hãy thêm một Idempotency-Key duy nhất vào yêu cầu tạo REST. Việc thử lại cùng một phần thân với cùng một khóa sẽ trả về ID cgt-... ban đầu; cùng một khóa với phần thân khác sẽ trả về 409.
Tài nguyên và xác thực người thật
Endpoint Action tương tự cũng hỗ trợ 10 thao tác tài nguyên và nhóm tài nguyên. Xem Action tài nguyên (Tương thích Volc) để biết chính xác các phần thân PascalCase, bộ lọc, phân trang, bao đóng phản hồi và URL tài nguyên có thời hạn 12 giờ.
Các tài nguyên người thật bổ sung hai Action trước khi tải lên:
Action thứ hai trả về GroupId đã được xác minh. Sử dụng ID đó với CreateAsset; client không thể tạo trực tiếp nhóm LivenessFace.
Danh sách kiểm tra di chuyển
- Thay thế API host bằng
https://api.tokenlab.sh. - Thay thế việc ký AK/SK bằng API key Bearer của TokenLab.
- Giữ nguyên phương thức, đường dẫn và định dạng phần thân yêu cầu của tác vụ REST chính thức; chỉ giữ lại Action và version cho các thao tác tài nguyên hoặc xác thực.
- Giữ nguyên
ProjectNametrên các yêu cầu tài nguyên và xác thực liên quan. - Lưu trữ các ID tác vụ, nhóm và tài nguyên TokenLab được trả về bởi các endpoint này.
- Xác minh một phản hồi tạo, polling, liệt kê và lỗi trước khi chuyển lưu lượng truy cập sản xuất.