Как использовать API Seedance 2.5: краткое руководство

Вы можете пройти путь от API-ключа до готового MP4 за четыре шага: отправьте авторизованный POST-запрос, сохраните request_id, опрашивайте эндпоинт результата каждые 10–20 секунд и скачайте видео до истечения ссылки, часто в течение 24 часов.

Если бы мне нужна была короткая версия, вот что я бы держал в уме:

• Используйте правильный эндпоинт
  • seedance-2.5-text-to-video для текстовых промптов
  • seedance-2.5-image-to-video для анимации публичного URL изображения
• Отправляйте правильные заголовки
  • Authorization: Bearer <API_KEY>
  • Content-Type: application/json
• Выберите основные настройки вывода
  • resolution: от 480p до 4K
  • aspect_ratio: например 16:9 или 9:16
  • duration: до 16 секунд
  • generate_audio: true для звука и произнесённых реплик
• Опрашивайте вместо повторной отправки
  • Проверяйте predictions/{request_id}/result
  • Следите за queued, running, succeeded или failed
• Контролируйте стоимость
  • Начинайте с 480p или 720p
  • Держите тот же seed
  • Перезапускайте в 1080p или 4K только когда план выглядит правильно

Я бы также следил за самыми распространёнными точками сбоя: 401 из-за плохого заголовка авторизации, 402 из-за отсутствия кредитов, 429 из-за слишком большого числа активных заданий и 400 из-за плохого JSON или отсутствующих полей. На APIMart кредиты резервируются при старте задания и списываются только если оно завершается; за неудавшиеся задания возвращается оплата.

Если вы выбираете между моделями, Seedance 2.5 — топовый вариант в этой линейке: до 16 с, до 3 840 × 2 160 и до 50 референсных входов. Seedance 2.0 находится посередине, а Seedance 2 Mini лучше для менее затратных черновиков.

Итог: если вы можете сделать валидный POST-запрос и сохранить один ID, вы можете запустить весь рабочий процесс. Остальное — это настройка промпта, терпеливый опрос и скачивание файла до того, как URL истечёт. Для постобработки вы можете использовать AI-холст, чтобы апскейлить или редактировать сгенерированные клипы.

Шаг 1: настройте доступ к APIMart и авторизуйте запросы

Каждый запрос Seedance 2.5 требует валидного API-ключа и правильных заголовков. Начните с этого. Как только это на месте, вы можете перейти к полезным нагрузкам генерации видео и отслеживанию заданий.

Создайте и надёжно храните ваш API-ключ

Создайте свой ключ в панели управления аккаунтом в разделе Settings или API Keys. Затем храните его в файле .env или переменной окружения, а не в системе контроля версий ^[6][8].

export APIMART_API_KEY="sk_live_xxxxxx"

Если ключ потерян, отзовите его и создайте новый ^[3]. Для интеграционного тестирования используйте отдельный ключ sk_test_, чтобы не затрагивать производственное использование ^[3].

Далее включайте этот ключ в каждый запрос с заголовком Authorization.

Правильно добавьте заголовок Authorization

Отправляйте запросы на https://muapi.ai/api/v1/ с этими заголовками:

• Authorization: Bearer sk_live_xxxxxx
• Content-Type: application/json

Одна маленькая оплошность в форматировании может сломать запрос. Самая частая — пропуск префикса Bearer или отсутствие пробела перед ключом ^[3][7]. Это обычно приводит к ответу 401 Unauthorized. Пропуск Content-Type: application/json тоже может привести к сбою запроса ^[3][7].

С настроенной авторизацией вы можете перейти к полезной нагрузке видеозапроса.

Шаг 2: постройте запрос генерации видео Seedance 2.5

С настроенным API-ключом следующий ход — построение валидного тела запроса. Каждое задание Seedance 2.5 начинается с POST-запроса на один из двух эндпоинтов, в зависимости от того, с чего вы начинаете. Используйте https://muapi.ai/api/v1/seedance-2.5-text-to-video для генерации только из промпта, или https://muapi.ai/api/v1/seedance-2.5-image-to-video, если вы анимируете исходное изображение ^[1].

Выберите правильный режим ввода и параметры

Ваш режим ввода определяет форму полезной нагрузки. Text-to-video нужен только prompt. Image-to-video также нужен image_url, указывающий на публично доступный файл JPG, PNG или WEBP размером менее 10 МБ ^[1].

Отсюда вы контролируете вывод несколькими основными полями:

• resolution: 480p, 720p, 1080p или 4K
• aspect_ratio: 16:9, 9:16, 1:1, 4:3, 3:4 или 21:9
• duration: до 16 секунд на Muapi
• generate_audio: булево значение, которое включает синхронизированный фоновый звук, эффекты и диалог при установке в true ^[1]

Разумный способ работы — начать с 480p с фиксированным seed. Если движение, темп и кадрирование выглядят правильно, запустите тот же seed снова в 1080p или 4K для финальной версии.

Для промптов используйте такой поток: Subject → Action → Camera → Setting → Mood ^[4]. Держите движение, направление камеры и настроение внутри самого prompt, а seed оставляйте неизменным, пока тестируете вариации. Если вам нужна синхронизация губ, поместите произносимую реплику в двойные кавычки прямо внутри строки промпта. Например: she turns and says "We launch at dawn." В этом случае убедитесь, что generate_audio установлен в true ^[1].

Как только полезная нагрузка выглядит хорошо, отправьте задание и сохраните возвращённый request ID. Он понадобится вам для опроса.

Примеры запросов на cURL, Postman, Python и JavaScript

Ниже одна и та же полезная нагрузка text-to-video показана в четырёх распространённых инструментах.

cURL

curl -X POST https://muapi.ai/api/v1/seedance-2.5-text-to-video \
  -H "Authorization: Bearer $APIMART_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A barista steams milk, then pours a latte art heart. Close-up, warm café lighting, cinematic.",
    "aspect_ratio": "16:9",
    "resolution": "1080p",
    "duration": 8,
    "generate_audio": true,
    "seed": 42
  }'

Postman — создайте новый POST-запрос, вставьте URL эндпоинта, добавьте Authorization: Bearer <your_key> и Content-Type: application/json во вкладке Headers, затем вставьте JSON выше в Body → raw → JSON. Нажмите Send и сохраните request_id из ответа.

Python

import os, requests

payload = {
    "prompt": "A barista steams milk, then pours a latte art heart. Close-up, warm café lighting, cinematic.",
    "aspect_ratio": "16:9",
    "resolution": "1080p",
    "duration": 8,
    "generate_audio": True,
    "seed": 42
}

response = requests.post(
    "https://muapi.ai/api/v1/seedance-2.5-text-to-video",
    headers={
        "Authorization": f"Bearer {os.environ['APIMART_API_KEY']}",
        "Content-Type": "application/json"
    },
    json=payload
)

print(response.json())  # save request_id here

JavaScript (fetch)

const response = await fetch("https://muapi.ai/api/v1/seedance-2.5-text-to-video", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.APIMART_API_KEY}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    prompt: "A barista steams milk, then pours a latte art heart. Close-up, warm café lighting, cinematic.",
    aspect_ratio: "16:9",
    resolution: "1080p",
    duration: 8,
    generate_audio: true,
    seed: 42
  })
});

const data = await response.json();
console.log(data.request_id); // use this to poll for results

Несколько ошибок могут быстро сбить вас с толку. Не отправляйте image_url, который недоступен публично. Не нагромождайте направления камеры, которые конфликтуют друг с другом в одном промпте. И в режиме image-to-video не описывайте субъект снова, если исходное изображение уже определяет его ^[1].

После отправки опрашивайте статус задания, пока URL MP4 не будет готов.

Когда использовать Seedance 2.5 в линейке видеомоделей APIMart

Это быстрое сравнение помогает выбрать правильную модель, прежде чем начинать настройку промптов или повышение разрешения. Seedance 2.5 даёт вам нативный 4K, до 50 референсных входов и поддержку более длинных клипов. Seedance 2 Mini лучше для лёгких черновиков, тогда как Seedance 2.0 находится посередине как вариант для общего использования ^[1][9][4].

Если проект — это финальная поставка, например видео запуска товара, брендовая кинематографическая последовательность или что-то, идущее на вещание, Seedance 2.5 — лучший выбор. Для проектов, требующих 高品質音声付きAI動画生成, Google Veo 3.1 — ещё один сильный претендент. Если вы всё ещё тестируете идеи, начните с Mini, чтобы проверить движение и зафиксировать кадрирование с меньшими затратами, затем переходите к 2.5 для финального рендера.

Шаг 3: отправьте задание, отслеживайте статус и прочитайте ответ

Как только вы отправите POST-запрос, API возвращает request_id. Сохраните его. Вы будете использовать этот ID, чтобы проверять задание позже, потому что генерация выполняется асинхронно.

Обработайте асинхронные задания от создания до завершения

После отправки задания следующий шаг прост: опрашивайте, пока финальное видео не будет готово.

