POST
https://vidbudget.com/v1/videos/generations
Асинхронная генерация видео · Единый API загрузок и задач · При сбое оплата не взимается
Попробовать онлайн → Скачать OpenAPI 3.1
Один API для всего процесса генерации
Базовый URL: https://vidbudget.com. REST / JSON, асинхронные задачи. Приложению нужны только ID моделей VidBudget.
Загрузите локальные файлы, получите URL из задачи загрузки, отправьте задачу генерации, проверьте её статус и скачайте результат. Публичную HTTPS-ссылку для скачивания файла можно передать сразу.
Поля available, availability и capabilities в GET /v1/models описывают доступные сейчас возможности. Изменения на сервере не требуют менять код загрузки и проверки статуса.
| Метод | Путь | Назначение |
|---|---|---|
| GET | /v1/models | Модели, цены, доступность и лимиты файлов |
| GET | /v1/balance | Баланс и бонусные баллы |
| POST | /v1/uploads | Загрузить изображение, видео или аудиофайл |
| POST | /v1/uploads/presign | Получить подпись для прямой загрузки большого файла |
| POST | /v1/uploads/{id}/complete | Подтвердить прямую загрузку и создать задачу обработки |
| POST | /v1/videos/generations | Создать задачу генерации видео |
| GET | /v1/tasks/{id} | Проверить задачу загрузки или генерации |
| GET | /v1/tasks | Последние 100 ваших задач |
| GET | /v1/videos/jobs/{id} | Совместимый путь проверки задачи генерации |
Авторизация, идемпотентность и баланс
Создайте свой ключ API VidBudget на странице /account/keys.
Авторизация: Authorization: Bearer YOUR_VIDBUDGET_API_KEY. Для JSON используйте Content-Type: application/json. При загрузке файлов HTTP-клиент сам задаёт границу multipart.
Для каждой новой генерации создавайте уникальный Idempotency-Key. При повторной отправке после сетевого сбоя сохраните исходные ключ и параметры. Сервис вернёт прежнюю задачу без повторного списания. После тайм-аута не отправляйте покупку с новым ключом.
Для обычного аккаунта при отправке сумма резервируется, при успехе списывается, при окончательном сбое возвращается. При временной недоступности генерации (HTTP 503) средства не списываются. Сначала проверьте баланс.
GET /v1/balance возвращает billing_mode: wallet означает оплату с обычного баланса, admin означает подтверждённый сервером запрос администратора. Баланс администратора не уменьшается при генерации в студии или с его ключом API. Платформа оплачивает генерацию и регистрирует каждый запрос для аудита. Параметры запроса не могут задать или изменить статус плательщика.
Модели и диапазоны параметров
Изображения, видео и аудио считаются отдельно. Актуальные значения durations, ratios, resolutions, images, videos и audios доступны в capabilities.
Для видеореференсов может действовать ограничение на сумму длительностей референсов и результата. См. capabilities.video_and_output_seconds.
В форме загрузки можно выбрать до 30 изображений за раз. Допустимое количество для одной генерации определяется текущими характеристиками выбранной модели.
| ID модели | Имя | Принимает задачи | Изображения / видео / аудио |
|---|---|---|---|
| seedance-2.5 | Seedance 2.5 | Да | 30 / 10 / 10 |
| seedance-2.5-flash | Seedance 2.5 Flash | Да | 10 / 5 / 5 |
| seedance-2.5-30s | Seedance 2.5 Special | Да | 30 / 10 / 10 |
| wan-3.0 | Wan 3.0 | Да | 10 / 5 / 5 |
| vidu-q4 | Vidu Q4 | Да | 10 / 0 / 3 |
| muse-video | Muse Video | Да | 9 / 0 / 0 |
Локальные файлы и пакетная загрузка
POST /v1/uploads, multipart/form-data, имя поля file. Один файл на запрос. Обычная загрузка — до 90000000 байт. Поддерживаются PNG/JPEG/WebP/GIF, MP4/WebM и MP3/WAV/M4A. Сервер проверяет фактический файл.
Возвращает HTTP 202 и id задачи загрузки. Проверяйте GET /v1/tasks/{id} и берите data[0].url только после успеха. Не подставляйте ID задачи загрузки в массивы файлов генерации.
Для пакета рекомендуется до 6 параллельных загрузок. Соберите результаты в исходном порядке. Текущий лимит ключа API — 150 загрузок в час.
Сверх обычного лимита вызовите presign с content_type и size, отправьте исходные байты методом PUT на upload_url, затем вызовите complete. Максимум 1000000000 байт, подпись действует 15 минут. В PUT передавайте только возвращённые заголовки, без ключа VidBudget.
curl https://vidbudget.com/v1/uploads \ -H "Authorization: Bearer $VIDBUDGET_API_KEY" \ -F "file=@reference.wav"
POST /v1/uploads/presign
{"content_type":"video/mp4","size":100000000}
PUT <upload_url>
POST /v1/uploads/<upload_id>/complete
GET /v1/tasks/<returned_task_id>
Запрос генерации со всеми параметрами
В промпте обращайтесь к файлам как @Image1, @Video1, @Audio1. Номер соответствует порядку добавления в массив. Сервер преобразует ссылки в формат выбранной модели.
duration задаётся в целых секундах, resolution — например 720P, aspect_ratio — например 16:9. Нужны HTTPS-ссылки. Локальные пути и URI data: не поддерживаются.
Основные поля: images, video_references и audio_references. Допустимы псевдонимы videos / audios. Для каждого типа файлов передавайте только одно поле.
audio / generate_audio управляет звуковой дорожкой результата. Для специальной модели с оплатой за ролик этот переключатель недоступен. Аудиореференсы передавайте в audio_references.
{
"model": "seedance-2.5-30s",
"prompt": "Keep the subject of @Image1, follow the camera movement of @Video1 and the rhythm of @Audio1.",
"duration": 5,
"resolution": "720P",
"aspect_ratio": "16:9",
"images": ["https://media.vidbudget.com/inputs/IMAGE.png"],
"video_references": ["https://media.vidbudget.com/inputs/VIDEO.mp4"],
"audio_references": ["https://media.vidbudget.com/inputs/AUDIO.wav"]
}
Python · Загрузка, генерация, проверка и скачивание
Установите requests. Задайте ключ в VIDBUDGET_API_KEY. Подготовьте изображения в references/, а также camera.mp4 и rhythm.wav, затем запустите пример. Генерация в этом примере платная.
При ошибке HTTP пример останавливается. Сохраните уже полученный ID задачи и проверьте её после восстановления связи. Не запускайте весь скрипт повторно как автоматическую попытку.
import os, time, uuid, mimetypes
from pathlib import Path
from concurrent.futures import ThreadPoolExecutor
import requests
BASE = "https://vidbudget.com"
HEADERS = {"Authorization": "Bearer " + os.environ["VIDBUDGET_API_KEY"]}
def wait(job):
deadline = time.monotonic() + 7200
while job["status"] not in ("succeeded", "failed"):
if time.monotonic() > deadline:
raise TimeoutError("Continue querying the original task: " + job["id"])
time.sleep(3)
response = requests.get(BASE + "/v1/tasks/" + job["id"], headers=HEADERS, timeout=85)
response.raise_for_status()
job = response.json()
if job["status"] == "failed":
raise RuntimeError(job["error"])
return job["data"][0]["url"]
def upload(path):
path = Path(path)
mime = mimetypes.guess_type(path.name)[0] or "application/octet-stream"
if path.suffix.lower() == ".m4a": mime = "audio/mp4"
with path.open("rb") as file:
response = requests.post(BASE + "/v1/uploads", headers=HEADERS,
files={"file": (path.name, file, mime)}, timeout=85)
response.raise_for_status()
return wait(response.json())
# executor.map preserves the original file order. Up to 30 images for the full-parameter tier.
files = sorted(Path("references").glob("*.png"))
with ThreadPoolExecutor(max_workers=6) as pool:
images = list(pool.map(upload, files))
video = upload("camera.mp4")
audio = upload("rhythm.wav")
request_id = str(uuid.uuid4()) # Persist this ID and body before submitting.
body = {"model": "seedance-2.5-30s", "prompt": "Generate a shot based on @Image1, @Video1 and @Audio1",
"duration": 5, "resolution": "720P", "aspect_ratio": "16:9",
"images": images, "video_references": [video], "audio_references": [audio]}
response = requests.post(BASE + "/v1/videos/generations",
headers={**HEADERS, "Idempotency-Key": request_id}, json=body, timeout=85)
response.raise_for_status()
job = response.json()
print("Save task ID:", job["id"])
url = wait(job)
with requests.get(url, stream=True, timeout=85) as result:
result.raise_for_status()
with open("video.mp4", "wb") as file:
for chunk in result.iter_content(1024 * 1024): file.write(chunk)
Статус и результаты задачи
Каждая задача содержит id, kind, model, status, created_at, completed_at, elapsed_seconds, retry_count, error и data. Статусы: queued при создании, processing во время работы, succeeded при успехе и failed при окончательном сбое.
Читайте data[0].url только после успешного завершения. Видео доступны на media.vidbudget.com. elapsed_seconds включает ожидание, обработку файлов, генерацию и сохранение результата.
У задачи с ошибкой есть поле error_message — фраза, которую можно показать вашим пользователям. Для content_rejected есть также error_reason с названием проверки: copyright, real_person или safety. Это проверка самой модели: повторная отправка того же промпта и тех же референсов редко проходит.
Закрытие браузера не отменяет задачу. GET /v1/tasks возвращает историю ваших задач. Доступны только собственные задачи. Скачивайте файлы и видео вовремя: хранение временное.
После завершения задачи ваш сервер может получить уведомление. См. раздел о вебхуках ниже. Потокового API видео нет.
Вебхуки: уведомления о завершении задачи
В разделе «Вебхуки» консоли добавьте до 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. Частные, петлевые и зарезервированные адреса исключены.
| Событие | Когда отправляется |
|---|---|
| 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));
Обработка ошибок
Формат ошибок HTTP: {"error":{"code":"..."}}. При окончательном сбое строка error содержит код ошибки.
Проверять статус достаточно раз в 3–5 сек. Если результат отправки неизвестен, используйте прежний Idempotency-Key и точно те же параметры.
Ошибка задачи service_busy означает, что сервис генерации занят: превышен лимит очереди (по умолчанию 10 минут) или автоматические повторы не помогли. Резерв полностью возвращён. Попробуйте позже.
| HTTP | Значение |
|---|---|
| 400/422 | Параметры или их типы не соответствуют требованиям |
| 401/403 | Не удалось проверить ключ или сеанс |
| 402 | Недостаточно средств |
| 404 | Задача не существует или принадлежит другому аккаунту |
| 409 | Модель отключена или с тем же ключом идемпотентности переданы другие параметры |
| 413 | Файл слишком велик. Используйте прямую загрузку по подписанной ссылке |
| 415 | MIME-тип файла не поддерживается |
| 429 | upload_rate_limit: превышен часовой лимит загрузок |
| 503 | Сочетание параметров временно недоступно. Средства не списаны |
| 504 | Время ожидания истекло. Проверьте исходную задачу или повторите исходный запрос без новой покупки |
| 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.
| Заголовок ответа | Значение |
|---|---|
| X-RateLimit-Limit | Лимит запросов этого типа в минуту |
| X-RateLimit-Remaining | Сколько запросов можно отправить сейчас |
| X-RateLimit-Reset | Секунд до полного восстановления лимита |
| Retry-After | Только при 429: ожидание в секундах |