Danh sách kiểm tra triển khai Seedance API cho các nhóm text-to-video

Một nguyên mẫu Seedance API có thể trông như đã hoàn thiện sau một video thành công. Một tích hợp production chỉ thực sự hoàn tất khi hệ thống của bạn có thể chịu được các job chậm, sự kiện trùng lặp, lộ trình model thay đổi, lỗi một phần và chi phí không chắc chắn.

Sự khác biệt đó rất quan trọng vì việc tạo video không phải là một tính năng request-response thông thường. Ứng dụng gửi công việc, chờ đợi, nhận các thay đổi trạng thái, lưu trữ đầu ra lớn và quyết định xem một lỗi có nên được thử lại hay không. Lời gọi model chỉ là một giai đoạn trong một quy trình dài hơn.

Danh sách kiểm tra này biến quy trình đó thành một cam kết production để các nhóm sản phẩm, nền tảng và tài chính của bạn có thể cùng xem xét.

Lưu ý về lộ trình hiện tại: Danh mục model công khai của Flatkey liệt kê seedance-2.5 cho text-to-video và image-to-video, cùng với seedance-2.0-i2v cho image-to-video, khi hướng dẫn này được kiểm tra vào Thứ Hai, ngày 27 tháng 7 năm 2026. Hãy xem những tên đó là trạng thái của danh mục, không phải hằng số vĩnh viễn. Xác nhận thư mục model của Flatkey hiện tại trước khi triển khai hoặc thay đổi danh sách cho phép.

Câu trả lời ngắn

Đừng kết nối trực tiếp yêu cầu từ phía người dùng với lời gọi đến nhà cung cấp video. Hãy đặt một lớp job bền vững ở giữa.

Đường đi production tối thiểu của bạn nên là:

1. tiếp nhận và xác thực yêu cầu tạo của người dùng
2. gán khóa idempotency và job ID riêng của bạn
3. lưu yêu cầu trước khi gọi lộ trình model
4. gửi job thông qua một adapter phía server
5. xử lý các cập nhật webhook và polling một cách idempotent
6. sao chép media đã hoàn tất sang bộ lưu trữ do bạn kiểm soát
7. ghi lại độ trễ, lý do lỗi, lộ trình model và chi phí ước tính
8. hiển thị trạng thái sản phẩm ổn định, không phụ thuộc vào cách diễn đạt của nhà cung cấp

Nếu thiếu một trong các bước đó, tích hợp vẫn có thể trình diễn tốt, nhưng sẽ khó vận hành an toàn hơn.

Vì sao công việc production với Seedance API lại khác

Tạo văn bản thường trả về một phản hồi hữu ích trong một lần trao đổi HTTP. Tạo video thường hoạt động như một job batch phân tán. Một hành động của người dùng có thể kéo dài lâu hơn một request ứng dụng, một lần triển khai, một phiên trình duyệt, hoặc thậm chí là URL tạm thời cuối cùng lưu kết quả.

Những hệ quả thực tế rất dễ bị đánh giá thấp:

Mục tiêu không phải là che giấu nhà cung cấp. Mục tiêu là ngăn hành vi đặc thù của nhà cung cấp trở thành hợp đồng vĩnh viễn của sản phẩm bạn.

1. Khóa hợp đồng sản phẩm trước payload

Bắt đầu từ trải nghiệm bạn hứa với người dùng, chứ không phải các trường của nhà cung cấp hiện có hôm nay.

Định nghĩa:

• các loại đầu vào được chấp nhận: chỉ văn bản, ảnh cộng văn bản, hoặc cả hai
• tỷ lệ khung hình và dải thời lượng được hỗ trợ
• giới hạn kích thước tải lên tối đa và các định dạng media được chấp nhận
• kiểm tra kiểm duyệt và quyền trước khi gửi
• các cập nhật trạng thái dự kiến và hành vi hủy
• thời gian lưu giữ đầu ra
• một công việc thất bại có tiêu tốn credit của người dùng hay không
• “retry” nghĩa là gì trong sản phẩm

Sau đó, chuyển hợp đồng đó thành tuyến Seedance hiện tại bên trong một adapter.

