
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_urls | auto или не указывать; вывод следует первому кадру |
| 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_urls | 1–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. В справочнике кодов ошибок перечислены такие:
| Код | Тип | Что делать |
|---|---|---|
400 | validation_error, file_format_error, content_moderation_error | Исправьте запрос или медиа; не повторяйте без изменений |
401 | authentication_error | Проверьте заголовок Bearer и что ключ всё ещё существует |
402 | insufficient_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 с 480p | 5 | 92.5 | $0.4625 |
| Text-to-video, 30 с 720p | 30 | 1,230 | $6.15 |
| Первый/последний кадр, 5 с 720p | 5 | 205 | $1.025 |
| Референсные изображения + аудио, 6 с 480p | 6 | 111 | $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.