Tạo tác vụ (Tương thích Volc)

Tổng quanCopy Anchor Link

Các client Seedance 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).

Xem thêm Mô hình Video Seedance 2.0 và Tạo Video.

Xác thực và EndpointCopy Anchor Link

• 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 TokenLab Bearer.
• Sử dụng đường dẫn tác vụ chính thức: POST /api/v3/contents/generations/tasks.

Quy tắc nội dungCopy Anchor Link

• 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.
• role: "reference_image", reference_video, và reference_audio được sử dụng làm tài liệu tham khảo.
• image_url.url chấp nhận URL hình ảnh công khai hoặc URI tài nguyên như asset://asset-YYYYMMDDHHMMSS-xxxxx. role xá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 khảo.
• Không trộn lẫn đầu vào khung hình đầu/cuối với phương tiện tham khảo trong cùng một yêu cầu.
• Các trường cấp cao nhất material_asset_id và material_asset_ids bị từ chối. Đặt URI tài nguyên TokenLab vào image_url.url. Chỉ Seedance 2.5 hỗ trợ priority.

Lưu ý về tham sốCopy Anchor Link

duration là số giây nguyên; -1 chọn thời lượng tự động. Giá trị mặc định và giới hạn khác nhau theo mô hình:

Với Seedance 2.5, các yêu cầu khung hình đầu, khung hình đầu/cuối, mở rộng video và video sang video cần ratio: "adaptive". Video sang video cũng cần duration: -1. Chỉ Seedance 2.5 hỗ trợ output_format là mp4 hoặc mov.

• ratio chấp nhận 16:9, 4:3, 1:1, 3:4, 9:16, 21:9, hoặc adaptive.
• watermark, return_last_frame, seed, execution_expires_after, và safety_identifier được chấp nhận khi hợp lệ với mô hình đã chọn.
• callback_url có thể trỏ đến một endpoint HTTP(S) công khai.

Gửi CallbackCopy Anchor Link

Khi có callback_url, TokenLab sẽ gửi một yêu cầu 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 của 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 dõi 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 lại 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 ảnhCopy Anchor Link

URL ảnh HTTP(S) công khai và URL data được hỗ trợ được dùng đúng như đầu vào, không tự động lưu thành tài nguyên có thể tái sử dụng. Tham chiếu tường minh asset://asset-... dùng tài nguyên TokenLab hiện có. Quyền sở hữu và trạng thái sẵn sàng được kiểm tra trước khi tạo. Nếu tài nguyên vẫn đang chuẩn bị, hãy chờ đến khi sẵn sàng rồi thử lại. Khi tạo thất bại, xem error.code và error.message.

Đố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ụCopy Anchor Link

{
  "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ặpCopy Anchor Link

Gửi một Idempotency-Key duy nhất cùng với các yêu cầu tạo. Nếu kết nối đóng trước khi nhận được phản hồi, 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êm Idempotency-Replayed: true.
• Nếu yêu cầu gốc vẫn đang được đăng ký, TokenLab trả về 409 IdempotencyRequestInProgress. Thử lại sau với cùng khóa và phần thân.
• Việc sử dụng lại khóa với phần thân khác sẽ trả về 409 IdempotencyConflict và không bao giờ tạo tác vụ thứ hai.

Idempotency áp dụng cho đường dẫn tạo REST v3 chính thức. Nó không thay đổi cấu trúc phản hồi JSON và không được suy ra 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ụCopy Anchor Link

Tạo bằng RESTCopy Anchor Link

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": "doubao-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 mỗi 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"}
  }
]

Bước tiếp theoCopy Anchor Link

Sử dụng ID cgt-... được trả về với Lấy tác vụ (Tương thích 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": "doubao-seedance-2-0-260128",    "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"}