VidBudget
api

Общая справка по API · API

Markdown

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 · Загрузка аудио
curl https://vidbudget.com/v1/uploads \
  -H "Authorization: Bearer $VIDBUDGET_API_KEY" \
  -F "file=@reference.wav"

Запрос генерации со всеми параметрами

В промпте обращайтесь к файлам как @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.

JSON · Изображения, видео и аудио в одном запросе
{
  "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 задачи и проверьте её после восстановления связи. Не запускайте весь скрипт повторно как автоматическую попытку.

Python
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 Вы нажали «Отправить тестовое событие» в консоли
Python · Проверка подписи
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())

Обработка ошибок

Формат ошибок 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: ожидание в секундах

Вход в VidBudget

В аккаунте доступны баланс, ключи API и история генераций.

или
Войти через Google

Ещё нет аккаунта?Зарегистрироваться бесплатно

Связаться с нами

Поможем с аккаунтом, пополнением баланса, результатами и API.

По вопросам платежа укажите номер заказа, по вопросам генерации — ID задачи. Так мы сможем сразу её проверить.

Правила возврата средств →Документация API →