Tạo Video Seedance — POST /v1/videos

Dùng POST /v1/videos để tạo một tác vụ tạo video Seedance bất đồng bộ. Theo dõi tác vụ cho đến khi hoàn thành, sau đó tải video từ URL Flatkey được trả về. Các mô hình được hỗ trợ gồm seedance-2.0, seedance-2.0-fast, seedance-2.0-mini và seedance-2.5. Tính khả dụng phụ thuộc vào tài khoản của bạn; dùng GET /v1/models để lấy danh sách mô hình hiện tại.

Endpoint

POST https://router.flatkey.ai/v1/videos

Flatkey cũng chấp nhận POST /v1/video/generations và GET /v1/video/generations/{task_id}. Dùng /v1/videos để có cấu trúc phản hồi chuẩn và dữ liệu usage gốc.

Yêu cầu

Header	Giá trị
`Authorization`	`Bearer $FLATKEY_API_KEY`
`Content-Type`	`application/json`

Tham số body

string

bắt buộc

ID mô hình Seedance: "seedance-2.0", "seedance-2.0-fast", "seedance-2.0-mini" hoặc "seedance-2.5".

array

bắt buộc

Các mục đầu vào đa phương thức. Bao gồm ít nhất một mục văn bản không rỗng, hình ảnh, video hoặc âm thanh. Xem các mục content.

string

Độ phân giải đầu ra. Mặc định: "720p".

Mô hình	Giá trị được hỗ trợ
`seedance-2.0`	`"480p"`, `"720p"`, `"1080p"`, `"4k"`
`seedance-2.0-fast`, `seedance-2.0-mini`	`"480p"`, `"720p"`
`seedance-2.5`	`"480p"`, `"720p"`, `"1080p"`

string

Tỷ lệ khung hình đầu ra: "16:9", "4:3", "1:1", "3:4", "9:16", "21:9" hoặc "adaptive". Mặc định: "adaptive". Với "adaptive", mô hình tự chọn tỷ lệ dựa trên hình ảnh hoặc video đầu vào. Với seedance-2.5, các tác vụ khung đầu và khung đầu/cuối chỉ hỗ trợ "adaptive".

integer

Thời lượng video tính bằng giây. Mặc định: 5. Các mô hình Seedance 2.0 chấp nhận từ 4 đến 15; seedance-2.5 chấp nhận từ 4 đến 30.

Luôn gửi duration là số dương. Flatkey tính phí Seedance theo giây, nên -1 (để mô hình tự chọn thời lượng) sẽ bị từ chối với video_price_not_configured. Ngoại lệ duy nhất là chỉnh sửa video với seedance-2.5, vốn bắt buộc dùng -1.

boolean

Thêm hình mờ “AI generated” vào góc dưới bên phải. Mặc định: false.

boolean

Tạo một bản âm thanh mono đồng bộ. Mặc định: true. Đặt thành false nếu bạn chỉ cần video; âm thanh được tạo đôi khi có thể không vượt qua kiểm tra bản quyền.

boolean

Trả về khung hình cuối cùng của video đã tạo dưới dạng hình ảnh. Mặc định: false. Khi là true, tác vụ đã hoàn thành sẽ có metadata.last_frame_url, dùng để tải một ảnh JPEG cùng kích thước với video và không có hình mờ. Dùng ảnh này làm first_frame cho tác vụ tiếp theo để nối các clip. Giống như metadata.url, URL này không cần header xác thực; hãy giữ nó ở chế độ riêng tư.

string

Chỉ dành cho seedance-2.5. Định dạng container của video được tạo: "mp4" hoặc "mov". Mặc định: "mp4". MOV giữ độ chính xác màu cao hơn cho chỉnh màu và ghép hình (H.264, YUV 4:4:4, âm thanh PCM), nhưng một số trình phát không mở được. Endpoint nội dung trả về video/quicktime cho kết quả MOV.

