https://router.flatkey.ai
Hướng dẫn này cung cấp cho bạn một lộ trình sao chép sẵn để sử dụng Seedance thông qua Flatkey. Bắt đầu với một tác vụ chuyển văn bản thành video, kiểm tra tác vụ liên tục cho đến khi hoàn tất, sau đó tải xuống file MP4 được tạo ra. Nếu bạn cần các tham chiếu sản phẩm, hình nền, âm thanh hoặc người thật có thể tái sử dụng, hãy tiếp tục đến các phần thư viện tài sản.
Các ví dụ sao chép sẵn
Sử dụng biểu tượng sao chép trên bất kỳ khối lệnh nào, sau đó thay thế
YOUR_FLATKEY_API_KEY, task_..., ast_..., và rph_... bằng các giá trị của riêng bạn.Một luồng công việc bất đồng bộ
Tạo tác vụ với
POST /v1/videos, kiểm tra liên tục với GET /v1/videos/{task_id}, và tải xuống MP4 từ metadata.url.metadata.url là ngoại lệ duy nhất.
Gọi Seedance
Bắt đầu tại đây nếu bạn chỉ muốn tạo một tác vụ chuyển văn bản thành video và tải xuống video đã hoàn thành.1. Tạo một tác vụ chuyển văn bản thành video
GửiPOST /v1/videos với mô hình seedance-2.0 và một prompt văn bản.
task_... được trả về. Lưu trữ nó trong cơ sở dữ liệu hoặc ghi chú của bạn vì bạn cần nó để kiểm tra video.
2. Kiểm tra tác vụ liên tục
Sử dụng endpoint này với ID tác vụ đã lưu:status là completed, sau đó đọc URL tải xuống từ metadata.url. Nếu trạng thái là failed, đọc error.message, sửa yêu cầu, và tạo một tác vụ mới.
metadata.url tải xuống file MP4 mà không cần header xác thực. Coi URL này là riêng tư và không công khai nó.
Sử dụng thư viện tài sản
Sử dụng thư viện tài sản khi bạn muốn đăng ký một tham chiếu một lần, chờ cho đến khi nó sẵn sàng, và tái sử dụng nó trong các yêu cầu Seedance. Có hai loại tài sản:
Sử dụng URI
asset://ast_... được Flatkey trả về trong các yêu cầu Seedance của bạn.
Tài sản ảo
Tài sản ảo không yêu cầu xác minh người thật. Tạo chúng từ một URL công khai hoặc tải lên một file cục bộ, sau đó tái sử dụng URI tài sản Flatkey được trả về.1. Tạo một tài sản ảo từ một URL HTTPS công khai
Gửi một URLhttps:// công khai.
id, ví dụ ast_1234567890abcdef1234567890abcdef, và một trạng thái như Processing. Xây dựng URI có thể tái sử dụng bằng cách thêm asset:// trước ID:
model khi bạn tạo, tải lên, hoặc truy vấn một tài sản. Flatkey suy ra các mô hình Seedance liên quan từ khóa API được sử dụng cho yêu cầu.
2. Tải lên một tài sản ảo cục bộ
Đối với một file hình ảnh, video, hoặc âm thanh cục bộ, gửimultipart/form-data đến POST /v1/assets/upload. Sử dụng một trường file. asset_type có thể là Image, Video, hoặc Audio.
id hoặc asset_url của nó để kiểm tra liên tục và các yêu cầu video sau này.
3. Kiểm tra liên tục cho đến khi mô hình đã chọn sẵn sàng
Truy vấn từng tài sản với cùng khóa API sẽ tạo tác vụ video. Ví dụ, kiểm tra hai tài sản hình ảnh riêng biệt:available_models. available_models luôn là một mảng và liệt kê các mô hình có thể sử dụng tài sản này ngay bây giờ. Một tài sản chỉ sẵn sàng phần nào có thể trông như thế này:
status là trạng thái tổng hợp trên các mô hình Seedance liên quan cho khóa API này:
Bạn không cần phải chờ trạng thái tổng hợp
Active khi mô hình bạn chọn đã được liệt kê. Trước khi tạo tác vụ, đảm bảo rằng mô hình đã chọn xuất hiện trong available_models của mọi tài sản. Đối với fast sử dụng seedance-2.0-fast; đối với pro sử dụng seedance-2.0. Yêu cầu tạo tác vụ kiểm tra lại trạng thái sẵn sàng, vì vậy hãy thử lại việc kiểm tra liên tục nếu định tuyến thay đổi giữa các yêu cầu GET và POST.
URI asset:// xác định tài sản nhưng không tự chứng minh trạng thái sẵn sàng. Deleting nghĩa là quá trình xóa đang diễn ra và tài sản không thể được sử dụng cho một tác vụ mới. Sau khi xóa hoàn tất, GET /v1/assets/{asset_id} trả về 404 asset_not_found; không chờ một trạng thái Deleted có thể kiểm tra được.
4. Gọi Seedance với hai tài sản ảo
Đặt mỗi URIasset://ast_... vào trường phương tiện phù hợp với loại tài sản: image_url.url cho Image, video_url.url cho Video, hoặc audio_url.url cho Audio. Một yêu cầu Seedance cần văn bản hoặc ít nhất một hình ảnh/video; âm thanh riêng lẻ là không đủ. Ví dụ này chỉ bắt đầu sau khi cả hai tài sản đều liệt kê seedance-2.0-fast trong available_models.
task_... được trả về và sử dụng GET /v1/videos/{task_id} từ phần đầu tiên để tải xuống video đã hoàn thành từ metadata.url.
Tài sản người thật
Tài sản người thật dành cho khuôn mặt, giọng nói, hoặc video của một người cụ thể. Khả năng này có quyền truy cập hạn chế. Chỉ sử dụng nó sau khi Flatkey bật nó cho tài khoản của bạn. Bạn sẽ tạo một hồ sơ, gửiverification_url cho người đó, chờ cho đến khi hồ sơ ở trạng thái active, tạo một tài sản, chờ cho đến khi status của tài sản là Active, sau đó gọi Seedance với asset://ast_....
Giới hạn kích thước file:
Các yêu cầu ghi trong phần này yêu cầu
Idempotency-Key. Thay thế mỗi placeholder YOUR_UNIQUE_KEY_... bằng một UUID mới cho mỗi yêu cầu ghi mới. Chỉ tái sử dụng một khóa khi thử lại chính xác yêu cầu tương tự.
1. Tạo một hồ sơ người thật
id hồ sơ, một status, và một verification_url sử dụng một lần. Gửi verification_url cho người thật đó và yêu cầu họ tự mở nó. Không công khai liên kết này.
Nếu liên kết hết hạn hoặc người đó cần một liên kết khác, tạo một phiên xác minh mới:
2. Kiểm tra liên tục cho đến khi hồ sơ hoạt động
active trước khi tạo tài sản. Nếu là pending_verification hoặc verifying, hãy chờ và kiểm tra lại. Nếu là failed hoặc expired, tạo một phiên xác minh mới.
3. Tạo một tài sản người thật từ một URL công khai
4. Tải lên một file cục bộ
Tải lên cục bộ sử dụngmultipart/form-data và chỉ có sẵn cho tài sản người thật. Sử dụng một trường file và để curl đặt ranh giới multipart.
asset_uri, ví dụ asset://ast_1234567890abcdef1234567890abcdef.
5. Kiểm tra liên tục trạng thái sẵn sàng và gọi Seedance
Phản hồi tài sản người thật không bao gồmavailable_models. Liệt kê các tài sản dưới hồ sơ cho đến khi status của tài sản là Active:
Processing, hãy chờ và kiểm tra lại. Nếu là Failed, tạo một tài sản mới từ một tham chiếu tốt hơn.
Sau khi tài sản là Active, gọi Seedance với URI asset://ast_....
task_... được trả về và sử dụng GET /v1/videos/{task_id} từ phần đầu tiên để tải xuống video đã hoàn thành từ metadata.url.
6. Xóa một tài sản khi bạn không còn cần nó
204 No Content. Sau khi xóa hoàn tất, GET /v1/assets/{asset_id} trả về 404 asset_not_found.