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

Используйте POST /v1/videos для создания асинхронной задачи генерации видео Seedance. Опрашивайте задачу до её завершения, затем скачайте видео по возвращённому URL Flatkey. Поддерживаемые модели: seedance-2.0 и seedance-2.0-fast. Доступность зависит от вашего аккаунта; используйте GET /v1/models для получения актуального списка моделей.

Эндпоинт

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

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

Запрос

Заголовки

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

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

string

обязательно

Идентификатор модели Seedance. Используйте "seedance-2.0" или "seedance-2.0-fast".

array

обязательно

Мультимодальные входные элементы. Включите хотя бы один непустой текстовый элемент, URL изображения или URL видео.

string

Разрешение выходного видео: "480p", "720p" или "1080p".

string

Соотношение сторон выходного видео: "16:9", "4:3", "1:1", "3:4", "9:16", "21:9" или "adaptive".

integer

Длительность видео от 4 до 15 секунд. Используйте -1, чтобы модель выбрала длительность самостоятельно.

integer

Случайное начальное значение. Опустите для использования случайного значения.

boolean

Добавлять ли водяной знак. По умолчанию: false.

boolean

Генерировать ли синхронизированное аудио.

Элементы `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 переходит в режим первого/последнего кадра. Остальные изображения обрабатываются как референсы.

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

string

Явный режим входных данных: "reference" или "first_last_frame". Опустите, чтобы режим определялся автоматически на основе content.

boolean

Включить расширение задачи с помощью веб-поиска.

object

Увеличить разрешение сгенерированного видео, сохраняя тот же публичный идентификатор задачи.

Показать Поля super_resolution_config

string

Целевое разрешение: "720p", "1080p", "2k" или "4k". Должно превышать исходное разрешение и не может сочетаться с resolution_limit.

integer

Пользовательский предел пикселей по короткой стороне от 64 до 2160. Не может сочетаться с resolution.

string

Сцена масштабирования: "aigc", "short_series", "ugc" или "old_film".

string

Режим масштабирования: "standard" (по умолчанию) или "professional".

integer

Частота кадров выходного видео от 1 до 120. Значения выше частоты кадров источника включают интерполяцию кадров.

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

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

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

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

{
  "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
}

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

{
  "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
  }
}

Ответ

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

Поля ответа

string

Публичный идентификатор задачи, используемый для опроса задачи и скачивания готового видео. task_id содержит то же значение.

string

Статус задачи: queued, in_progress, completed или failed.

integer

Прогресс генерации от 0 до 100.

integer

Unix-метка времени создания задачи.

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

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

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

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

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

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

{
  "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
}

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

{
  "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`, любой предварительно списанный баланс возвращается.

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

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

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

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

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

Ошибки

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

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

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

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

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

Обзор

Эндпоинты

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

Эндпоинт

Запрос

Заголовки

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

Элементы `content`

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

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

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

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

Ответ

Поля ответа

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

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

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

Ошибки

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

​Эндпоинт

​Запрос

​Заголовки

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

​Элементы content

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

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

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

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

​Ответ

​Поля ответа

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

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

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

​Ошибки

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

Эндпоинт

Запрос

Заголовки

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

Элементы `content`

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

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

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

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

Ответ

Поля ответа

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

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

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

Ошибки

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