Sự tách biệt này bảo vệ bạn khỏi hai kiểu lỗi phổ biến. Thứ nhất, một cập nhật tuyến có thể thêm hoặc đổi tên tham số mà không buộc phải viết lại frontend. Thứ hai, ứng dụng của bạn có thể từ chối các tổ hợp không được hỗ trợ trước khi tốn tiền cho một công việc chắc chắn thất bại.

2. Dùng job ID và idempotency key của riêng bạn

Mỗi yêu cầu cần hai định danh:

• product job ID: định danh ổn định được hiển thị xuyên suốt hệ thống của bạn
• idempotency key: định danh dùng để ngăn việc gửi trùng lặp ngoài ý muốn

Đừng dùng task ID của nhà cung cấp làm khóa chính. Nó chỉ tồn tại sau khi gửi, và nó có thể thay đổi nếu bạn chủ động gửi lại qua một tuyến khác.

Một bản ghi yêu cầu đơn giản có thể trông như sau:

type VideoJob = {
  id: string;
  idempotencyKey: string;
  accountId: string;
  requestedModel: string;
  resolvedModel: string | null;
  providerTaskId: string | null;
  status: "accepted" | "queued" | "running" | "succeeded" | "failed" | "cancelled";
  attempt: number;
  outputUrl: string | null;
  failureCode: string | null;
  createdAt: string;
  updatedAt: string;
};

Tạo bản ghi này trước khi gọi API đi ra ngoài. Nếu ứng dụng gặp sự cố sau khi gửi nhưng trước khi lưu phản hồi, idempotency key sẽ cho bạn cách đối soát thay vì tính phí mù quáng cho một lần tạo khác.

3. Đặt Seedance sau một adapter phía máy chủ duy nhất

Giữ việc xây dựng request theo từng nhà cung cấp trong một mô-đun duy nhất. Phần còn lại của sản phẩm nên gửi một lệnh đã được chuẩn hóa như sau:

type GenerateVideoCommand = {
  prompt: string;
  sourceImageUrl?: string;
  aspectRatio: "16:9" | "9:16" | "1:1";
  durationSeconds: number;
  qualityProfile: "draft" | "standard" | "high";
};

Bộ điều hợp chịu trách nhiệm về:

• ánh xạ qualityProfile sang mô hình và cài đặt hiện đang khả dụng
• đính kèm xác thực ở phía máy chủ
• chuyển đổi các lựa chọn aspect và duration của bạn sang schema API đang hoạt động
• gửi tác vụ
• chuẩn hóa lỗi từ nhà cung cấp
• lưu ID tác vụ của nhà cung cấp
• báo cáo đủ metadata cho phân tích chi phí và độ tin cậy

Flatkey cung cấp cho các nhóm một API key, một endpoint router ổn định, một số dư dùng chung và khả năng hiển thị tập trung mức sử dụng trên các họ mô hình. Với các nhóm đã dùng lớp truy cập đó, hãy giữ logic bất đồng bộ đặc thù của Seedance trong bộ điều hợp thay vì rải các giả định về route khắp codebase. Hướng dẫn trước về stable OpenAI-compatible base URL cho các nhóm Seedance API giải thích ranh giới đó chi tiết hơn.

4. Mô hình hóa workflow như một máy trạng thái

Đừng để các chuỗi trạng thái tùy ý đi vào logic sản phẩm. Hãy chuẩn hóa chúng.

stateDiagram-v2
    [*] --> accepted
    accepted --> queued: submit accepted
    accepted --> failed: validation or submit error
    queued --> running: provider starts work
    queued --> failed: terminal provider error
    running --> succeeded: output verified
    running --> failed: terminal provider error
    accepted --> cancelled: cancelled before submit
    queued --> cancelled: cancellation confirmed
    succeeded --> [*]
    failed --> [*]
    cancelled --> [*]

Chỉ cho phép các chuyển trạng thái tiến lên trừ khi bạn đang chạy một quy trình khôi phục rõ ràng. Một sự kiện running đến muộn không được ghi đè một job đã được đánh dấu succeeded. Một webhook succeeded bị nhân đôi không được kích hoạt hai bản sao lưu trữ hoặc hai thông báo khách hàng.

Lưu riêng sự kiện thô từ nhà cung cấp để gỡ lỗi, nhưng đưa ra quyết định sản phẩm từ trạng thái đã chuẩn hóa.

5. Dùng webhooks và polling cùng nhau

Webhooks hiệu quả, nhưng chúng không đảm bảo rằng ứng dụng của bạn sẽ xử lý mọi sự kiện đúng một lần và theo đúng thứ tự. Polling chậm hơn, nhưng hữu ích cho việc đối soát.

Hãy dùng cả hai:

• đường webhook: cập nhật trạng thái độ trễ thấp
• đường polling: khôi phục theo lịch cho các job không thay đổi gần đây

Webhook handler của bạn nên:

1. xác thực callback khi API đang hoạt động hỗ trợ xác minh
2. phân tích sự kiện mà không làm công việc nặng trực tiếp tại chỗ
3. ghi fingerprint của sự kiện vào bảng deduplication
4. đưa việc xử lý vào hàng đợi
5. trả về thành công nhanh chóng

Worker đối soát của bạn chỉ nên polling những job vẫn chưa ở trạng thái cuối sau một độ trễ hợp lý. Thêm jitter để một lần triển khai không làm phát sinh hàng nghìn lượt kiểm tra trạng thái cùng một lúc.

Webhook và các trường truy vấn phụ thuộc vào nhà cung cấp có thể thay đổi. Hãy xác minh chúng theo tài liệu tham chiếu API chính thức hiện tại trong quá trình triển khai thay vì sao chép một payload cũ từ bài viết blog.

6. Đưa ra quyết định retry theo từng loại lỗi

“Retry các job thất bại” không phải là một chính sách. Đó là một rủi ro về chi phí.

Chuẩn hóa lỗi thành các nhóm:

Phân biệt cuối cùng này đặc biệt quan trọng. Nếu video đã được tạo thành công nhưng việc sao chép vào bộ nhớ của bạn thất bại, việc tạo lại video sẽ tạo ra chi phí không cần thiết và có thể cho ra kết quả khác.

Thiết lập ngân sách retry cho mỗi job. Một chính sách hợp lý có thể cho phép nhiều lần kiểm tra trạng thái và thử sao chép lưu trữ hơn là số lần gửi tạo sinh.

7. Sao chép đầu ra vào bộ nhớ do bạn kiểm soát

Hãy coi bất kỳ URL kết quả nào do nhà cung cấp lưu trữ là vị trí chuyển tiếp, không phải tài sản sản phẩm lâu dài của bạn.

Sau khi một job thành công:

1. xác minh phản hồi chứa đúng kiểu media dự kiến
2. tải xuống với giới hạn kích thước và thời gian
3. xác thực rằng tệp không rỗng hoặc không bị cắt xén rõ ràng
4. tính checksum
5. sao chép nó vào object storage của bạn
6. lưu thời lượng, kích thước, codec và dung lượng
7. chỉ chuyển job của sản phẩm sang succeeded sau khi bản sao bền vững đã sẵn sàng

Nếu sản phẩm của bạn cho phép người dùng tải xuống tài sản gốc từ nhà cung cấp trước khi việc sao chép hoàn tất, hãy biểu diễn điều đó như một trạng thái tạm thời riêng biệt. Đừng âm thầm hứa hẹn tính lâu dài.

8. Thêm kiểm soát chi phí trước khi mở tính năng

Các job video đủ tốn kém để các giới hạn sản phẩm phải được thiết lập trước khi ra mắt công khai.

Tối thiểu, hãy xác định:

• một mức trần chi tiêu theo từng key hoặc từng nhóm
• một allowlist model cho application key
• số job đồng thời tối đa trên mỗi tài khoản
• thời lượng tối đa và cấu hình chất lượng theo gói
• giới hạn gửi yêu cầu hàng ngày cho tài khoản mới hoặc không đáng tin cậy
• một circuit breaker khi tỷ lệ lỗi hoặc chi phí trên mỗi lần thành công tăng lên

Tài liệu công khai của Flatkey mô tả các mức trần theo từng key, allowlist model tùy chọn và khả năng hiển thị mức sử dụng thông qua Usage & Logs hoặc ledger API. Hãy sử dụng các kiểm soát đó như rào chắn ở lớp truy cập, sau đó bổ sung hạn mức ở cấp sản phẩm dựa trên các gói của riêng bạn và rủi ro lạm dụng.

Trước khi bật một route mới, hãy so sánh danh mục hiện tại và bảng giá Flatkey. Không nhúng một mức giá số từ bài viết này vào logic ứng dụng; giá và khả năng sẵn có của route là dữ liệu có thể làm mới.

9. Đo lường toàn bộ job, không chỉ độ trễ API

Với quy trình Seedance API bất đồng bộ, một lần gửi thành công vẫn có thể tạo ra trải nghiệm khách hàng kém.

Theo dõi ít nhất:

• tỷ lệ chấp nhận gửi
• thời gian chờ hàng đợi
• thời gian tạo
• tổng thời gian để có đầu ra bền vững
• tỷ lệ thành công theo model đã phân giải
• tỷ lệ lỗi theo lớp lỗi đã chuẩn hóa
• độ trễ phân phối webhook
• tỷ lệ khôi phục khi polling
• tỷ lệ lỗi sao chép lưu trữ
• chi phí cho mỗi job đã gửi
• chi phí cho mỗi đầu ra bền vững thành công
• số lần ngăn chặn gửi trùng lặp

Hãy dùng các phân vị, không chỉ dùng trung bình. Thời gian tạo ở mức trung vị có thể trông ổn trong khi mười phần trăm job chậm nhất lại tạo ra phần lớn phiếu hỗ trợ.

Đồng thời ghi riêng requestedModel và resolvedModel. Điều đó giúp các thay đổi route trở nên hữu hình và cung cấp bằng chứng cho quyết định rollback.

10. Triển khai thay đổi model như các migration

Thay đổi catalog không chỉ đơn thuần là thay thế chuỗi. Hãy coi nó như một lần nâng cấp phụ thuộc.

Trước khi chuyển lưu lượng production sang một Seedance route mới:

1. xác nhận route hiện tại trong thư mục model trực tiếp
2. so sánh input được hỗ trợ và các ràng buộc đầu ra
3. chạy một bộ đánh giá cố định trên các kiểu prompt phổ biến của bạn
4. so sánh tỷ lệ thành công, độ trễ, mức độ chấp nhận đầu ra và chi phí
5. kiểm thử webhook, polling và chuẩn hóa lỗi
6. canary một tỷ lệ lưu lượng nhỏ
7. giữ nguyên route rollback cho đến khi canary ổn định
8. cập nhật allowlist model và sổ tay vận hành

Nếu ứng dụng của bạn hiển thị một thiết lập “chất lượng”, hãy ánh xạ nó tới một hồ sơ năng lực thay vì một model ID cố định. Điều đó cho phép bạn thay đổi route nền mà không làm hỏng API sản phẩm.

Danh sách kiểm tra sẵn sàng sản xuất

Dùng danh sách này như một điểm chặn phát hành.

Yêu cầu và truy cập

• [ ] API key vẫn ở phía server
• [ ] application key có giới hạn chi tiêu và allowlist model
• [ ] mọi request đều có job ID nội bộ và idempotency key
• [ ] input được xác thực trước khi gửi
• [ ] route model Seedance hiện tại được kiểm tra trên catalog trực tiếp

Thực thi bất đồng bộ

• [ ] logic đặc thù của nhà cung cấp nằm trong một adapter duy nhất
• [ ] trạng thái sản phẩm sử dụng một state machine đã chuẩn hóa
• [ ] sự kiện webhook được xác thực khi được hỗ trợ và loại bỏ trùng lặp
• [ ] polling đối soát các job không kết thúc còn cũ
• [ ] sự kiện đến muộn hoặc trùng lặp không thể đảo ngược trạng thái kết thúc

Độ tin cậy và chi phí

• [ ] hành vi retry thay đổi theo lớp lỗi
• [ ] retry tạo sinh có ngân sách nghiêm ngặt
• [ ] retry sao chép đầu ra không tái tạo lại video đã thành công
• [ ] giới hạn đồng thời và giới hạn job hằng ngày được thực thi
• [ ] circuit breaker có thể tạm dừng một route bị suy giảm

