how-tos

Seedance 2.5 API: руководство — вызов Seedance 2.5 Flash через cURL и Python

Poyo.ai Team
10 min read
Share:

Курьер на велосипеде наперегонки с часами на башне на рассвете, редакционная иллюстрация к руководству по Seedance 2.5 Flash API

Seedance 2.5 Flash API — более быстрый и дешёвый тариф Seedance 2.5 API, и в PoYo это один ID модели: seedance-2.5-flash. ByteDance выпустила её 12 ноября 2026 года; на странице модели Seedance 2.5 Flash есть песочница и актуальные цены. Это руководство проведёт вас от первого запроса cURL до production-цикла на Python по схеме из документации Seedance 2.5 Flash API, проверенной 16 ноября 2026 года.

Seedance 2.5 Flash API: основное

ПараметрЗначение
Эндпоинт отправкиPOST https://api.poyo.ai/api/generate/submit
Эндпоинт статусаGET https://api.poyo.ai/api/generate/status/{task_id}
Заголовок авторизацииAuthorization: Bearer $POYO_API_KEY
ID моделиseedance-2.5-flash (слаг страницы seedance-2-5-flash не является ID модели)
Обязательные поляprompt, duration
ДлительностьЦелые секунды, 4–30
Разрешение480p или 720p, по умолчанию 720p
Соотношение сторонauto, 21:9, 16:9, 4:3, 1:1, 3:4, 9:16, по умолчанию auto
Аудиоgenerate_audio, по умолчанию true
Доставка результатаАсинхронная задача: опрос статуса или callback_url

Первый запрос к Seedance 2.5 API через cURL

Экспортируйте ключ в POYO_API_KEY и храните его на сервере, а не в браузерном коде. Это 5-секундный запрос text-to-video в 480p — недорогой первый тест за 92.5 кредита:

curl --fail-with-body https://api.poyo.ai/api/generate/submit \
  -H "Authorization: Bearer $POYO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2.5-flash",
    "input": {
      "prompt": "A paper boat drifts under a stone bridge at sunrise. Slow tracking shot, gentle water sounds, no speech, no subtitles.",
      "duration": 5,
      "resolution": "480p",
      "aspect_ratio": "16:9"
    }
  }'

Успешная отправка возвращает code: 200 и объект data с task_id, status (сразу после отправки всегда not_started) и created_time. Это квитанция, а не видео. Сохраните task_id и запросите статус:

curl --fail-with-body \
  https://api.poyo.ai/api/generate/status/YOUR_TASK_ID \
  -H "Authorization: Bearer $POYO_API_KEY"

Статусы проходят через not_started, running, finished и failed. Когда задача в статусе finished, URL видео находится в data.files[].file_url с file_type: "video"; при failed смотрите data.error_message. Сгенерированные файлы доступны 3 дня, поэтому копируйте их в своё хранилище.

Python: отправка и опрос с жёстким дедлайном

Документация по статусам рекомендует опрашивать каждые 2–5 секунд, увеличивать задержку при 429 и 5xx и всегда задавать таймаут. Цикл ниже делает все три и никогда не отправляет задачу повторно по таймауту, потому что повторная отправка — это вторая оплачиваемая задача.

import os
import time
import requests

BASE = "https://api.poyo.ai"
session = requests.Session()
session.headers["Authorization"] = "Bearer " + os.environ["POYO_API_KEY"]


def checked(response):
    try:
        body = response.json()
    except ValueError:
        response.raise_for_status()
        raise
    if body.get("code") != 200:
        err = body.get("error") or {}
        raise RuntimeError(
            f"PoYo {body.get('code')} {err.get('type')}: "
            f"{err.get('message') or body.get('detail')}"
        )
    return body["data"]


task = checked(session.post(BASE + "/api/generate/submit", json={
    "model": "seedance-2.5-flash",
    "input": {
        "prompt": "A paper boat drifts under a stone bridge at sunrise. Slow tracking shot.",
        "duration": 5,
        "resolution": "480p",
        "aspect_ratio": "16:9",
    },
}, timeout=60))
task_id = task["task_id"]
print("Saved task:", task_id, flush=True)

deadline = time.monotonic() + 15 * 60
backoff = 5
while time.monotonic() < deadline:
    r = session.get(f"{BASE}/api/generate/status/{task_id}", timeout=60)
    if r.status_code == 429 or r.status_code >= 500:
        time.sleep(backoff)
        backoff = min(backoff * 2, 60)
        continue
    data = checked(r)
    if data["status"] == "failed":
        raise RuntimeError(data.get("error_message") or "Generation failed")
    if data["status"] == "finished":
        videos = [f["file_url"] for f in data.get("files", [])
                  if f.get("file_type") == "video"]
        print(videos[0], "credits:", data.get("credits_amount"))
        break
    backoff = 5
    time.sleep(5)
else:
    raise TimeoutError("Still running; poll the saved task ID later: " + task_id)

