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

# Генерация видео Seedance — POST /v1/videos

> Создавайте задачи генерации видео Seedance с текстовыми и мультимодальными входными данными, опрашивайте их статус и скачивайте готовые видео через Flatkey.

Используйте `POST /v1/videos` для создания асинхронной задачи генерации видео Seedance. Опрашивайте задачу до её завершения, затем скачайте видео по возвращённому URL Flatkey.

Поддерживаемые модели: `seedance-2.0` и `seedance-2.0-fast`. Доступность зависит от вашего аккаунта; используйте [`GET /v1/models`](/ru/api-reference/models) для получения актуального списка моделей.

## Эндпоинт

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

<Note>
  Flatkey также принимает `POST /v1/video/generations` и `GET /v1/video/generations/{task_id}`. Используйте `/v1/videos` для стандартной структуры ответа и нативных данных `usage`.
</Note>

## Запрос

### Заголовки

| Заголовок       | Значение                  |
| --------------- | ------------------------- |
| `Authorization` | `Bearer $FLATKEY_API_KEY` |
| `Content-Type`  | `application/json`        |

### Параметры тела запроса

<ParamField body="model" type="string" required>
  Идентификатор модели Seedance. Используйте `"seedance-2.0"` или `"seedance-2.0-fast"`.
</ParamField>

<ParamField body="content" type="array" required>
  Мультимодальные входные элементы. Включите хотя бы один непустой текстовый элемент, URL изображения или URL видео.
</ParamField>

<ParamField body="resolution" type="string">
  Разрешение выходного видео: `"480p"`, `"720p"` или `"1080p"`.
</ParamField>

<ParamField body="ratio" type="string">
  Соотношение сторон выходного видео: `"16:9"`, `"4:3"`, `"1:1"`, `"3:4"`, `"9:16"`, `"21:9"` или `"adaptive"`.
</ParamField>

<ParamField body="duration" type="integer">
  Длительность видео от 4 до 15 секунд. Используйте `-1`, чтобы модель выбрала длительность самостоятельно.
</ParamField>

<ParamField body="seed" type="integer">
  Случайное начальное значение. Опустите для использования случайного значения.
</ParamField>

<ParamField body="watermark" type="boolean">
  Добавлять ли водяной знак. По умолчанию: `false`.
</ParamField>

<ParamField body="generate_audio" type="boolean">
  Генерировать ли синхронизированное аудио.
</ParamField>

### Элементы `content`

| `type`      | Поле значения   | Поддерживаемый `role`                          | Назначение                                                               |
| ----------- | --------------- | ---------------------------------------------- | ------------------------------------------------------------------------ |
| `text`      | `text`          | —                                              | Текстовый промпт. Несколько текстовых элементов объединяются по порядку. |
| `image_url` | `image_url.url` | `first_frame`, `last_frame`, `reference_image` | Входное или референсное изображение. До 9 изображений.                   |
| `video_url` | `video_url.url` | `reference_video`                              | Референсное видео. До 3 видео.                                           |
| `audio_url` | `audio_url.url` | `reference_audio`                              | Референсное аудио. До 3 клипов.                                          |

Если изображение использует роль `first_frame` или `last_frame`, API переходит в режим первого/последнего кадра. Остальные изображения обрабатываются как референсы.

### Дополнительные параметры

<ParamField body="input_type" type="string">
  Явный режим входных данных: `"reference"` или `"first_last_frame"`. Опустите, чтобы режим определялся автоматически на основе `content`.
</ParamField>

<ParamField body="web_search" type="boolean">
  Включить расширение задачи с помощью веб-поиска.
</ParamField>