string

Chỉ dành cho seedance-2.5, áp dụng cho tác vụ ở chế độ tham chiếu. Cho mô hình biết bạn muốn thực hiện tác vụ nào: "auto" (mặc định), "reference", "edit" hoặc "extend". Khi đặt rõ giá trị này, các bước kiểm tra loại tác vụ được chuyển lên lúc gửi yêu cầu, nên một tổ hợp không hợp lệ sẽ thất bại ngay thay vì sau khi tác vụ đã bắt đầu. "reference", "edit" và "extend" đều cần các mục tham chiếu trong content; yêu cầu chỉ có văn bản mà dùng "reference" sẽ bị từ chối. Xem chỉnh sửa và kéo dài video.

integer

Mức ưu tiên trong hàng đợi, từ 0 đến 9. Mặc định: 0. Giá trị cao hơn đưa tác vụ lên trước các tác vụ có mức ưu tiên thấp hơn đang chờ cùng mô hình. Được hỗ trợ trên tất cả các mô hình Seedance 2.0 và seedance-2.5. Giá trị ngoài khoảng 0–9 sẽ bị từ chối với 400.

integer

Số giây tác vụ được phép chờ và chạy trước khi hết hạn. Mặc định: 172800 (48 giờ). Hãy dùng giá trị ngắn hơn khi kết quả đến muộn không còn hữu ích với bạn.

string

URL HTTPS công khai nhận một yêu cầu POST mỗi khi trạng thái tác vụ thay đổi. Xem Callback tác vụ. URL phải dùng https, không chứa thông tin đăng nhập của người dùng, dài tối đa 2.048 ký tự và phân giải tới một địa chỉ công khai; nếu không, yêu cầu sẽ bị từ chối với 400.

Các mục `content`

`type`	Trường giá trị	`role` được hỗ trợ	Giới hạn
`text`	`text`	—	Văn bản prompt. Nên giữ dưới khoảng 1.000 từ tiếng Anh.
`image_url`	`image_url.url`	`first_frame`, `last_frame`, `reference_image`	Tối đa 9 hình ảnh tham chiếu (`seedance-2.5`: 30). JPEG, PNG, WebP, BMP, TIFF, GIF, HEIC hoặc HEIF; dưới 30 MB; mỗi cạnh 300–6000 px; tỷ lệ khung hình 0,4–2,5.
`video_url`	`video_url.url`	`reference_video`	Tối đa 3 video, mỗi video 2–15 giây và tổng cộng 15 giây (`seedance-2.5`: 10 video, 30 giây). MP4 hoặc MOV; dưới 200 MB; tổng số pixel tối thiểu khoảng 409.600 (ví dụ 854×480).
`audio_url`	`audio_url.url`	`reference_audio`	Tối đa 3 đoạn, mỗi đoạn 2–15 giây và tổng cộng 15 giây (`seedance-2.5`: 10 đoạn, 30 giây). WAV hoặc MP3; dưới 15 MB. Các mô hình Seedance 2.0 cần ít nhất một hình ảnh hoặc video đi kèm với âm thanh.

Mỗi URL có thể là một URL HTTPS công khai, một data URI dạng data:<mime>;base64, (chỉ áp dụng cho hình ảnh và âm thanh), hoặc một tham chiếu asset:// từ thư viện tài sản. Toàn bộ body của yêu cầu phải nhỏ hơn 64 MB. Chọn một chế độ đầu vào cho mỗi tác vụ. Không thể kết hợp các chế độ này:

Chế độ	Cách tạo `content`
Khung đầu	Một hình ảnh với `role: "first_frame"`.
Khung đầu và khung cuối	Hai hình ảnh, một với `role: "first_frame"` và một với `role: "last_frame"`. `last_frame` luôn cần có `first_frame`, và cả hai đều không thể kết hợp với các mục tham chiếu.
Tham chiếu	Bất kỳ tổ hợp nào của các mục `reference_image`, `reference_video` và `reference_audio`.