Для ориентира: в тестах PoYo 16 ноября 2026 года 4-секундный ролик в 480p был готов примерно за две минуты, а 30-секундный ролик в 720p — меньше чем за три минуты от начала до конца. Время зависит от нагрузки, поэтому 15-минутный дедлайн — это страховочный предел, а не оценка.

Без опроса: используйте callback_url

Добавьте callback_url на верхнем уровне рядом с model. Когда задача переходит в finished или failed, PoYo отправляет POST, тело которого — объект данных задачи (task_id, status, files, created_time, error_message) без обёртки code/data. Согласно документации по видеовебхукам:

  • URL должен быть публичным HTTPS, не длиннее 2048 символов, без приватных IP.
  • Отвечайте кодом 2xx в течение 30 секунд; неудачные доставки повторяются до 5 раз с экспоненциальной задержкой.
  • Проверяйте X-Webhook-Signature как base64(HMAC-SHA256(task_id + "." + timestamp, key)), где timestamp берётся из X-Webhook-Timestamp, а ключ — из GET /api/api-keys/webhook-secret.
  • Делайте обработчик идемпотентным. Если все повторы провалятся, результат всё равно доступен через эндпоинт статуса.

Три режима ввода с JSON-телами запросов

API выбирает режим по переданным медиа. Поля mode нет.

РежимКогда выбираетсяСоотношение сторон
Reference-to-videoНепусто любое из reference_image_urls, reference_video_urls, reference_audio_urlsЛюбое поддерживаемое значение
Image-to-video (первый/последний кадр)Непусто image_urlsauto или не указывать; вывод следует первому кадру
Text-to-videoМедиа нетЛюбое поддерживаемое значение

image_urls и поля референсов передаются в разных запросах. Эти тела запросов — примеры из документации.

Text-to-video (30 секунд в 720p, с раскадровкой по времени в промпте):

{
  "model": "seedance-2.5-flash",
  "callback_url": "https://your-domain.com/callback",
  "input": {
    "prompt": "One continuous 30-second story of the same young woman in a yellow raincoat delivering a handwritten letter across a small seaside town at dawn. 0-6s: wide aerial shot of the sleepy harbor town, fishing boats rocking, soft morning light; she rides an old bicycle down a cobblestone hill. 6-12s: tracking shot beside her as she weaves past a fish market, seagulls lifting off, a vendor waves at her. 12-18s: low-angle shot as she climbs a steep stone staircase carrying the bicycle, breathing hard, the letter tucked in her pocket. 18-24s: she knocks on a blue door at the top; an elderly man opens it and she hands him the letter. 24-30s: close-up of the man reading, his eyes filling with tears; he smiles and says softly, \"She remembered.\" Camera slowly pulls back to reveal the sunrise over the sea. Natural ambient sound: waves, gulls, bicycle bell, footsteps, gentle piano music. No subtitles, no on-screen text.",
    "duration": 30,
    "resolution": "720p",
    "aspect_ratio": "16:9",
    "generate_audio": true
  }
}

Первый и последний кадр (один URL задаёт начало, второй — концовку):

{
  "model": "seedance-2.5-flash",
  "input": {
    "prompt": "Locked-off time-lapse of the red lakeside cabin: start from the summer evening in the first frame, let snow gradually cover the shore and the wooden dock as the sky darkens, and end exactly on the snowy night with the aurora in the last frame. Soft wind and crackling ice.",
    "image_urls": [
      "https://example.com/first-frame.jpg",
      "https://example.com/last-frame.jpg"
    ],
    "duration": 5,
    "resolution": "720p",
    "aspect_ratio": "auto"
  }
}

Reference-to-video (ссылайтесь на файлы по порядку загрузки: @Image1, @Video1, @Audio1):

{
  "model": "seedance-2.5-flash",
  "input": {
    "prompt": "@Image1 is the ginger cat. It wears the yellow knitted scarf from @Image2 and is inside the bookstore from @Image3. On a rainy night the cat walks along a bookshelf, jumps down beside a reading lamp, and looks at the camera. Match the slow, cozy rhythm of @Audio1. No subtitles.",
    "reference_image_urls": [
      "https://example.com/cat.png",
      "https://example.com/scarf.png",
      "https://example.com/bookstore.png"
    ],
    "reference_audio_urls": [
      "https://example.com/rhythm.mp3"
    ],
    "duration": 6,
    "resolution": "480p",
    "aspect_ratio": "16:9"
  }
}

Правила валидации, которые стоит проверять до отправки

Проверка на стороне клиента экономит лишний запрос и даёт пользователям более понятное сообщение, чем общий 400.

