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

Используйте POST /v1/videos для создания асинхронной задачи генерации видео Seedance. Опрашивайте задачу до её завершения, затем скачайте видео по возвращённому URL Flatkey. Поддерживаемые модели: seedance-2.0, seedance-2.0-fast, seedance-2.0-mini и seedance-2.5. Доступность зависит от вашего аккаунта; используйте 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", "seedance-2.0-mini" или "seedance-2.5".

array

обязательно

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

string

Разрешение выходного видео. По умолчанию: "720p".

Модель	Поддерживаемые значения
`seedance-2.0`	`"480p"`, `"720p"`, `"1080p"`, `"4k"`
`seedance-2.0-fast`, `seedance-2.0-mini`	`"480p"`, `"720p"`
`seedance-2.5`	`"480p"`, `"720p"`, `"1080p"`

string

Соотношение сторон выходного видео: "16:9", "4:3", "1:1", "3:4", "9:16", "21:9" или "adaptive". По умолчанию: "adaptive". При "adaptive" модель подбирает соотношение сторон по входным изображениям или видео. Для seedance-2.5 задачи с первым кадром и с первым и последним кадрами поддерживают только "adaptive".

integer

Длительность видео в секундах. По умолчанию: 5. Модели Seedance 2.0 принимают значения от 4 до 15; seedance-2.5 — от 4 до 30.

Всегда передавайте положительное значение duration. Flatkey тарифицирует Seedance посекундно, поэтому -1 (длительность выбирает модель) отклоняется с ошибкой video_price_not_configured. Единственное исключение — редактирование видео в seedance-2.5, где -1 обязателен.

boolean

Добавить водяной знак “AI generated” в правый нижний угол. По умолчанию: false.

boolean

Сгенерировать синхронизированную монофоническую звуковую дорожку. По умолчанию: true. Установите false, если вам нужно только видео; сгенерированное аудио иногда может не пройти проверку на авторские права.

boolean

Вернуть последний кадр сгенерированного видео в виде изображения. По умолчанию: false. При значении true завершённая задача содержит metadata.last_frame_url, по которому скачивается JPEG того же размера, что и видео, без водяного знака. Используйте его как first_frame следующей задачи, чтобы выстраивать клипы в цепочку. Как и metadata.url, этот URL не требует заголовка авторизации; не раскрывайте его посторонним.

string

Только для seedance-2.5. Контейнер сгенерированного видео: "mp4" или "mov". По умолчанию: "mp4". MOV сохраняет больше цветовой точности для цветокоррекции и композитинга (H.264, YUV 4:4:4, звук PCM), но некоторые плееры не могут его открыть. Эндпоинт контента отдаёт результаты в MOV с типом video/quicktime.

string

Только для seedance-2.5, для задач в режиме референса. Сообщает модели, какую задачу вы хотите выполнить: "auto" (по умолчанию), "reference", "edit" или "extend". Если задать значение явно, проверки типа задачи выполняются уже при отправке, поэтому недопустимая комбинация сразу завершается ошибкой, а не после запуска задачи. Для "reference", "edit" и "extend" в content нужны референсные элементы; запрос только с текстом и "reference" отклоняется. См. редактирование и продление видео.

integer

Приоритет в очереди от 0 до 9. По умолчанию: 0. Задача с более высоким значением встаёт в очередь перед задачами с более низким приоритетом, ожидающими ту же модель. Поддерживается всеми моделями Seedance 2.0 и seedance-2.5. Значения вне диапазона 0–9 отклоняются с кодом 400.

integer

Сколько секунд задача может ожидать и выполняться, прежде чем истечёт. По умолчанию: 172800 (48 часов). Укажите меньшее значение, если запоздалый результат вам не нужен.

string

Публичный HTTPS URL, на который отправляется POST при каждом изменении статуса задачи. См. Колбэки задач. URL должен использовать https, не содержать учётных данных пользователя, быть не длиннее 2048 символов и разрешаться в публичный адрес; иначе запрос отклоняется с кодом 400.

Элементы `content`

`type`	Поле значения	Поддерживаемый `role`	Ограничения
`text`	`text`	—	Текст промпта. Не более примерно 1000 английских слов.
`image_url`	`image_url.url`	`first_frame`, `last_frame`, `reference_image`	До 9 референсных изображений (`seedance-2.5`: 30). JPEG, PNG, WebP, BMP, TIFF, GIF, HEIC или HEIF; менее 30 МБ; 300–6000 пикселей по каждой стороне; соотношение сторон 0,4–2,5.
`video_url`	`video_url.url`	`reference_video`	До 3 видео длительностью 2–15 секунд каждое и не более 15 секунд в сумме (`seedance-2.5`: 10 видео, 30 секунд). MP4 или MOV; менее 200 МБ; не менее примерно 409 600 пикселей в кадре (например, 854×480).
`audio_url`	`audio_url.url`	`reference_audio`	До 3 клипов длительностью 2–15 секунд каждый и не более 15 секунд в сумме (`seedance-2.5`: 10 клипов, 30 секунд). WAV или MP3; менее 15 МБ. Моделям Seedance 2.0 вместе с аудио нужно хотя бы одно изображение или видео.

Каждый URL может быть публичным HTTPS URL, data URI вида data:<mime>;base64, (только для изображений и аудио) или ссылкой asset:// из библиотеки ассетов. Размер всего тела запроса должен быть меньше 64 МБ. Для каждой задачи выберите один режим ввода. Смешивать режимы нельзя:

Режим	Как сформировать `content`
Первый кадр	Одно изображение с `role: "first_frame"`.
Первый и последний кадры	Два изображения: одно с `role: "first_frame"`, другое с `role: "last_frame"`. `last_frame` всегда требует `first_frame`, и ни один из них нельзя сочетать с референсными элементами.
Референс	Любая комбинация элементов `reference_image`, `reference_video` и `reference_audio`.

Редактирование видео

seedance-2.5 умеет редактировать или продлевать существующее видео в режиме референса. Опишите изменение в промпте и ссылайтесь на видео как @Video1.

Задача	Обязательные настройки	Длительность результата
Редактирование (замена главного объекта, добавление или удаление объектов, изменение звука)	Хотя бы один `reference_video` длительностью 4–30 секунд, `ratio: "adaptive"`, `duration: -1`. Рекомендуется: `omni_reference_task_type: "edit"`.	Как у редактируемого входного видео
Продление (продолжение видео вперёд или назад)	Хотя бы один `reference_video`, `ratio: "adaptive"`, положительное значение `duration`. Рекомендуется: `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" }
  ]
}

Как и любой запрос к seedance-2.5 с референсным видео, редактирование тарифицируется по ставке для запросов с видео при выбранном разрешении за фиксированные 30 секунд, независимо от длительности входного и выходного видео.

Режим черновика

seedance-2.5 может сначала сгенерировать недорогой черновик в 480p, чтобы вы проверили сцену, планы и движение, прежде чем платить за финальное видео. Для этого нужны два запроса:

Создайте черновик. Отправьте обычный запрос с "draft": true и "resolution": "480p". Он тарифицируется как обычное видео 480p.
Сгенерируйте финальное видео. После завершения черновика отправьте запрос с "resolution": "1080p", в котором единственный элемент content — это draft_task со ссылкой на идентификатор задачи черновика.

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

Финальное видео наследует от черновика промпт, медиафайлы, длительность, соотношение сторон, сид, настройку звука и тип задачи. Не передавайте вместе с draft_task параметры duration, ratio, frames, seed, generate_audio, omni_reference_task_type, draft и любые другие элементы content: такой запрос отклоняется с кодом 400. Параметры return_last_frame, output_format, watermark, priority, execution_expires_after и callback_url по-прежнему можно задавать.

Правило	Подробности
Модель	`model` должен совпадать с моделью черновика.
Идентификатор задачи черновика	Используйте идентификатор `task_…`, который Flatkey вернул для черновика. Это должна быть ваша собственная задача, и она должна быть завершена.
Разрешение	Черновик: только `480p`. Финальное видео: только `1080p`.
Срок действия	Черновик можно использовать в течение 7 дней после создания.
Тарификация	Финальное видео тарифицируется по ставке 1080p за длительность черновика. Если в черновике использовалось референсное видео, применяется ставка для запросов с видео за фиксированные 30 секунд.

Seedance не принимает напрямую изображения или видео с реальными человеческими лицами. Загрузите их как ассеты реального человека и ссылайтесь на них через asset://.

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

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

Мультимодальный референс

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

Ответ

{
  "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",
    "last_frame_url": "https://router.flatkey.ai/v1/videos/task_3f9a00000000000000000000000000e2/last-frame"
  },
  "created_at": 1780306574,
  "completed_at": 1780306750
}

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

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

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

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

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

Колбэки задач

Укажите callback_url, чтобы получать изменения статуса вместо опроса или вместе с ним. Flatkey отправляет POST с Content-Type: application/json, когда задача переходит в статус in_progress, completed или failed. Тело запроса в точности совпадает с тем, что в этот момент возвращает GET /v1/videos/{task_id}, включая metadata.url и metadata.last_frame_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
}

Заголовок	Значение
`X-Flatkey-Event-Id`	`<task_id>:<status>`, например `task_3f9a…e2:completed`. Одно и то же событие может быть доставлено несколько раз; используйте этот заголовок, чтобы отбрасывать дубликаты.

Ответьте любым статусом 2xx в течение 5 секунд. Иначе Flatkey повторит отправку дважды, через 2 и 8 секунд, после чего прекратит попытки. Flatkey не следует редиректам. Колбэки не подписываются, поэтому, прежде чем действовать на основе результата, проверьте его опросом задачи и продолжайте считать опрос источником истины на случай потери колбэка.

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

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 в потоковом режиме или video/quicktime, если в задаче использовался output_format: "mov". Он не требует Bearer-токена и может использоваться непосредственно как источник <video>.

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

Ошибки

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

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

Сценарий	Поведение
Пустой `content`	Запрос отклоняется. Включите непустой текст, изображение или видео.
Недоступная модель	Запрошенная `model` не включена для данного маршрута.
Недостаточный баланс	Задача не создаётся.
`priority` вне диапазона 0–9	Запрос возвращает `400` с `invalid_request`.
Недопустимый `callback_url`	Запрос возвращает `400` с `invalid_request`, если URL не использует HTTPS, содержит учётные данные, длиннее 2048 символов или указывает на частный или локальный адрес.
`duration: -1` вне редактирования видео в `seedance-2.5`	Запрос возвращает `400` с `video_price_not_configured`.
Недопустимые входные данные для модели	Запрос возвращает `400` с `fail_to_fetch_task`, а для запросов со ссылками `asset://` задача завершается с ошибкой `task preparation failed`. Проверьте разрешение, длительность, ограничения на входные данные и правила режимов ввода, описанные выше. Оплата не списывается.
Временный сбой сервиса	Повторите попытку позже, используя вашу стандартную политику повторных запросов.

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

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

Редактирование видео

Режим черновика

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

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

Мультимодальный референс

Ответ

Поля ответа

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

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

Колбэки задач

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

Ошибки

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