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

POST https://vidbudget.com/v1/videos/generations

Видео хранятся 72 часа. Скачайте их вовремя.

## Один 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"
```

### JSON · Подпись для большого файла

```
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.

### 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())

```

### Node.js · Проверка подписи

```
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: ожидание в секундах |