ПолеПравило
promptОбязательно, непустая строка
durationОбязательно, целое число, 4–30
resolutionТолько 480p или 720p; для 1080p нужна seedance-2.5
aspect_ratioОдно из семи значений; с image_urls используйте auto или не указывайте
image_urls1–2 URL (первый, затем последний кадр); JPEG, PNG или WebP, до 30 MB каждый; не сочетается с полями референсов
reference_image_urlsДо 10; JPEG, PNG или WebP, до 30 MB каждый
reference_video_urlsДо 5; MP4 или MOV, 2–30 с и до 200 MB каждый; суммарная длина не более 30 с
reference_audio_urlsДо 5; MP3 или WAV, 2–30 с и до 15 MB каждый; суммарная длина не более 30 с; требуется референсное изображение или видео
Все URL медиаПубличные HTTP или HTTPS, доступные для прямого скачивания (без страниц входа и истекающих превью)

Суммарная длительность референсов проверяется при отправке задачи. Схема также задаёт additionalProperties: false для input, поэтому не отправляйте поля из API других вендоров, например seed или negative_prompt.

Ошибки, которые стоит обрабатывать

Всегда читайте поле code в теле ответа: некоторые ошибки валидации от эндпоинта отправки приходят с HTTP 200 и "code": 400. В справочнике кодов ошибок перечислены такие:

КодТипЧто делать
400validation_error, file_format_error, content_moderation_errorИсправьте запрос или медиа; не повторяйте без изменений
401authentication_errorПроверьте заголовок Bearer и что ключ всё ещё существует
402insufficient_credits_errorПополните баланс и отправьте заново
429Ограничение частотыПодождите (1 с, 2 с, 4 с...) перед новым опросом или отправкой
500, 502, 503Сервер или вышестоящий провайдерПовторите запрос статуса с задержкой; проверьте статус перед повторной отправкой
Задача failedЗадано error_messageЗалогируйте ID задачи; проваленные задачи показывают credits_amount: 0

Как рассчитывается первый счёт

Без референсных видео стоимость — это секунды вывода, умноженные на посекундную ставку: 18.5 кредита ($0.0925) в 480p и 41 кредит ($0.205) в 720p, при 1 кредит = $0.005. Сгенерированное аудио ничего не добавляет.

Запрос вышеОплачиваемые секундыКредитыUSD
Тест cURL, 5 с 480p592.5$0.4625
Text-to-video, 30 с 720p301,230$6.15
Первый/последний кадр, 5 с 720p5205$1.025
Референсные изображения + аудио, 6 с 480p6111$0.555

Добавление любых reference_video_urls переключает на более низкую ставку с видео (11.5 кредита в 480p, 25.5 в 720p), которая применяется к оплачиваемым секундам: длительности вывода плюс длине каждого референсного видео, округлённой вниз до целых секунд. Эти случаи разобраны в статье Цены Seedance 2.5 API. Сумма списания за завершённую задачу отображается как credits_amount в ответе статуса.

Переход на Seedance 2.5 для 1080p

Поля запроса те же, поэтому перенос задачи с Flash на стандартную модель Seedance 2.5 — это смена ID модели:

{
  "model": "seedance-2.5",
  "input": {
    "prompt": "A paper boat drifts under a stone bridge at sunrise. Slow tracking shot.",
    "duration": 5,
    "resolution": "1080p",
    "aspect_ratio": "16:9"
  }
}

Две детали: в документации seedance-2.5 поле resolution указано как обязательное, поэтому всегда передавайте его, а стандартная модель допускает до 30 изображений, 10 видео и 10 аудиореференсов. В 1080p она стоит 114 кредитов ($0.57) за секунду. О выборе маршрута — в статье Seedance 2.5 Flash vs Seedance 2.5; о сравнении Seedance 2.5 с моделью другого вендора — в статье Kling 4.0 vs Seedance 2.5.

Часто задаваемые вопросы

Какой ID модели у Seedance 2.5 Flash API? seedance-2.5-flash, с точками. Вариант с дефисами seedance-2-5-flash — только слаг страницы модели.

Поддерживает ли Seedance 2.5 Flash API 1080p? Нет. Он принимает 480p и 720p. Для нативного 1080p отправьте то же тело с "model": "seedance-2.5" и "resolution": "1080p".

Как отключить аудио в Seedance 2.5 API? Задайте "generate_audio": false для беззвучного ролика или оставьте аудио включённым и уберите отдельные слои в промпте, например «no background music».

Можно ли использовать первые кадры и референсные изображения в одном запросе к Seedance 2.5 Flash? Нет. image_urls и поля reference_* нужно отправлять в разных запросах.

Сколько времени занимает задача Seedance 2.5 Flash API? В тесте PoYo 16 ноября 2026 года — около двух минут для 4 секунд в 480p и меньше трёх минут для 30 секунд в 720p от начала до конца. Опрашивайте статус или используйте коллбэк, а не держите запрос открытым.

Списываются ли кредиты, если задача Seedance 2.5 Flash провалилась? Нет. Проваленные задачи не оплачиваются, и их статус показывает credits_amount: 0.

Share: