> ## Documentation Index
> Fetch the complete documentation index at: https://docs.flatkey.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Tạo Video Seedance — POST /v1/videos

> Tạo tác vụ video Seedance với đầu vào văn bản và đa phương thức, theo dõi trạng thái và tải video đã hoàn thành qua Flatkey.

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`](/vi/api-reference/models) để lấy danh sách mô hình hiện tại.

## Endpoint

```http theme={"dark"}
POST https://router.flatkey.ai/v1/videos
```

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

## Yêu cầu

### Header

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

### Tham số body

<ParamField body="model" type="string" required>
  ID mô hình Seedance. Dùng `"seedance-2.0"` hoặc `"seedance-2.0-fast"`.
</ParamField>

<ParamField body="content" type="array" required>
  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.
</ParamField>

<ParamField body="resolution" type="string">
  Độ phân giải đầu ra: `"480p"`, `"720p"`, hoặc `"1080p"`.
</ParamField>

<ParamField body="ratio" type="string">
  Tỷ lệ khung hình đầu ra: `"16:9"`, `"4:3"`, `"1:1"`, `"3:4"`, `"9:16"`, `"21:9"`, hoặc `"adaptive"`.
</ParamField>

<ParamField body="duration" type="integer">
  Thời lượng video từ 4 đến 15 giây. Dùng `-1` để để mô hình tự chọn.
</ParamField>

<ParamField body="seed" type="integer">
  Seed ngẫu nhiên. Bỏ qua để dùng seed ngẫu nhiên.
</ParamField>

<ParamField body="watermark" type="boolean">
  Có thêm hình mờ hay không. Mặc định: `false`.
</ParamField>

<ParamField body="generate_audio" type="boolean">
  Có tạo âm thanh đồng bộ hay không.
</ParamField>

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

<ParamField body="input_type" type="string">
  Chế độ đầu vào tường minh: `"reference"` hoặc `"first_last_frame"`. Bỏ qua để suy ra chế độ từ `content`.
</ParamField>

<ParamField body="web_search" type="boolean">
  Bật tính năng tăng cường tìm kiếm web cho tác vụ.
</ParamField>

<ParamField body="super_resolution_config" type="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.

  <Expandable title="Các trường super_resolution_config">
    <ParamField body="resolution" type="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`.
    </ParamField>

    <ParamField body="resolution_limit" type="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`.
    </ParamField>

    <ParamField body="scene" type="string">
      Cảnh nâng cấp: `"aigc"`, `"short_series"`, `"ugc"`, hoặc `"old_film"`.
    </ParamField>

    <ParamField body="tool_version" type="string">
      Chế độ nâng cấp: `"standard"` (mặc định) hoặc `"professional"`.
    </ParamField>

    <ParamField body="fps" type="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.
    </ParamField>
  </Expandable>
</ParamField>

<Warning>
  `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.
</Warning>

## Ví dụ yêu cầu

<CodeGroup>
  ```python python theme={"dark"}
  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())
  ```

  ```javascript node theme={"dark"}
  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());
  ```

  ```bash curl theme={"dark"}
  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
    }'
  ```
</CodeGroup>

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

```json theme={"dark"}
{
  "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

```json theme={"dark"}
{
  "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

```json theme={"dark"}
{
  "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

<ResponseField name="id" type="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ị.
</ResponseField>

<ResponseField name="status" type="string">
  Trạng thái tác vụ: `queued`, `in_progress`, `completed`, hoặc `failed`.
</ResponseField>

<ResponseField name="progress" type="integer">
  Tiến độ tạo từ 0 đến 100.
</ResponseField>

<ResponseField name="created_at" type="integer">
  Dấu thời gian Unix khi tạo tác vụ.
</ResponseField>

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

```http theme={"dark"}
GET https://router.flatkey.ai/v1/videos/{task_id}
```

```bash theme={"dark"}
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:

```json theme={"dark"}
{
  "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:

```json theme={"dark"}
{
  "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ụ:

```json theme={"dark"}
{
  "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

```http theme={"dark"}
GET https://router.flatkey.ai/v1/videos/{task_id}/content
```

```bash theme={"dark"}
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>`.

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

## 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:

```json theme={"dark"}
{
  "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`](https://jqlang.github.io/jq/).

```bash theme={"dark"}
#!/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"
```