Nếu đội ngũ sản phẩm của bạn muốn có cách nhanh nhất và an toàn nhất để đánh giá quyền truy cập Seedance API, bước đầu tiên đúng đắn không phải là xây dựng toàn bộ quy trình video ngay từ ngày đầu. Thay vào đó, hãy chứng minh ba điều cơ bản với bề mặt tích hợp nhỏ nhất có thể:
- khóa Flatkey của bạn xác thực chính xác
- ứng dụng của bạn có thể gọi
https://router.flatkey.ai/v1 - đội ngũ của bạn có thể nhìn thấy yêu cầu trong Usage Logs trước khi bạn nối các tác vụ video bất đồng bộ
Đó là quickstart ít cản trở mà trang này đề cập.
Tính đến Thứ Sáu, ngày 17 tháng 7 năm 2026, hướng dẫn quickstart công khai của Flatkey vẫn yêu cầu các nhà phát triển dùng Bearer auth, base URL tương thích OpenAI https://router.flatkey.ai/v1, và POST /v1/chat/completions cho bài kiểm tra khói đầu tiên. Danh mục mô hình trực tiếp của Flatkey cũng công khai liệt kê seedance-2.5 cho text-to-video lẫn image-to-video, và seedance-2.0-i2v cho image-to-video. Trang API công khai của Seedance vẫn mô tả quy trình video là tạo tác vụ bất đồng bộ, thăm dò trạng thái, webhooks, và tín dụng dựa trên mức sử dụng.
Sự kết hợp đó rất quan trọng cho quá trình onboarding: mô hình truy cập qua router rất đơn giản, nhưng quy trình tạo video thực tế không phải là một lệnh chat đồng bộ. Các đội ngũ sản phẩm nên xác thực router trước bằng yêu cầu nhỏ nhất, sau đó chỉ thay đổi mô hình và luồng công việc mà họ cần cho việc đánh giá Seedance.
Trả lời ngắn
Hãy dùng trình tự này khi bạn muốn có một lộ trình onboarding Seedance có thể xem xét, với ít thành phần di chuyển nhất.
| Bước | Nên dùng gì | Nó chứng minh điều gì |
|---|---|---|
| Bước 1. Tạo khóa | Khóa API Flatkey bắt đầu bằng sk-fk- |
Đội ngũ của bạn có một thông tin xác thực hợp lệ |
| Bước 2. Đặt một base URL | https://router.flatkey.ai/v1 |
Ứng dụng của bạn trỏ tới router dùng chung, không phải endpoint riêng của nhà cung cấp |
| Bước 3. Chạy bài kiểm tra khói nhỏ nhất | POST /v1/chat/completions với một mô hình văn bản đơn giản |
Xác thực, headers, định tuyến, và Usage Logs hoạt động |
| Bước 4. Chuyển sang tuyến Seedance | Thay mô hình placeholder bằng ID mô hình Seedance đã được phê duyệt | Cùng lớp truy cập đó giờ có thể hỗ trợ quy trình đánh giá video của bạn |
| Bước 5. Thêm xử lý bất đồng bộ | Logic polling hoặc webhook cho các tác vụ video | Sản phẩm của bạn đã sẵn sàng cho việc thực thi text-to-video thực sự |
Nếu bạn chỉ nhớ một điều, hãy nhớ điều này: yêu cầu cURL đầu tiên là một kiểm tra kết nối router, không phải payload text-to-video cuối cùng.
Trước khi bắt đầu
Bạn cần bốn thứ:
- Một tài khoản Flatkey
- Một khóa API Flatkey
- Một ít credit trả trước cho yêu cầu
- Một quyết định của sản phẩm về tuyến Seedance mà bạn thực sự muốn đánh giá
Đối với hầu hết các đội ngũ text-to-video, danh mục mô hình công khai đủ rõ để bắt đầu cuộc trao đổi:
| Tín hiệu mô hình công khai hiện tại trên Flatkey | Cách dùng tốt nhất |
|---|---|
seedance-2.5 |
Đánh giá text-to-video, và cả image-to-video nếu cần |
seedance-2.0-i2v |
Chỉ image-to-video |
Đừng hardcode tên model từ một ảnh chụp màn hình cũ hoặc một ghi chú nội bộ. Hãy kiểm tra thư mục model hiện tại hoặc danh mục trực tiếp vào ngày phát hành, vì khả năng truy cập vào tuyến video có thể thay đổi nhanh hơn một hướng dẫn thiết lập tĩnh.
Step 1: tạo và lưu khóa API Flatkey
Trong Flatkey Console, tạo một khóa API và lưu nó dưới dạng biến môi trường.
export FLATKEY_API_KEY="sk-fk-..."
Đây là nơi đầu tiên các đội ngũ tạo ra sự cản trở không cần thiết. Hãy giữ khóa ở phía server, không đưa vào mã trình duyệt và không lưu trong một ghi chú cục bộ dùng chung. Nếu đánh giá dành cho một đội ngũ sản phẩm chứ không phải một kỹ sư, hãy dùng ngay một secret thuộc sở hữu của cả đội ngay từ đầu.
Step 2: chạy bài kiểm tra khởi động router nhỏ nhất có thể
Quickstart hiện tại của Flatkey dùng POST /v1/chat/completions cho yêu cầu đầu tiên. Đó là lựa chọn đúng ngay cả khi mục tiêu cuối cùng của bạn là tạo video Seedance, vì nó xác minh lớp truy cập dùng chung trước khi bạn thêm độ phức tạp của luồng công việc bất đồng bộ.
curl https://router.flatkey.ai/v1/chat/completions -H "Authorization: Bearer $FLATKEY_API_KEY" -H "Content-Type: application/json" -d '{
"model": "gpt-4o-mini",
"messages": [
{"role": "user", "content": "Reply with the word connected."}
]
}'
Một phản hồi thành công cho bạn biết ngay năm điều hữu ích:
- khóa API là hợp lệ
- header
Authorization: Bearer ...là đúng - base URL là đúng
- client của bạn có thể POST JSON thành công
- yêu cầu sẽ xuất hiện trong Flatkey Usage Logs với số lượng token và chi phí
Đó là bằng chứng tối thiểu có thể xem xét được rằng lớp truy cập đang hoạt động.
Step 3: hiểu chính xác yêu cầu smoke test đang kiểm tra điều gì
Smoke test chat-completions được thiết kế cố ý đơn giản. Cấu trúc bắt buộc là:
| Trường yêu cầu | Tại sao nó quan trọng |
|---|---|
header Authorization |
Xác nhận định dạng token Bearer |
Content-Type: application/json |
Xác nhận phần thân yêu cầu được phân tích đúng |
model |
Xác nhận tuyến có thể phân giải một model ID |
messages |
Xác nhận phần thân khớp với schema tương thích OpenAI |
Tài liệu chat-completions hiện tại của Flatkey cũng nêu ba trường phản hồi mà các đội ngũ sản phẩm thường kiểm tra đầu tiên:
choices[0].message.contentmodelusage
Trường cuối cùng này đặc biệt hữu ích cho quá trình onboarding, vì nó cung cấp cho đội ngũ sản phẩm và vận hành một nơi chung để xác minh rằng yêu cầu thực sự đã đi qua router.
Step 4: thay model placeholder bằng đánh giá Seedance
Sau khi smoke test chạy thành công, hãy giữ nguyên cùng thông tin xác thực và cùng base URL của router, rồi chỉ thay đổi những phần cụ thể cho quy trình video của bạn.
Giữ nguyên các phần sau:
Authorization: Bearer $FLATKEY_API_KEYhttps://router.flatkey.ai/v1- xử lý secret ở phía server của bạn
- quy trình xem xét log và thanh toán của bạn
Tiếp theo, thay đổi các phần sau:
| Những gì thay đổi sau smoke test | Vì sao nó thay đổi |
|---|---|
model |
Bạn thay model văn bản giữ chỗ bằng ID model Seedance đã được phê duyệt |
| Cấu trúc body của request | Tạo video cần các trường payload riêng, không chỉ một mảng messages của chat |
| Xử lý response | Luồng video trả về trạng thái job, tài nguyên, hoặc trạng thái bất đồng bộ thay vì chỉ văn bản ngay lập tức |
| Logic sản phẩm | Bạn cần polling hoặc webhook thay vì coi lời gọi như chat đồng bộ |
Đối với đánh giá sản phẩm text-to-video, placeholder an toàn trong ngày phát hành là:
seedance-2.5
Đối với đánh giá image-to-video, lộ trình công khai hiện tại là:
seedance-2.0-i2v
Hãy dùng những tên đó làm điểm khởi đầu để khám phá, chứ không phải là cam kết rằng mọi workflow downstream đều dùng cùng một cấu trúc payload giống hệt nhau.
Bước 5: thiết kế xoay quanh luồng video bất đồng bộ của Seedance
Đây là bước mà hầu hết quickstart bỏ qua.
Trang API công khai của Seedance vẫn mô tả workflow là:
- tạo tác vụ bất đồng bộ
- polling trạng thái
- webhook
- credit dựa trên mức sử dụng
Điều đó có nghĩa là một đội ngũ production nên giả định đường dẫn video thực tế cần ít nhất bốn trạng thái trong ứng dụng của riêng mình:
| Trạng thái job | Ứng dụng của bạn nên làm gì |
|---|---|
queued |
Ghi nhận job và hiển thị rằng yêu cầu đã được chấp nhận |
running |
Poll trạng thái hoặc chờ webhook |
succeeded |
Lấy output asset và gắn metadata |
failed |
Lưu lỗi và quyết định có retry hay không |
Nếu đội của bạn cố coi Seedance như một phản hồi chat đồng bộ, việc tích hợp sẽ có cảm giác không ổn định ngay cả khi API đang hoạt động bình thường.
Quy trình onboarding thực tế cho các đội ngũ sản phẩm
Nếu bạn muốn vòng đánh giá nhỏ nhất có thể, hãy dùng thứ tự này:
- Tạo khóa Flatkey.
- Chạy smoke test
chat/completions. - Xác minh request xuất hiện trong Usage Logs.
- Chọn ID model Seedance hiện tại mà bạn thực sự muốn test.
- Triển khai luồng request bất đồng bộ dành riêng cho Seedance.
- Thêm một đường polling hoặc một đường webhook trước khi mở rộng rollout.
Điều này giảm rủi ro onboarding vì bạn tách riêng xác minh router khỏi triển khai workflow video.
Xử lý sự cố
401 hoặc 403 từ request cURL đầu tiên
Thường có nghĩa là khóa không hợp lệ, đã hết hạn, hoặc không được truyền dưới dạng Bearer token.
Kiểm tra:
- khóa bắt đầu bằng
sk-fk- - biến shell thực sự đã được set
- header là
Authorization: Bearer ...
404 hoặc không khớp route
Thường có nghĩa là ứng dụng của bạn đang trỏ đến sai URL.
Sử dụng:
https://router.flatkey.ai/v1
Đừng trỏ request tới trang marketing hoặc bỏ hậu tố /v1.
Request thành công nhưng Usage Logs vẫn trống
Hướng dẫn bắt đầu nhanh của Flatkey nêu rõ hãy chờ vài giây rồi tìm lại. Nếu log vẫn không xuất hiện, hãy kiểm tra lại tên model, API key và base URL mà bạn thực sự đã gửi.
Smoke test chạy được nhưng quy trình Seedance thì không
Điều đó thường có nghĩa là lớp truy cập vẫn ổn và vấn đề hiện nằm ở một trong các chỗ sau:
- sai Seedance model ID
- sai định dạng payload video
- thiếu logic polling bất đồng bộ
- xử lý webhook chưa được triển khai
- mã sản phẩm đang giả định một phản hồi văn bản đồng bộ
Đó là tiến triển, không phải thất bại. Bạn đã cô lập được vấn đề ra khỏi xác thực và định tuyến.
Khi quickstart này là đủ
Quickstart này là đủ khi đội của bạn cần trả lời:
- Chúng ta có thể xác thực qua Flatkey không?
- Chúng ta có thể tái sử dụng đường dẫn client tương thích OpenAI hiện có không?
- Sản phẩm và ops có thể thấy request trong log không?
- Chúng ta có thể chuyển từ text smoke test sang một route Seedance mà chưa cần thêm key của nhà cung cấp khác trước không?
Nếu câu trả lời cho bốn câu hỏi đó là có, bước phê duyệt tiếp theo thường liên quan đến quy trình video bất đồng bộ và mô hình chi phí, chứ không phải kết nối cơ bản.
Nếu bạn cần xem phần giá trước khi triển khai, hãy xem tiếp trang giá trực tiếp của Flatkey để đội có thể phê duyệt việc đánh giá với cùng bề mặt tính phí sẽ dùng trong sản xuất.
Câu hỏi thường gặp
Cách nhanh nhất để kiểm tra quyền truy cập Seedance API qua Flatkey là gì?
Bắt đầu với smoke test POST /v1/chat/completions hiện tại của Flatkey để xác minh xác thực, base URL và Usage Logs. Sau khi thành công, thay model placeholder bằng Seedance model ID đã được phê duyệt hiện tại và xây dựng quy trình video bất đồng bộ.
Request cURL đầu tiên có tạo ra video không?
Không. Request cURL đầu tiên là một kiểm tra kết nối cho router dùng chung. Nó chứng minh key, headers, base URL và log của bạn hoạt động trước khi bạn thêm xử lý request dành riêng cho video.
Đội text-to-video nên bắt đầu với Seedance model nào?
Tính đến Thứ Sáu, ngày 17 tháng 7 năm 2026, danh mục model công khai của Flatkey liệt kê seedance-2.5 cho text-to-video và image-to-video. Hãy kiểm tra lại thư mục model hiện tại trước khi hardcode nó vào mã sản phẩm.
Đội image-to-video nên bắt đầu với Seedance model nào?
Tính đến Thứ Sáu, ngày 17 tháng 7 năm 2026, danh mục công khai của Flatkey liệt kê seedance-2.0-i2v cho image-to-video.
Tại sao luồng onboarding bắt đầu bằng chat completions thay vì một job video?
Vì request chat-completions là bằng chứng nhỏ nhất có thể cho thấy đường định tuyến tương thích OpenAI của bạn hoạt động. Nó tách các vấn đề về xác thực và logging ra khỏi các vấn đề của pipeline video.
Tôi nên kiểm tra gì trong phản hồi thành công đầu tiên?
Kiểm tra model, choices[0].message.content và usage, sau đó xác nhận cùng request đó xuất hiện trong Usage Logs.
Khi chuyển từ smoke test sang đánh giá Seedance thực tế thì điều gì thay đổi?
Key và base URL giữ nguyên. Model ID, body request và xử lý job bất đồng bộ sẽ thay đổi.