<ParamField body="super_resolution_config" type="object">
  Увеличить разрешение сгенерированного видео, сохраняя тот же публичный идентификатор задачи.

  <Expandable title="Поля super_resolution_config">
    <ParamField body="resolution" type="string">
      Целевое разрешение: `"720p"`, `"1080p"`, `"2k"` или `"4k"`. Должно превышать исходное разрешение и не может сочетаться с `resolution_limit`.
    </ParamField>

    <ParamField body="resolution_limit" type="integer">
      Пользовательский предел пикселей по короткой стороне от 64 до 2160. Не может сочетаться с `resolution`.
    </ParamField>

    <ParamField body="scene" type="string">
      Сцена масштабирования: `"aigc"`, `"short_series"`, `"ugc"` или `"old_film"`.
    </ParamField>

    <ParamField body="tool_version" type="string">
      Режим масштабирования: `"standard"` (по умолчанию) или `"professional"`.
    </ParamField>

    <ParamField body="fps" type="integer">
      Частота кадров выходного видео от 1 до 120. Значения выше частоты кадров источника включают интерполяцию кадров.
    </ParamField>
  </Expandable>
</ParamField>

<Warning>
  `camera_fixed`, `frames`, `callback_url` и `return_last_frame` принимаются для совместимости, но в настоящее время не оказывают никакого эффекта.
</Warning>

## Примеры запросов

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

### Входные данные первого и последнего кадра

```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
}
```

### Мультимодальный референс с масштабированием разрешения

```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
  }
}
```

## Ответ

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

### Поля ответа

<ResponseField name="id" type="string">
  Публичный идентификатор задачи, используемый для опроса задачи и скачивания готового видео. `task_id` содержит то же значение.
</ResponseField>

<ResponseField name="status" type="string">
  Статус задачи: `queued`, `in_progress`, `completed` или `failed`.
</ResponseField>

<ResponseField name="progress" type="integer">
  Прогресс генерации от 0 до 100.
</ResponseField>

<ResponseField name="created_at" type="integer">
  Unix-метка времени создания задачи.
</ResponseField>

## Опрос статуса задачи

```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"
```

Пока идёт генерация, ответ содержит текущий прогресс:

```json theme={"dark"}
{
  "id": "task_3f9a00000000000000000000000000e2",
  "object": "video",
  "status": "in_progress",
  "progress": 50,
  "model": "seedance-2.0",
  "created_at": 1780306574
}
```

После завершения задачи ответ содержит URL видео и данные об использовании токенов:

```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
}
```

Для неудавшихся задач в ответе возвращаются детали ошибки:

```json theme={"dark"}
{
  "id": "task_3f9a00000000000000000000000000e2",
  "object": "video",
  "status": "failed",
  "error": {
    "message": "The video generation task failed.",
    "code": "video_generation_failed"
  }
}
```

Любой предварительно списанный баланс возвращается автоматически.

### Значения статусов

| Статус        | Значение                                                                                                              |
| ------------- | --------------------------------------------------------------------------------------------------------------------- |
| `queued`      | Задача ожидает запуска.                                                                                               |
| `in_progress` | Видео генерируется. `progress` принимает значения от 0 до 100.                                                        |
| `completed`   | Видео готово по адресу `metadata.url`, данные об использовании токенов доступны в `usage`.                            |
| `failed`      | Генерация завершилась ошибкой. Детали доступны в `error.message`, любой предварительно списанный баланс возвращается. |

## Скачивание видео

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

Эндпоинт контента передаёт данные `video/mp4` в потоковом режиме. Он не требует Bearer-токена и может использоваться непосредственно как источник `<video>`.

<Warning>
  Эндпоинт контента работает только после завершения задачи и имеет ограничение по частоте запросов на основе IP-адреса клиента. Обращайтесь с URL осторожно, поскольку любой, у кого он есть, сможет скачать видео.
</Warning>

## Ошибки

Ошибки на этапе запроса используют стандартный конверт ошибок Flatkey:

```json theme={"dark"}
{
  "error": {
    "message": "...",
    "type": "...",
    "code": "..."
  }
}
```

| Сценарий               | Поведение                                                                        |
| ---------------------- | -------------------------------------------------------------------------------- |
| Пустой `content`       | Запрос отклоняется. Включите непустой текст, изображение или видео.              |
| Недоступная модель     | Запрошенная `model` не включена для данного маршрута.                            |
| Недостаточный баланс   | Задача не создаётся.                                                             |
| Временный сбой сервиса | Повторите попытку позже, используя вашу стандартную политику повторных запросов. |

## Сквозной пример

Этот пример создаёт задачу, опрашивает её каждые пять секунд и скачивает готовое видео. Требуется [`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"
```