Chỉnh sửa video

seedance-2.5 có thể chỉnh sửa hoặc kéo dài một video có sẵn ở chế độ tham chiếu. Mô tả thay đổi trong prompt và gọi video đó là @Video1.

Tác vụ	Thiết lập bắt buộc	Thời lượng đầu ra
Chỉnh sửa (thay thế chủ thể, thêm hoặc xóa đối tượng, thay đổi âm thanh)	Ít nhất một `reference_video` dài 4–30 giây, `ratio: "adaptive"`, `duration: -1`. Khuyến nghị: `omni_reference_task_type: "edit"`.	Bằng thời lượng của video đầu vào được chỉnh sửa
Kéo dài (nối tiếp video về phía trước hoặc phía sau)	Ít nhất một `reference_video`, `ratio: "adaptive"`, `duration` là số dương. Khuyến nghị: `omni_reference_task_type: "extend"`.	`duration`

{
  "model": "seedance-2.5",
  "resolution": "720p",
  "ratio": "adaptive",
  "duration": -1,
  "omni_reference_task_type": "edit",
  "content": [
    { "type": "text", "text": "Edit @Video1: make the ball bright green and keep everything else unchanged." },
    { "type": "video_url", "video_url": { "url": "https://example.com/input.mp4" }, "role": "reference_video" }
  ]
}

Giống như mọi yêu cầu seedance-2.5 có video tham chiếu, một tác vụ chỉnh sửa được tính phí theo đơn giá có video của độ phân giải tương ứng cho cố định 30 giây, bất kể thời lượng đầu vào hay đầu ra.

Chế độ bản nháp

seedance-2.5 có thể tạo trước một bản nháp 480p giá rẻ để bạn kiểm tra bối cảnh, các cảnh quay và chuyển động trước khi trả tiền cho video chính thức. Quy trình gồm hai yêu cầu:

Tạo bản nháp. Gửi một yêu cầu bình thường với "draft": true và "resolution": "480p". Yêu cầu này được tính phí như một video 480p thông thường.
Tạo video chính thức. Sau khi bản nháp hoàn thành, gửi một yêu cầu có mục content duy nhất là một draft_task trỏ tới ID tác vụ của bản nháp, kèm "resolution": "1080p".

{
  "model": "seedance-2.5",
  "resolution": "1080p",
  "content": [
    { "type": "draft_task", "draft_task": { "id": "task_3f9a00000000000000000000000000e2" } }
  ]
}

Video chính thức dùng lại prompt, nội dung đa phương tiện, thời lượng, tỷ lệ khung hình, seed, thiết lập âm thanh và loại tác vụ của bản nháp. Không gửi duration, ratio, frames, seed, generate_audio, omni_reference_task_type, draft hoặc bất kỳ mục content nào khác cùng với draft_task; yêu cầu sẽ bị từ chối với 400. Bạn vẫn có thể đặt return_last_frame, output_format, watermark, priority, execution_expires_after và callback_url.

Quy tắc	Chi tiết
Mô hình	`model` phải giống với bản nháp.
ID tác vụ bản nháp	Dùng ID `task_…` mà Flatkey trả về cho bản nháp. Tác vụ đó phải thuộc về bạn và đã hoàn thành.
Độ phân giải	Bản nháp: chỉ `480p`. Video chính thức: chỉ `1080p`.
Thời hạn	Bản nháp có thể được dùng trong 7 ngày kể từ khi tạo.
Tính phí	Video chính thức được tính phí theo đơn giá 1080p cho thời lượng của bản nháp. Nếu bản nháp dùng video tham chiếu, áp dụng đơn giá có video cho cố định 30 giây.

Seedance không chấp nhận trực tiếp hình ảnh hoặc video có khuôn mặt người thật. Hãy tải chúng lên dưới dạng tài sản người thật và tham chiếu bằng asset://.

