Video & tư liệu
Tạo tác vụ (Tương thích với Volc)
Tạo tác vụ Seedance bằng API tương thích với Volc.
Tổng quan
Các ứng dụng khách Seedance theo kiểu Volc hiện có có thể sử dụng TokenLab bằng cách thay đổi địa chỉ API và khóa (key).
Các ví dụ sử dụng Seedance 2.0. Endpoint này cũng hỗ trợ Seedance 2.5 với các khác biệt cụ thể theo mô hình bên dưới. Các ví dụ về URI tài nguyên TokenLab có thể tái sử dụng trên trang này áp dụng cho Seedance 2.0.
Xem thêm Mô hình video Seedance 2.0 và Tạo video.
Xác thực và Endpoint
- Sử dụng
Authorization: Bearer <TOKENLAB_API_KEY>. - Chữ ký Volc AK/SK không được chấp nhận. Các yêu cầu phải bao gồm khóa Bearer của TokenLab.
- Sử dụng đường dẫn tác vụ chính thức:
POST /api/v3/contents/generations/tasks.
Quy tắc nội dung
type: "text"là văn bản gợi ý (prompt).type: "image_url"không córole, hoặc córole: "first_frame", được coi là khung hình đầu tiên.role: "last_frame"phải đi kèm với một khung hình đầu tiên.type: "video_url"yêu cầurole: "reference_video", vàtype: "audio_url"yêu cầurole: "reference_audio".role: "reference_image"đánh dấu một hình ảnh tham chiếu.- Giới hạn mục: Seedance 2.0 chấp nhận tối đa 16 mục
content(1 văn bản, 9 hình ảnh, 3 video, 3 âm thanh, 1draft_task). Seedance 2.5 chấp nhận tối đa 51 mục (1 văn bản, 30 hình ảnh, 10 video, 10 âm thanh, 1draft_task). image_url.urlchấp nhận URL hình ảnh công khai hoặc URI tài nguyên nhưasset://asset-YYYYMMDDHHMMSS-xxxxx.rolexác định liệu tài nguyên đó là khung hình đầu tiên, khung hình cuối cùng hay hình ảnh tham chiếu.- Không trộn lẫn đầu vào khung hình đầu/cuối với phương tiện tham chiếu trong cùng một yêu cầu.
- Phần thân REST chỉ chấp nhận các trường trên trang này. Bất kỳ trường cấp cao nhất nào khác, bao gồm
material_asset_idvàmaterial_asset_ids, sẽ trả về400 UnsupportedParameter. Hãy đặt URI tài nguyên TokenLab vàoimage_url.url.
Lưu ý về tham số
model chấp nhận ID mô hình TokenLab như seedance-2.0 hoặc seedance-2.5. Các ứng dụng khách hiện có có thể tiếp tục gửi ID mô hình Volcengine mà họ đang sử dụng cho các mô hình này. Phản hồi get-task sẽ trả về giá trị model mà bạn đã gửi. Một giá trị không được nhận dạng sẽ trả về 400 InvalidParameter.
duration là một số nguyên tính bằng giây; -1 chọn thời lượng tự động. Các giá trị mặc định và giới hạn khác nhau tùy theo mô hình:
| Tham số | Seedance 2.0 | Seedance 2.5 |
|---|---|---|
duration | 4–15 / -1 (mặc định: 5) | 4–30 / -1 (mặc định: -1) |
resolution | 480p, 720p, 1080p (mặc định: 720p) | 480p, 720p (mặc định: 720p) |
generate_audio | boolean (mặc định: false) | boolean (mặc định: true) |
priority | Không hỗ trợ | integer: 0–9 |
seed | integer: -1–4294967295 (mặc định: -1) | Không hỗ trợ |
execution_expires_after | 3600–259200 giây (mặc định: 172800) | 3600–259200 giây (mặc định: 172800) |
Đối với Seedance 2.5, các yêu cầu khung hình đầu tiên, khung hình đầu/cuối, mở rộng video và video-to-video yêu cầu ratio: "adaptive"; video-to-video cũng yêu cầu duration: -1. output_format chỉ chấp nhận mp4 hoặc mov cho Seedance 2.5.
ratiochấp nhận16:9,4:3,1:1,3:4,9:16,21:9, hoặcadaptive(mặc định:adaptive).watermarkvàreturn_last_framelà các giá trị boolean (mặc định:false).safety_identifierlà một chuỗi tối đa 64 ký tự.service_tierchỉ chấp nhậndefault;flexsẽ trả về400 UnsupportedParameter.toolschấp nhận tối đa một mục,{"type": "web_search"}.draft: true,frames, vàcamera_fixedkhông được hỗ trợ.camera_fixed: falsechỉ được chấp nhận cho Seedance 2.0.callback_urlcó thể trỏ đến một endpoint HTTP(S) công khai dài tối đa 2.048 ký tự.
Gửi Callback
Khi có callback_url, TokenLab sẽ gửi một HTTP POST khi trạng thái tác vụ thay đổi. Các trạng thái callback bao gồm queued, running, succeeded, failed, và expired. Phần thân JSON khớp với phản hồi get-task.
Phản hồi 2xx xác nhận việc gửi thành công. Đối với succeeded và failed, nếu việc gửi không thành công trong vòng năm giây, hệ thống sẽ thử lại tối đa ba lần. Callback chỉ có tiêu đề nội dung JSON tiêu chuẩn và không có tiêu đề gửi cụ thể của TokenLab. Các chuyển hướng (redirects) sẽ không được theo sau, và các mục tiêu mạng riêng tư hoặc dành riêng sẽ bị từ chối.
Hãy lưu ID tác vụ. Nếu callback không được gửi, bạn vẫn có thể truy xuất kết quả bằng endpoint get-task.
Chuẩn bị hình ảnh
Các URL hình ảnh HTTP(S) công khai và các URL dữ liệu được hỗ trợ sẽ được sử dụng như được cung cấp; chúng không tự động được lưu dưới dạng tài nguyên có thể tái sử dụng. Các tham chiếu asset://asset-... rõ ràng sẽ sử dụng các tài nguyên TokenLab hiện có. TokenLab kiểm tra quyền sở hữu và trạng thái sẵn sàng trước khi tạo. Nếu một tài nguyên được tham chiếu vẫn đang trong quá trình chuẩn bị, hãy đợi cho đến khi nó sẵn sàng và thử lại; kiểm tra error.code và error.message khi quá trình tạo thất bại.
Đối với các tài nguyên hiện có, hãy sử dụng ID asset-YYYYMMDDHHMMSS-xxxxx công khai thay vì ID tài nguyên gốc do hệ thống khác trả về. TokenLab xác minh quyền sở hữu tài nguyên trước khi tạo.
Phản hồi tạo tác vụ
{
"id": "cgt-20260102030405-a1b2c"
}Phản hồi tạo tác vụ chỉ chứa ID tác vụ. Hãy lưu lại để bạn có thể truy xuất trạng thái và kết quả bất cứ lúc nào.
Ngăn chặn tác vụ trùng lặp
Gửi một Idempotency-Key duy nhất (1–255 ký tự, không có ngắt dòng) cùng với các yêu cầu tạo. Nếu kết nối đóng trước khi phản hồi đến, hãy thử lại với cùng khóa API, khóa idempotency và phần thân yêu cầu:
- Nếu tác vụ gốc đã được tạo, TokenLab trả về cùng ID
cgt-...và thêmIdempotency-Replayed: true. - Việc sử dụng lại khóa với phần thân khác sẽ trả về
409với mãidempotency_conflictvà không bao giờ tạo tác vụ thứ hai. - Một khóa dài hơn 255 ký tự hoặc chứa ngắt dòng sẽ trả về
400 InvalidParameter.
Khóa này không làm thay đổi định dạng phản hồi JSON. TokenLab không suy luận các bản sao từ X-Request-ID hoặc từ các phần thân yêu cầu giống hệt nhau mà không có khóa.
Ví dụ
Tạo REST
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.0",
"content": [
{"type": "text", "text": "A cinematic forest at sunset"},
{"type": "image_url", "role": "reference_image", "image_url": {"url": "https://example.com/ref.png"}}
],
"ratio": "16:9",
"duration": 5,
"resolution": "720p",
"generate_audio": false,
"callback_url": "https://example.com/webhooks/seedance"
}'Đối với các tài nguyên hiện có, hãy đặt từng URI vào mục content[] chính thức và khai báo vai trò của nó:
[
{
"type": "image_url",
"role": "first_frame",
"image_url": {"url": "asset://asset-20260720123458-start"}
},
{
"type": "image_url",
"role": "last_frame",
"image_url": {"url": "asset://asset-20260720123459-end01"}
}
]Lỗi
Các lỗi REST sử dụng {"error": {"code", "message", "param", "type"}}. Các vấn đề về yêu cầu trả về 400 với InvalidParameter hoặc UnsupportedParameter, và việc thiếu khóa Bearer trả về 401 AuthenticationError. Các lỗi từ quá trình tạo video, chẳng hạn như không đủ số dư (402) hoặc giới hạn tốc độ (429), vẫn giữ nguyên trạng thái HTTP của chúng.
Các thao tác tương tự cũng có sẵn dưới dạng các Hành động CreateContentsGenerationsTasks, GetContentsGenerationsTask, ListContentsGenerationsTasks, và DeleteContentsGenerationsTasks trên POST /api/v3?Version=2024-01-01. Các tích hợp mới nên sử dụng các đường dẫn REST ở trên.
Bước tiếp theo
Sử dụng ID cgt-... được trả về với Lấy tác vụ (Tương thích với Volc) cho đến khi tác vụ đạt trạng thái cuối cùng.
curl -X POST "https://example.com/api/v3/contents/generations/tasks" \ -H "Content-Type: application/json" \ -d '{ "model": "seedance-2.0", "content": [ { "type": "text", "text": "A cinematic forest at sunset" }, { "type": "image_url", "role": "reference_image", "image_url": { "url": "https://example.com/ref.png" } } ], "ratio": "16:9", "duration": 5, "resolution": "720p", "generate_audio": false }'{ "id": "string"}Xác thực
BearerAuth 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
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"
Key do client tạo để tạo task REST có tính lũy đẳng (idempotent), 1-255 ký tự không có ngắt dòng. Dưới cùng một thông tin xác thực API TokenLab, việc sử dụng lại cùng một key với cùng một body JSON sẽ trả về ID task cgt gốc; sử dụng lại với body khác sẽ trả về 409 với mã idempotency_conflict. Một key quá dài hoặc chứa ngắt dòng sẽ trả về 400. Giữ nguyên thông tin xác thực, key và body yêu cầu khi thử lại sau khi hết thời gian chờ hoặc ngắt kết nối.
1 <= length <= 255Nộ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