Отправьте GET-запрос на https://muapi.ai/api/v1/predictions/{request_id}/result. Подождите около 10 секунд после отправки перед первым опросом, затем проверяйте снова каждые 10–20 секунд. Если вы опрашиваете чаще, чем каждые 5 секунд, вы можете упереться в лимиты частоты ^[1][3].

Каждый ответ включает поле status. Это поле сообщает вам, что происходит и что вам следует делать дальше:

Как только задание достигает succeeded, захватите URL вывода, прежде чем он истечёт.

Прочитайте поля вывода и сохраните результаты

Когда статус меняется на succeeded, прочитайте полезную нагрузку вывода и сохраните результат.

Успешный ответ включает video_url. Он также может включать last_frame_url, если вы его запросили. Сохраните video_url, необязательный last_frame_url и метаданные, такие как seed, duration, resolution, aspect_ratio и usage. Эти данные важны для биллинга и для воспроизведения того же прогона позже ^[11][13].

URL вывода часто истекают в течение 24 часов, так что сразу скачивайте файл в собственное хранилище ^[11][12][13]. Если задание падает, логируйте error.code и error.message. А если сбой связан с проверками безопасности, не повторяйте его автоматически ^[2][11][12].

Шаг 4: устраните ошибки, контролируйте стоимость и завершите работу

Исправьте ошибки авторизации, валидации и лимитов частоты

После отправки задания и опроса результатов несколько простых проверок могут уберечь производственные прогоны от срыва. Большинство сбоев Seedance обычно проявляются одними и теми же несколькими способами.

Для референсных ресурсов убедитесь, что URL публичный, файл — JPG, PNG или WEBP, и он не превышает указанного лимита размера ^[12][4].

Сократите затраты и повысьте надёжность

Как только обработка ошибок настроена, следующий шаг прост: тестируйте дёшево, потом рендерьте по-крупному.

Начните свой промпт с 480p или 720p. Это даёт вам недорогой способ проверить кадрирование, движение и делает ли промпт то, что вы хотите. Если план выглядит правильно, перезапустите то же значение seed в 4K для финального вывода ^[1][4].

Длина клипа тоже важна. Более короткие видео стоят меньше, так что держите длительность на минимуме, который всё ещё выполняет задачу ^[1][10].

Есть также коварный способ, которым команды сжигают деньги: дублирующие отправки после сетевого тайм-аута. Одно чистое решение — хешировать промпт, ID модели и URL медиа перед каждым POST-запросом. Если этот хеш уже сопоставлен с ID задачи, вообще пропустите новую отправку ^[11]. И как только задание достигает succeeded, сохраните готовый файл в надёжное хранилище, чтобы не зависеть от записи задачи позже ^[12][11].

Заключение: от документации API к работающей генерации видео

С авторизацией, полезными нагрузками, опросом и обработкой ошибок на месте у вас теперь есть полный рабочий процесс Seedance 2.5 на APIMart.

Частые вопросы

::: faq

Сколько времени занимает у Seedance 2.5 создание видео?

Seedance 2.5 может генерировать один непрерывный видеоклип длиной до 30 секунд. Документация, однако, не указывает точное время завершения.

API работает асинхронно. Вы отправляете задачу, получаете ID задачи, а затем либо опрашиваете эндпоинт статуса, либо ждёте вебхук, чтобы получить готовое видео.

Время обработки может варьироваться в зависимости от таких факторов, как разрешение и сложность сцены. :::

::: faq

Что мне делать, если мой URL видео истёк до того, как я его скачал?

Если ваш URL видео истёк до того, как вы его скачали, вы не сможете получить файл по этой ссылке. Seedance держит эти временные URL активными 24 часа.

Безопасный ход прост: скопируйте видео в собственное защищённое объектное хранилище, как только задача покажет статус завершения. Поскольку API работает асинхронно и не хранит вывод вечно, ваше приложение должно сразу получить видео и переместить его в долгосрочное хранилище. :::

::: faq

Как мне избежать дублирующих списаний при повторе неудавшихся запросов?

Используйте идемпотентную обработку запросов, привязанную к вашим собственным надёжным записям заданий, а не только к HTTP-клиенту.

Прежде чем что-либо отправлять, постройте детерминированный хеш запроса из входных данных, таких как промпт, ID модели, ID ресурсов и идентификатор пользователя. Затем сохраните этот хеш со статусом submitting в своей собственной базе данных.

Если тот же хеш появляется снова, верните существующее задание вместо создания нового.

Как только вы сохранили ID задания провайдера, не отправляйте запрос снова. Просто возобновите опрос с этим ID задания. :::