TokenLab

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 đổiClient Volcengine hiện tạiTokenLab
Base URLEndpoint Volcengine của bạnhttps://api.tokenlab.sh/
Xác thựcKý yêu cầu AK/SKAuthorization: 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ựcCá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ênCá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ụ VolcengineID 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ạiEndpoint 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ựcPOST /?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ẫnMục đích
POST /api/v3/contents/generations/tasksTạo tác vụ video
GET /api/v3/contents/generations/tasks/{id}Đọc một tác vụ
GET /api/v3/contents/generations/tasksLiệ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:

Quy tắc phần thân yêu cầu

  • content[] chấp nhận các mục text, image_url, video_url, audio_url và draft_task.
  • Đối với image_url, hãy bỏ qua role hoặc sử dụng first_frame cho tính năng image-to-video. Sử dụng last_frame cùng với một khung hình đầu tiên, hoặc reference_image cho tính năng reference-to-video.
  • Một URI tài nguyên công khai như asset://asset-YYYYMMDDHHMMSS-xxxxx có 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_after và safety_identifier. Các giá trị mặc định khác nhau theo model. generate_audio là false cho các model seedance-2.0 và true cho seedance-2.5, còn duration là 5 cho các model seedance-2.0 và -1 cho seedance-2.5. Định dạng REST này chấp nhận các giá trị resolution là 480p, 720p và 1080p (480p và 720p cho seedance-2.5) nhưng không chấp nhận 4k, vốn chỉ được API /v1/videos/generations hợp nhất hỗ trợ. seedance-2.5 từ chối seed, frames và camera_fixed.
  • callback_url chấ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ái queued, running, succeeded, failed và expired; chỉ có succeeded và failed tuâ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:

  1. Tạo phiên xác thực hình ảnh
  2. Lấy kết quả xác thực hình ảnh

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

  1. Thay thế API host bằng https://api.tokenlab.sh.
  2. Thay thế việc ký AK/SK bằng API key Bearer của TokenLab.
  3. 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.
  4. Giữ nguyên ProjectName trên các yêu cầu tài nguyên và xác thực liên quan.
  5. 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.
  6. 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.

Trên trang này