Đầu ra và khả năng quan sát

• [ ] video thành công được sao chép sang bộ nhớ lưu trữ được kiểm soát
• [ ] metadata đầu ra và checksum được lưu trữ
• [ ] ID mô hình được yêu cầu và ID đã được phân giải được ghi log
• [ ] chi phí trên mỗi đầu ra bền vững thành công được đo lường
• [ ] người vận hành có runbook cho các job bị kẹt, thất bại và bị trùng lặp

Flatkey phù hợp ở đâu

Flatkey không loại bỏ nhu cầu về một lớp job video bất đồng bộ. Nó giảm bớt công việc truy cập và quản trị xung quanh lớp đó: một tài khoản, một số dư, kiểm soát API key, một bề mặt router ổn định, một danh mục mô hình trực tiếp, và các bản ghi sử dụng tập trung.

Với lần tích hợp đầu tiên, hãy bắt đầu với hướng dẫn nhanh Seedance API cho các nhóm sản phẩm text-to-video rộng hơn. Khi tính năng tiến gần đến production, áp dụng danh sách kiểm tra này cho các lớp queue, state, retry, storage, và observability xung quanh lời gọi mô hình.

Nếu nhóm của bạn đang quyết định route hiện tại và các kiểm soát sử dụng nào phù hợp với đợt triển khai, hãy xem các mô hình trực tiếp và giá trước khi phê duyệt cấu hình production.

Các câu hỏi thường gặp

Seedance API là đồng bộ hay bất đồng bộ?

Hãy coi việc tạo video là một job bất đồng bộ. Sản phẩm của bạn nên gửi công việc, trả về ID job riêng của nó, và xử lý các cập nhật trạng thái thông qua webhook và/hoặc polling theo tài liệu API hiện tại.

Tôi có nên dùng provider task ID làm khóa chính của cơ sở dữ liệu không?

Không. Hãy tạo ID job ổn định của riêng bạn trước khi gửi. Lưu provider task ID như một tham chiếu bên ngoài để bạn có thể đối soát, gửi lại, hoặc thay đổi route mà không phải thay đổi định danh sản phẩm.

Tôi có cần cả webhook và polling không?

Đối với một hệ thống production bền vững, có. Webhook cung cấp cập nhật nhanh; polling khôi phục các job có sự kiện bị chậm, bị bỏ lỡ, hoặc không được xử lý.

Khi nào thì an toàn để thử lại một Seedance job đã thất bại?

Chỉ thử lại sau khi đã phân loại lỗi. Lỗi năng lực và mạng có thể có thể thử lại. Lỗi xác thực, xác thực danh tính, an toàn, hoặc các lỗi kết thúc khác thường cần thay đổi cấu hình hoặc thay đổi từ người dùng. Nếu việc gửi hết thời gian chờ, hãy đối soát bằng idempotency key trước khi gửi một job trả phí khác.

Tôi có nên tự lưu trữ video được tạo ra không?

Có. Sao chép đầu ra đã hoàn thành vào bộ nhớ lưu trữ do bạn kiểm soát, xác thực tệp, và lưu metadata của nó. Các URL kết quả do provider lưu trữ không nên được coi là bộ nhớ lưu trữ sản phẩm vĩnh viễn trừ khi điều khoản hiện tại nêu rõ ràng đảm bảo hành vi đó.

Tôi nên xử lý một phiên bản mô hình Seedance mới như thế nào?

Hãy coi đó là một lần di chuyển: xác minh danh mục hiện tại, chạy một bộ đánh giá cố định, so sánh chất lượng, độ trễ, lỗi, và chi phí, canary traffic, và giữ một route rollback cho đến khi thay đổi ổn định.

Tôi nên hardcode mô hình Seedance nào?

Tránh mã hóa cứng vĩnh viễn một model dựa trên một bài viết tĩnh. Hãy ánh xạ một hồ sơ năng lực sản phẩm tới một model được liệt kê trong thư mục model Flatkey hiện tại, và giữ tuyến đã chọn trong cấu hình để người vận hành có thể thay đổi an toàn.