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ợ bao gồm seedance-2.0 và seedance-2.0-fast. 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. Dùng "seedance-2.0" hoặc "seedance-2.0-fast".

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, URL hình ảnh, hoặc URL video.

string

Độ phân giải đầu ra: "480p", "720p", hoặc "1080p".

string

Tỷ lệ khung hình đầu ra: "16:9", "4:3", "1:1", "3:4", "9:16", "21:9", hoặc "adaptive".

integer

Thời lượng video từ 4 đến 15 giây. Dùng -1 để để mô hình tự chọn.

integer

Seed ngẫu nhiên. Bỏ qua để dùng seed ngẫu nhiên.

boolean

Có thêm hình mờ hay không. Mặc định: false.

boolean

Có tạo âm thanh đồng bộ hay không.

Các mục `content`

`type`	Trường giá trị	`role` được hỗ trợ	Mục đích
`text`	`text`	—	Prompt văn bản. Nhiều mục văn bản được ghép theo thứ tự.
`image_url`	`image_url.url`	`first_frame`, `last_frame`, `reference_image`	Hình ảnh đầu vào hoặc tham chiếu. Tối đa 9 hình ảnh.
`video_url`	`video_url.url`	`reference_video`	Video tham chiếu. Tối đa 3 video.
`audio_url`	`audio_url.url`	`reference_audio`	Âm thanh tham chiếu. Tối đa 3 đoạn.

Nếu một hình ảnh dùng role first_frame hoặc last_frame, API sẽ sử dụng chế độ khung đầu/cuối. Các hình ảnh khác được coi là tham chiếu.

Tham số nâng cao

string

Chế độ đầu vào tường minh: "reference" hoặc "first_last_frame". Bỏ qua để suy ra chế độ từ content.

boolean

Bật tính năng tăng cường tìm kiếm web cho tác vụ.

object

Nâng cấp độ phân giải video đã tạo trong khi vẫn giữ nguyên ID tác vụ công khai.

Hiện Các trường super_resolution_config

string

Độ phân giải đích: "720p", "1080p", "2k", hoặc "4k". Phải cao hơn độ phân giải gốc và không thể kết hợp với resolution_limit.

integer

Giới hạn pixel cạnh ngắn tùy chỉnh từ 64 đến 2160. Không thể kết hợp với resolution.

string

Cảnh nâng cấp: "aigc", "short_series", "ugc", hoặc "old_film".

string

Chế độ nâng cấp: "standard" (mặc định) hoặc "professional".

integer

Tốc độ khung hình đầu ra từ 1 đến 120. Các giá trị cao hơn tốc độ khung hình nguồn sẽ bật nội suy khung hình.

camera_fixed, frames, callback_url, và return_last_frame được chấp nhận để tương thích nhưng hiện tại không có tác dụng.

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
}

Tham chiếu đa phương thức với nâng cấp độ phân giải

{
  "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,
  "super_resolution_config": {
    "resolution": "4k",
    "scene": "aigc",
    "tool_version": "professional",
    "fps": 60
  }
}

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"
  },
  "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": "video_generation_failed"
  }
}

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.

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. 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.
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

​Tham số nâng cao

​Ví dụ yêu cầu

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

​Tham chiếu đa phương thức với nâng cấp độ phân giải

​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

​Tải video

​Lỗi

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

Endpoint

Yêu cầu

Header

Tham số body

Các mục `content`

Tham số nâng cao

Ví dụ yêu cầu

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

Tham chiếu đa phương thức với nâng cấp độ phân giải

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

Tải video

Lỗi

Ví dụ đầu-cuối