Ví dụ yêu cầu

import os
import requests

response = requests.post(
    "https://router.flatkey.ai/v1/videos",
    headers={
        "Authorization": f"Bearer {os.environ['FLATKEY_API_KEY']}",
        "Content-Type": "application/json",
    },
    json={
        "model": "seedance-2.0",
        "content": [
            {
                "type": "text",
                "text": "An astronaut walking on the moon, cinematic lighting, slow camera push-in",
            }
        ],
        "resolution": "1080p",
        "ratio": "16:9",
        "duration": 5,
    },
)
response.raise_for_status()
print(response.json())

const response = await fetch("https://router.flatkey.ai/v1/videos", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.FLATKEY_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "seedance-2.0",
    content: [
      {
        type: "text",
        text: "An astronaut walking on the moon, cinematic lighting, slow camera push-in",
      },
    ],
    resolution: "1080p",
    ratio: "16:9",
    duration: 5,
  }),
});

if (!response.ok) throw new Error(await response.text());
console.log(await response.json());

curl https://router.flatkey.ai/v1/videos \
  -H "Authorization: Bearer $FLATKEY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2.0",
    "content": [
      {
        "type": "text",
        "text": "An astronaut walking on the moon, cinematic lighting, slow camera push-in"
      }
    ],
    "resolution": "1080p",
    "ratio": "16:9",
    "duration": 5
  }'

Đầu vào khung đầu và khung cuối

{
  "model": "seedance-2.0",
  "content": [
    { "type": "text", "text": "The camera slowly moves forward" },
    {
      "type": "image_url",
      "image_url": { "url": "https://example.com/first.jpg" },
      "role": "first_frame"
    },
    {
      "type": "image_url",
      "image_url": { "url": "https://example.com/last.jpg" },
      "role": "last_frame"
    }
  ],
  "resolution": "720p",
  "ratio": "16:9",
  "duration": 5,
  "generate_audio": false
}

Tham chiếu đa phương thức

{
  "model": "seedance-2.0",
  "content": [
    { "type": "text", "text": "A woman smiles at the camera during a beach sunset" },
    {
      "type": "image_url",
      "image_url": { "url": "https://example.com/reference.jpg" },
      "role": "reference_image"
    }
  ],
  "resolution": "1080p",
  "ratio": "16:9",
  "duration": 5,
  "watermark": false
}

Phản hồi

{
  "id": "task_3f9a00000000000000000000000000e2",
  "task_id": "task_3f9a00000000000000000000000000e2",
  "object": "video",
  "model": "seedance-2.0",
  "status": "queued",
  "progress": 0,
  "created_at": 1780306574
}

Các trường phản hồi

string

ID tác vụ công khai dùng để theo dõi tác vụ và tải video đã hoàn thành. task_id chứa cùng giá trị.

string

Trạng thái tác vụ: queued, in_progress, completed, hoặc failed.

integer

Tiến độ tạo từ 0 đến 100.

integer

Dấu thời gian Unix khi tạo tác vụ.

Theo dõi trạng thái tác vụ

GET https://router.flatkey.ai/v1/videos/{task_id}

curl https://router.flatkey.ai/v1/videos/task_3f9a00000000000000000000000000e2 \
  -H "Authorization: Bearer $FLATKEY_API_KEY"

Trong khi đang tạo, phản hồi bao gồm tiến độ hiện tại:

{
  "id": "task_3f9a00000000000000000000000000e2",
  "object": "video",
  "status": "in_progress",
  "progress": 50,
  "model": "seedance-2.0",
  "created_at": 1780306574
}

Khi tác vụ hoàn thành, phản hồi bao gồm URL video và thông tin sử dụng token:

{
  "id": "task_3f9a00000000000000000000000000e2",
  "object": "video",
  "status": "completed",
  "progress": 100,
  "model": "seedance-2.0",
  "usage": {
    "completion_tokens": 120,
    "total_tokens": 120
  },
  "metadata": {
    "url": "https://router.flatkey.ai/v1/videos/task_3f9a00000000000000000000000000e2/content",
    "last_frame_url": "https://router.flatkey.ai/v1/videos/task_3f9a00000000000000000000000000e2/last-frame"
  },
  "created_at": 1780306574,
  "completed_at": 1780306750
}

Các tác vụ thất bại trả về chi tiết lỗi kèm theo phản hồi tác vụ:

{
  "id": "task_3f9a00000000000000000000000000e2",
  "object": "video",
  "status": "failed",
  "error": {
    "message": "The video generation task failed.",
    "code": ""
  }
}

Bất kỳ số dư đã tiêu trước nào sẽ được hoàn lại tự động.

Các giá trị trạng thái

Trạng thái	Ý nghĩa
`queued`	Tác vụ đang chờ bắt đầu.
`in_progress`	Video đang được tạo. `progress` dao động từ 0 đến 100.
`completed`	Video đã sẵn sàng tại `metadata.url`, và thông tin sử dụng token có trong `usage`.
`failed`	Quá trình tạo thất bại. Chi tiết có trong `error.message`, và bất kỳ số dư đã tiêu trước nào sẽ được hoàn lại.

Callback tác vụ

Đặt callback_url để nhận các thay đổi trạng thái thay cho việc theo dõi tác vụ, hoặc song song với việc đó. Flatkey gửi một yêu cầu POST với Content-Type: application/json khi tác vụ chuyển sang in_progress, completed hoặc failed. Body chính là nội dung mà GET /v1/videos/{task_id} trả về tại thời điểm đó, bao gồm metadata.url và metadata.last_frame_url với các tác vụ đã hoàn thành.

{
  "id": "task_3f9a00000000000000000000000000e2",
  "object": "video",
  "status": "completed",
  "progress": 100,
  "model": "seedance-2.0",
  "usage": {
    "completion_tokens": 120,
    "total_tokens": 120
  },
  "metadata": {
    "url": "https://router.flatkey.ai/v1/videos/task_3f9a00000000000000000000000000e2/content"
  },
  "created_at": 1780306574,
  "completed_at": 1780306750
}

Header	Giá trị
`X-Flatkey-Event-Id`	`<task_id>:<status>`, ví dụ `task_3f9a…e2:completed`. Cùng một sự kiện có thể được gửi nhiều lần; hãy dùng header này để bỏ qua các bản trùng lặp.

Hãy phản hồi bằng bất kỳ mã trạng thái 2xx nào trong vòng 5 giây. Nếu không, Flatkey sẽ thử lại hai lần, sau 2 và 8 giây, rồi dừng hẳn. Flatkey không đi theo chuyển hướng (redirect). Callback không được ký, vì vậy hãy xác minh kết quả bằng cách truy vấn tác vụ trước khi xử lý, và luôn lấy việc theo dõi tác vụ làm nguồn dữ liệu chuẩn phòng khi một callback bị mất.

Tải video

GET https://router.flatkey.ai/v1/videos/{task_id}/content

curl -L "https://router.flatkey.ai/v1/videos/task_3f9a00000000000000000000000000e2/content" \
  -o output.mp4

Endpoint nội dung truyền dữ liệu video/mp4, hoặc video/quicktime khi tác vụ dùng output_format: "mov". Nó không yêu cầu Bearer token và có thể dùng trực tiếp làm nguồn cho thẻ <video>.

Endpoint nội dung chỉ hoạt động sau khi tác vụ hoàn thành và bị giới hạn tốc độ theo IP client. Hãy coi URL là thông tin nhạy cảm vì bất kỳ ai có URL đó đều có thể tải video.

Lỗi

Các lỗi tại thời điểm yêu cầu dùng phong bì lỗi chuẩn của Flatkey:

{
  "error": {
    "message": "...",
    "type": "...",
    "code": "..."
  }
}

Tình huống	Hành vi
`content` rỗng	Yêu cầu bị từ chối. Hãy bao gồm văn bản không rỗng, hình ảnh, hoặc video.
Mô hình không khả dụng	`model` được yêu cầu không được bật cho route này.
Số dư không đủ	Tác vụ không được tạo.
`priority` ngoài khoảng 0–9	Yêu cầu trả về `400` với `invalid_request`.
`callback_url` không hợp lệ	Yêu cầu trả về `400` với `invalid_request` khi URL không phải HTTPS, chứa thông tin đăng nhập, dài hơn 2.048 ký tự, hoặc trỏ tới một địa chỉ riêng tư hay cục bộ.
`duration: -1` ngoài tác vụ chỉnh sửa video với `seedance-2.5`	Yêu cầu trả về `400` với `video_price_not_configured`.
Đầu vào không hợp lệ cho mô hình	Yêu cầu trả về `400` với `fail_to_fetch_task`, hoặc với các yêu cầu dùng tham chiếu `asset://`, tác vụ thất bại với `task preparation failed`. Hãy kiểm tra độ phân giải, thời lượng, giới hạn nội dung và các quy tắc chế độ đầu vào ở trên. Bạn không bị tính phí.
Lỗi dịch vụ tạm thời	Thử lại sau theo chính sách backoff thông thường của bạn.

Ví dụ đầu-cuối

Ví dụ này tạo một tác vụ, theo dõi mỗi năm giây, và tải video đã hoàn thành. Yêu cầu cài đặt jq.

#!/usr/bin/env bash
set -euo pipefail

BASE="https://router.flatkey.ai"
: "${FLATKEY_API_KEY:?Set FLATKEY_API_KEY before running this script}"

RESPONSE=$(curl -sS "$BASE/v1/videos" \
  -H "Authorization: Bearer $FLATKEY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2.0",
    "content": [
      { "type": "text", "text": "An astronaut walking on the moon, cinematic lighting" }
    ],
    "resolution": "1080p",
    "ratio": "16:9",
    "duration": 5
  }')

TASK_ID=$(echo "$RESPONSE" | jq -r '.id')
echo "task: $TASK_ID"

while true; do
  RESULT=$(curl -sS "$BASE/v1/videos/$TASK_ID" \
    -H "Authorization: Bearer $FLATKEY_API_KEY")
  STATUS=$(echo "$RESULT" | jq -r '.status')
  echo "status: $STATUS"

  [ "$STATUS" = "completed" ] && break
  if [ "$STATUS" = "failed" ]; then
    echo "failed: $(echo "$RESULT" | jq -r '.error.message')" >&2
    exit 1
  fi
  sleep 5
done

VIDEO_URL=$(echo "$RESULT" | jq -r '.metadata.url')
curl -L "$VIDEO_URL" -o output.mp4
echo "saved -> output.mp4"

​Endpoint

​Yêu cầu

​Header

​Tham số body

​Các mục content

​Chỉnh sửa video

​Chế độ bản nháp

​Ví dụ yêu cầu

​Đầu vào khung đầu và khung cuối

​Tham chiếu đa phương thức

​Phản hồi

​Các trường phản hồi

​Theo dõi trạng thái tác vụ

​Các giá trị trạng thái

​Callback tác vụ

​Tải video

​Lỗi

​Ví dụ đầu-cuối

Endpoint

Yêu cầu

Header

Tham số body

Các mục `content`

Chỉnh sửa video

Chế độ bản nháp

Ví dụ yêu cầu

Đầu vào khung đầu và khung cuối

Tham chiếu đa phương thức

Phản hồi

Các trường phản hồi

Theo dõi trạng thái tác vụ

Các giá trị trạng thái

Callback tác vụ

Tải video

Lỗi

Ví dụ đầu-cuối