POST
https://vidbudget.com/v1/videos/generations
Асинхронная генерация видео · Оплата за ролик · При сбое оплата не взимается
Быстрый старт: отправьте задачу, проверьте статус и скачайте видео
Генерация видео асинхронная. При успешной отправке API возвращает HTTP 202 и ID задачи. Генерация и обработка файлов идут в фоне. Не ждите готовое видео в ответе на отправку.
Сохраните ID задачи и проверяйте статус каждые 5–10 сек. При обрыве связи продолжайте проверять исходную задачу. Если необходимо отправить запрос снова, используйте тот же ключ идемпотентности и точно те же параметры.
curl https://vidbudget.com/v1/videos/generations \
-H "Authorization: Bearer $VIDBUDGET_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: YOUR_UNIQUE_REQUEST_ID" \
-d '{
"model": "seedance-2.5-30s",
"prompt": "Soft light shimmers across the lake as the camera slowly pushes forward",
"duration": 30,
"resolution": "720P",
"aspect_ratio": "16:9"
}'
curl https://vidbudget.com/v1/videos/jobs/TASK_ID -H "Authorization: Bearer $VIDBUDGET_API_KEY"
import os, time, uuid, requests
BASE = "https://vidbudget.com"
headers = {"Authorization": "Bearer " + os.environ["VIDBUDGET_API_KEY"]}
response = requests.post(BASE + "/v1/videos/generations", headers={**headers,
"Idempotency-Key": str(uuid.uuid4())}, json={'model': 'seedance-2.5-30s', 'prompt': 'Soft light shimmers across the lake as the camera slowly pushes forward', 'duration': 30, 'resolution': '720P', 'aspect_ratio': '16:9'}, timeout=85)
response.raise_for_status()
job = response.json()
print("Task ID (save it to keep polling after a disconnect):", job["id"])
deadline = time.monotonic() + 7200
while job["status"] not in ("succeeded", "failed") and time.monotonic() < deadline:
time.sleep(5)
response = requests.get(BASE + "/v1/videos/jobs/" + job["id"], headers=headers, timeout=85)
response.raise_for_status()
job = response.json()
if job["status"] == "succeeded":
url = job["data"][0]["url"]
if not url.startswith("https://media.vidbudget.com/videos/"):
raise RuntimeError("Unexpected media URL")
with requests.get(url, stream=True, timeout=85) as media:
media.raise_for_status()
with open("video.mp4", "wb") as output:
for chunk in media.iter_content(1024 * 1024):
output.write(chunk)
elif job["status"] == "failed":
print("Failed; the hold was refunded:", job["error"])
else:
print("Not finished yet; keep polling the original task:", job["id"])
// Node.js 18+; save the task ID before polling.
const base = "https://vidbudget.com";
const headers = {Authorization: `Bearer ${process.env.VIDBUDGET_API_KEY}`};
async function request(path, options = {}) {
const response = await fetch(base + path, {...options, signal: AbortSignal.timeout(85000)});
const data = await response.json();
if (!response.ok) throw new Error(JSON.stringify(data.error));
return data;
}
let job = await request('/v1/videos/generations', {method: 'POST', headers: {...headers,
'Content-Type': 'application/json', 'Idempotency-Key': crypto.randomUUID()},
body: JSON.stringify({"model": "seedance-2.5-30s", "prompt": "Soft light shimmers across the lake as the camera slowly pushes forward", "duration": 30, "resolution": "720P", "aspect_ratio": "16:9"})});
console.log('Task ID:', job.id);
const deadline = Date.now() + 7200000;
while (!['succeeded', 'failed'].includes(job.status) && Date.now() < deadline) {
await new Promise(resolve => setTimeout(resolve, 5000));
job = await request('/v1/videos/jobs/' + job.id, {headers});
}
console.log(job.status === 'succeeded' ? job.data[0].url : job);
Авторизация и заголовки
Создайте ключ API в консоли. Полный ключ виден только при создании. Не помещайте его в публичный клиентский код, URL или журналы.
Authorization: Bearer YOUR_API_KEY Content-Type: application/json Idempotency-Key: YOUR_UNIQUE_REQUEST_ID
Характеристики и ограничения
Изображения служат референсами персонажей, сцен, товаров и стиля. Они не задают первый или последний кадр. Убедитесь, что у вас есть права на исходные материалы и на использование изображений людей.
Доступность сочетаний параметров сейчас указана в availability ответа GET /v1/models. Если сочетание временно недоступно, API вернёт 503 без списания.
| Параметр | Поддерживается |
|---|---|
| Длительность | 4 / 5 / 6 / 7 / 8 / 9 / 10 / 11 / 12 / 13 / 14 / 15 / 16 / 17 / 18 / 19 / 20 / 21 / 22 / 23 / 24 / 25 / 26 / 27 / 28 / 29 / 30 сек. |
| Разрешения | 720P |
| Соотношения сторон | 16:9 / 9:16 / 1:1 / 4:3 / 3:4 / 21:9 |
| Изображения-референсы | До 30 изображений |
| Видеореференсы | До 10 видео |
| Аудиореференсы | До 10 аудиофайлов |
| Промпт | Обязательное непустое значение. Максимальный размер JSON запроса — 2 МБ |
| Единица тарификации | За ролик |
| Срок хранения видео | 72 часа. Скачайте вовремя |
Параметры запроса
Используйте Content-Type: application/json. Параметры callback_url и n (несколько результатов), первый и последний кадры и потоковая выдача не поддерживаются.
| Параметр | Тип | Обязательно | Описание |
|---|---|---|---|
| model | string | Да | seedance-2.5-30s |
| prompt | string | Да | Описание видео. Ссылайтесь на файлы как @Image1 / @Video1 / @Audio1. Номер соответствует позиции файла в массиве. |
| duration | integer | Нет | По умолчанию 30 сек. Диапазон см. в характеристиках. Для вертикального Clip явно укажите 15 сек. |
| resolution | string | Нет | По умолчанию 720P. Доступно: 720P |
| aspect_ratio | string | Нет | По умолчанию 16:9. Псевдонимы size и ratio не должны противоречить друг другу. |
| images | array<string> | Нет | Массив HTTPS-адресов изображений. Псевдонимы: reference_images, image_url, image. Передавайте одно поле на тип файла. |
| video_references | array<string> | Нет | Массив HTTPS-адресов видео. Опустите поле, если модель не поддерживает видео. Псевдонимы: video_reference, video_url. |
| audio_references | array<string> | Нет | Массив HTTPS-адресов аудио. Опустите поле, если модель не поддерживает аудио. Псевдонимы: audio_reference, audio_url. |
| audio | boolean | Нет | Недоступно при оплате за ролик. Для остальных моделей по умолчанию true. Значение false не гарантирует видео без звука: это зависит от модели. Псевдоним: generate_audio. |
| seconds | integer | Нет | Псевдоним duration. При передаче обоих полей значения должны совпадать. |
| image_role | string | Нет | Допустимы только reference / reference_images / ref. Первый и последний кадры не поддерживаются. |
Цены и расчёт стоимости
Цены берутся из той же действующей конфигурации, что и при списании. Резервирование и создание задачи выполняются одной транзакцией. При успехе резерв списывается, при окончательном сбое возвращается.
Цена по акции действует до 2026-11-22 00:00 (UTC+8): на 25% ниже обычной цены $2.00 за ролик. Задача, отправленная до этого времени, оплачивается по цене акции, даже если завершится позже.
Специальная версия сторонней разработки. Результат может отличаться от официальной версии. Цена одинакова для изображений, видео и аудиореференсов. Требования к файлам определяются текущими характеристиками.
| Разрешение | Цена за единицу (USD) | Пример стоимости |
|---|---|---|
| 720P | 1.5 за ролик | 30 сек.: $1.50 |
Референсы и примеры
Загрузите файлы и проверьте статус задачи загрузки. Получив URL на media.vidbudget.com, поместите его в соответствующий массив. Подходят и публичные HTTPS-ссылки для скачивания. base64 и URI data: не принимаются.
Изображения задают образы персонажей и стиль, видео — движение и работу камеры, аудио — звук и ритм. Доступные типы и количество файлов указаны в характеристиках модели.
Файлы скачиваются и проверяются в фоне. Нечитаемый файл, неподходящий формат или нарушение правил содержимого могут привести к сбою. В этом случае резерв возвращается на баланс.
Правила генерации могут ограничивать использование фотографий реальных людей. Принятие каждого запроса и соответствие результата субъективным ожиданиям не гарантируются.
Видео и загруженные материалы хранятся 72 часа и 72 часа соответственно. Скачайте их вовремя. Временные ссылки не подходят для постоянного хранения.
{
"model": "seedance-2.5-30s",
"prompt": "Soft light shimmers across the lake as the camera slowly pushes forward",
"duration": 30,
"resolution": "720P",
"aspect_ratio": "16:9",
"images": [
"https://media.vidbudget.com/inputs/YOUR_IMAGE_UUID.png"
]
}
Формат ответа
Ответ на отправку имеет ту же структуру: status равен queued, completed_at равен null, data — пустой массив. При сбое error содержит строковый код ошибки. При успехе или во время работы он равен null.
{
"id": "TASK_UUID",
"object": "task",
"kind": "video",
"model": "seedance-2.5-30s",
"status": "succeeded",
"created_at": 1793354400,
"completed_at": 1793354700,
"elapsed_seconds": 300,
"retry_count": 0,
"error": null,
"data": [
{
"url": "https://media.vidbudget.com/videos/VIDEO_UUID.mp4"
}
]
}
Статусы задач и повторные попытки
retry_count считает дополнительные попытки генерации. Изначально значение 0. Запросы статуса не учитываются. completed_at записывается только при окончательном успехе или сбое. Общее время включает очередь, повторные попытки и передачу файлов.
При временном сбое генерация автоматически повторяется до 4 раз на задачу без доплаты. Ошибки промпта, файлов и модерации не повторяются. Если результат отправки нельзя подтвердить, задача завершается ошибкой, резерв возвращается. Повторной покупки нет. Для каждой задачи сумма резервируется один раз и один раз списывается или возвращается. Все изменения видны в истории баланса.
| Статус | Значение |
|---|---|
| queued | Сохранено, ожидает фоновой обработки |
| processing | Идёт обработка файлов, генерация, опрос или передача результата |
| succeeded | Готово. Читайте data[0].url |
| failed | Ошибка. Проверьте error. Резерв возвращается автоматически |
Время генерации и тайм-ауты
Генерация может занять несколько минут или дольше. Время зависит от длительности, разрешения и очереди. У нового сайта пока нет собственной статистики времени генерации. Замеры на других сервисах ничего не гарантируют.
Лимит HTTP-запроса — 85 сек. После этого возвращается JSON с кодом 504. Общий лимит задачи генерации сейчас составляет 7200 сек. Закрытие браузера не отменяет задачу.
503 означает, что сочетание параметров временно недоступно. Средства не списаны. Измените настройки или повторите позже, избегая многократной отправки.
Ошибки и способы устранения
Формат ошибок HTTP: {"error":{"code":"..."}}. Поле message может отсутствовать. При сбое задачи строковый код ошибки указан в поле error объекта задачи.
У задачи с ошибкой есть поле error_message — фраза, которую можно показать вашим пользователям. Для content_rejected есть также error_reason с названием проверки: copyright, real_person или safety. Это проверка самой модели: повторная отправка того же промпта и тех же референсов редко проходит.
| HTTP / задача | Код ошибки | Что делать |
|---|---|---|
| 400 | invalid_request | Проверьте параметры, типы, поля файлов и ограничения модели |
| 401 | invalid_api_key / login_required | Проверьте ключ или войдите снова |
| 402 | insufficient_balance | Пополните баланс и повторите отправку |
| 404 | task_not_found | Проверьте ID и убедитесь, что задача принадлежит вам |
| 409 | conflict | Модель отключена или с тем же ключом идемпотентности переданы другие параметры |
| 413 | payload_too_large | Для больших файлов используйте прямую загрузку по подписанной ссылке |
| 415 | unsupported_media_type | Загружайте только изображения, видео или аудио |
| 429 | upload_rate_limit | Дождитесь обновления лимита |
| 503 | temporarily_unavailable | Сочетание параметров временно недоступно. Средства не списаны. Повторите позже |
| 504 | request_timeout | Проверьте исходную задачу, чтобы избежать повторной покупки |
| Задача | media_processing_failed | Проверьте доступность и фактический формат файла |
| Задача | generation_timeout | Истекло общее время задачи. Резерв возвращён |
| Задача | content_rejected | Промпт или материалы не прошли модерацию. Измените их и отправьте задачу снова |
| Задача | content_rejected · copyright | Проверка авторских прав самой модели: в промпте или референсе есть названный персонаж игры, аниме или фильма, знаменитость, бренд или логотип, песня. Используйте собственных персонажей и свои референсы |
| Задача | content_rejected · real_person | Проверка самой модели на реальных людей: в референсе или видео есть лицо реального человека |
| Задача | content_rejected · safety | Проверка безопасности самой модели (промпт или готовое видео), например нагота, сексуальные или жестокие детали |
| Задача | reference_rejected | Длительность, формат или содержимое референсов не соответствуют требованиям |
| Задача | request_not_accepted | Сочетание длительности, соотношения сторон и файлов временно недоступно. Измените параметры и повторите попытку |
| Задача | generation_failed / service_unavailable | Автоматические повторы не помогли. Попробуйте позже |
| Задача | service_busy | Сервис генерации занят: истёк лимит ожидания в очереди (по умолчанию 10 минут) или автоматические повторы не помогли. Резерв полностью возвращён. Повторите позже |
| Задача | submission_unconfirmed | Результат отправки не подтверждён. Резерв возвращён. Задачу можно отправить снова |
| 429 | too_many_active_tasks | Достигнут лимит видеозадач аккаунта в очереди или в работе (по умолчанию 50). Средства не списаны. Дождитесь завершения части задач. В ответе указан Retry-After: 30 |
| 429 | rate_limited | Слишком много запросов. Средства не списаны. Повторите через число секунд, указанное в заголовке Retry-After. См. «Лимиты запросов» |
| 503 | service_busy | Сервис занят. Запрос не выполнен, средства не списаны. Подождите число секунд из Retry-After (обычно 2 секунды), затем повторите отправку с прежним Idempotency-Key |
| 402 | key_daily_budget_exceeded | Дневной бюджет ключа по UTC исчерпан. Средства не списаны. Бюджет обновится в 00:00 UTC. Его также можно повысить в консоли |
| 403 | key_ip_not_allowed | Текущий IP отсутствует в списке разрешённых адресов ключа |
| 403 | key_model_not_allowed | Эта модель недоступна для данного ключа |
Лимиты запросов
Лимиты действуют отдельно для каждого ключа API. У онлайн-студии отдельный счётчик аккаунта. Используется алгоритм token bucket: запас запросов равномерно восстанавливается с заданной скоростью. По умолчанию GET /v1/* допускает 1200 запросов в минуту и короткие всплески до 100. Для генерации и загрузок (POST /v1/videos/generations, /v1/uploads*) это 120 запросов в минуту и всплески до 30. Для неверного ключа или запроса без входа лимит считается по IP отправителя: 60 в минуту.
При превышении лимита API возвращает HTTP 429 с кодом rate_limited без списания. В Retry-After указано время ожидания в секундах. Каждый ответ /v1 содержит X-RateLimit-Limit (лимит за минуту), X-RateLimit-Remaining (доступно сейчас) и X-RateLimit-Reset (секунд до полного восстановления).
Для наблюдения за несколькими задачами запросите последние 100 через GET /v1/tasks или настройте в консоли вебхук завершения задач. По умолчанию в очереди и в работе у аккаунта может быть до 50 видеозадач одновременно. При превышении лимита API вернёт 429 too_many_active_tasks.
Загрузка файлов и прямая загрузка больших файлов
По умолчанию один ключ API допускает 150 загрузок в час. Лимит обычной загрузки — 90000000 байт. Для больших файлов используйте подписанный PUT. Максимальный размер прямой загрузки — 1000000000 байт. Подпись действует 15 минут.
Принимаются MIME-типы изображений, видео и аудио. Фактическое содержимое декодируется и проверяется в фоне. Рекомендуемые форматы: PNG/JPEG/WebP, MP4, MP3/WAV/M4A. Для пакета отправляйте по запросу на файл, желательно не более 6 одновременно. Сохраните порядок добавления: он определяет номера файлов.
В PUT-запросе на upload_url передавайте только заголовки из ответа. Не передавайте ключ API VidBudget. Затем вызовите complete и запросите статус задачи для получения итогового URL файла.
curl https://vidbudget.com/v1/uploads -H "Authorization: Bearer $VIDBUDGET_API_KEY" -F "file=@reference.png"
POST /v1/uploads/presign
{"content_type":"video/mp4","size":100000000}
PUT <upload_url> (raw file bytes, with the returned headers)
POST /v1/uploads/<upload_id>/complete
GET /v1/tasks/<task_id>
Вебхуки: уведомления о завершении задачи
В разделе «Вебхуки» консоли добавьте до 3 HTTPS-адресов и выберите события. После завершения задачи, отправленной с ключом API, включая успех, сбой, тайм-аут и возврат средств, мы отправим POST на каждый подписанный адрес. Задачи онлайн-студии не рассылаются. Можно также опрашивать GET /v1/tasks/{id}. Параметр callback_url для отдельного запроса не поддерживается.
Тело запроса: {"id":"evt_…","type":"task.succeeded","created":<Unix seconds>,"data":<the task object, the same as GET /v1/tasks/{id} returns>}. При повторной доставке id события сохраняется. Используйте его для устранения дубликатов.
Подпись передаётся в заголовке VidBudget-Signature: t=<Unix seconds>,v1=<hex HMAC-SHA256>. Подписываются t + "." + исходное тело запроса. Ключ — секрет подписи этого адреса с префиксом whsec_. Он виден только при создании или замене. Проверяйте подпись по исходным байтам и отклоняйте события с t старше 5 минут.
Любой ответ 2xx подтверждает доставку. Если за 10 секунд нет ответа, соединение не установлено или получен другой статус, повторяем через 1 минуту, 5 минут, 30 минут, 2 и 6 часов. Всего 6 попыток. Перенаправления не обрабатываются. Нужен публичный HTTPS-адрес на порту 443. Частные, петлевые и зарезервированные адреса исключены.
Синхронная загрузка, другие способы оплаты, другие модели и поля ответа сторонних сервисов к этому API не применяются. Методы аккаунта: GET /v1/balance, GET /v1/tasks, GET /v1/models.
| Событие | Когда отправляется |
|---|---|
| task.succeeded | Задача выполнена. Ссылка на видео находится в data.data[0].url |
| task.failed | Задача завершилась ошибкой. Код указан в data.error. Резерв полностью возвращён |
| webhook.test | Вы нажали «Отправить тестовое событие» в консоли |
import hashlib, hmac, time
def verify(secret: str, header: str, body: bytes, tolerance: int = 300) -> bool:
"""header = the VidBudget-Signature value; body = the raw request bytes, not re-encoded JSON."""
fields = dict(part.split("=", 1) for part in header.split(","))
stamp = int(fields["t"])
if abs(time.time() - stamp) > tolerance:
return False
expected = hmac.new(secret.encode(), f"{stamp}.".encode() + body, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, fields.get("v1", ""))
# Flask: verify(SECRET, request.headers["VidBudget-Signature"], request.get_data())
import crypto from 'node:crypto';
// header = the VidBudget-Signature value; rawBody = the request bytes (a Buffer), not re-encoded JSON.
export function verify(secret, header, rawBody, tolerance = 300) {
const fields = Object.fromEntries(header.split(',').map(p => [p.slice(0, p.indexOf('=')), p.slice(p.indexOf('=') + 1)]));
const stamp = Number(fields.t);
if (!Number.isInteger(stamp) || Math.abs(Date.now() / 1000 - stamp) > tolerance) return false;
const expected = crypto.createHmac('sha256', secret).update(`${stamp}.`).update(rawBody).digest('hex');
const given = Buffer.from(fields.v1 || '');
return given.length === expected.length && crypto.timingSafeEqual(given, Buffer.from(expected));
}
// Express: app.post('/vidbudget', express.raw({ type: 'application/json' }), (req, res) =>
// res.sendStatus(verify(SECRET, req.get('VidBudget-Signature'), req.body) ? 204 : 400));