# Общая справка по 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: ожидание в секундах |


---

# Seedance 2.5 · VidBudget API

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

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

## Быстрый старт: отправьте задачу, проверьте статус и скачайте видео

Генерация видео асинхронная. При успешной отправке API возвращает HTTP 202 и ID задачи. Генерация и обработка файлов идут в фоне. Не ждите готовое видео в ответе на отправку.

Сохраните ID задачи и проверяйте статус каждые 5–10 сек. При обрыве связи продолжайте проверять исходную задачу. Если необходимо отправить запрос снова, используйте тот же ключ идемпотентности и точно те же параметры.

### cURL · Отправка

```
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",
  "prompt": "Soft light shimmers across the lake as the camera slowly pushes forward",
  "duration": 5,
  "resolution": "720P",
  "aspect_ratio": "16:9"
}'
```

### cURL · Проверка статуса

```
curl https://vidbudget.com/v1/videos/jobs/TASK_ID -H "Authorization: Bearer $VIDBUDGET_API_KEY"
```

### Python · Полный цикл опроса

```
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', 'prompt': 'Soft light shimmers across the lake as the camera slowly pushes forward', 'duration': 5, '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 · Полный цикл опроса

```
// 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", "prompt": "Soft light shimmers across the lake as the camera slowly pushes forward", "duration": 5, "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 или журналы.

### HTTP

```
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 сек. |
| Разрешения | 480P / 720P |
| Соотношения сторон | 16:9 / 9:16 / 1:1 / 4:3 / 3:4 |
| Изображения-референсы | До 30 изображений |
| Видеореференсы | До 10 видео |
| Аудиореференсы | До 10 аудиофайлов |
| Промпт | До 11000 символов / 33000 байт UTF-8 |
| Единица тарификации | За секунду готового видео. 720P с видеореференсом: длительность видеореференсов плюс длительность результата |
| Срок хранения видео | 72 часа. Скачайте вовремя |

## Параметры запроса

Используйте Content-Type: application/json. Параметры callback_url и n (несколько результатов), первый и последний кадры и потоковая выдача не поддерживаются.

| Параметр | Тип | Обязательно | Описание |
| --- | --- | --- | --- |
| model | string | Да | seedance-2.5 |
| prompt | string | Да | Описание видео. Ссылайтесь на файлы как @Image1 / @Video1 / @Audio1. Номер соответствует позиции файла в массиве. |
| duration | integer | Нет | По умолчанию 5 сек. Диапазон см. в характеристиках. Для вертикального Clip явно укажите 15 сек. |
| resolution | string | Нет | По умолчанию 720P. Доступно: 480P, 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. Первый и последний кадры не поддерживаются. |

## Цены и расчёт стоимости

Цены берутся из той же действующей конфигурации, что и при списании. Резервирование и создание задачи выполняются одной транзакцией. При успехе резерв списывается, при окончательном сбое возвращается.

При разрешении 720P с видеореференсом стоимость равна сумме длительностей видеореференсов и результата, умноженной на $0.11 за секунду. Суммарная длительность видеореференсов округляется вверх до целой секунды. Остаток менее 0.05 сек. отбрасывается. Без видеореференса тариф прежний. Референсные изображения и аудио бесплатны. Для ссылок от нашего API загрузки резерв рассчитывается по фактической длительности. Для остальных ссылок сначала резервируется максимум 30 сек. После измерения до начала генерации разница возвращается. В истории баланса появится запись «Излишек резерва возвращён».

| Разрешение | Цена за единицу (USD) | Пример стоимости |
| --- | --- | --- |
| 480P | 0.1 за секунду | 5 сек.: $0.50 |
| 720P | 0.158 за секунду | 5 сек.: $0.79 |
| 720P с видеореференсом | 0.11 за секунду (видеореференс + результат) | 5 сек. результата + 5 сек. видеореференса: $1.10 |

## Референсы и примеры

Загрузите файлы и проверьте статус задачи загрузки. Получив URL на media.vidbudget.com, поместите его в соответствующий массив. Подходят и публичные HTTPS-ссылки для скачивания. base64 и URI data: не принимаются.

Изображения задают образы персонажей и стиль, видео — движение и работу камеры, аудио — звук и ритм. Доступные типы и количество файлов указаны в характеристиках модели.

Файлы скачиваются и проверяются в фоне. Нечитаемый файл, неподходящий формат или нарушение правил содержимого могут привести к сбою. В этом случае резерв возвращается на баланс.

Правила генерации могут ограничивать использование фотографий реальных людей. Принятие каждого запроса и соответствие результата субъективным ожиданиям не гарантируются.

Видео и загруженные материалы хранятся 72 часа и 72 часа соответственно. Скачайте их вовремя. Временные ссылки не подходят для постоянного хранения.

### JSON · Изображение-референс

```
{
  "model": "seedance-2.5",
  "prompt": "Soft light shimmers across the lake as the camera slowly pushes forward",
  "duration": 5,
  "resolution": "720P",
  "aspect_ratio": "16:9",
  "images": [
    "https://media.vidbudget.com/inputs/YOUR_IMAGE_UUID.png"
  ]
}
```

## Формат ответа

Ответ на отправку имеет ту же структуру: status равен queued, completed_at равен null, data — пустой массив. При сбое error содержит строковый код ошибки. При успехе или во время работы он равен null.

### JSON · Завершённая задача

```
{
  "id": "TASK_UUID",
  "object": "task",
  "kind": "video",
  "model": "seedance-2.5",
  "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 · Обычная загрузка

```
curl https://vidbudget.com/v1/uploads -H "Authorization: Bearer $VIDBUDGET_API_KEY" -F "file=@reference.png"
```

### HTTP · Загрузка большого файла

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

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

```


---

# Seedance 2.5 Flash · VidBudget API

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

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

## Быстрый старт: отправьте задачу, проверьте статус и скачайте видео

Генерация видео асинхронная. При успешной отправке API возвращает HTTP 202 и ID задачи. Генерация и обработка файлов идут в фоне. Не ждите готовое видео в ответе на отправку.

Сохраните ID задачи и проверяйте статус каждые 5–10 сек. При обрыве связи продолжайте проверять исходную задачу. Если необходимо отправить запрос снова, используйте тот же ключ идемпотентности и точно те же параметры.

### cURL · Отправка

```
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-flash",
  "prompt": "Soft light shimmers across the lake as the camera slowly pushes forward",
  "duration": 5,
  "resolution": "720P",
  "aspect_ratio": "16:9"
}'
```

### cURL · Проверка статуса

```
curl https://vidbudget.com/v1/videos/jobs/TASK_ID -H "Authorization: Bearer $VIDBUDGET_API_KEY"
```

### Python · Полный цикл опроса

```
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-flash', 'prompt': 'Soft light shimmers across the lake as the camera slowly pushes forward', 'duration': 5, '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 · Полный цикл опроса

```
// 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-flash", "prompt": "Soft light shimmers across the lake as the camera slowly pushes forward", "duration": 5, "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 или журналы.

### HTTP

```
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 сек. |
| Разрешения | 480P / 720P |
| Соотношения сторон | 16:9 / 9:16 / 1:1 / 4:3 / 3:4 |
| Изображения-референсы | До 10 изображений |
| Видеореференсы | До 5 видео |
| Аудиореференсы | До 5 аудиофайлов |
| Промпт | До 11000 символов / 33000 байт UTF-8 |
| Единица тарификации | За секунду готового видео. 480P с видеореференсом: длительность видеореференсов плюс длительность результата. 720P с видеореференсом: длительность видеореференсов плюс длительность результата |
| Срок хранения видео | 72 часа. Скачайте вовремя |

## Параметры запроса

Используйте Content-Type: application/json. Параметры callback_url и n (несколько результатов), первый и последний кадры и потоковая выдача не поддерживаются.

| Параметр | Тип | Обязательно | Описание |
| --- | --- | --- | --- |
| model | string | Да | seedance-2.5-flash |
| prompt | string | Да | Описание видео. Ссылайтесь на файлы как @Image1 / @Video1 / @Audio1. Номер соответствует позиции файла в массиве. |
| duration | integer | Нет | По умолчанию 5 сек. Диапазон см. в характеристиках. Для вертикального Clip явно укажите 15 сек. |
| resolution | string | Нет | По умолчанию 720P. Доступно: 480P, 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. Первый и последний кадры не поддерживаются. |

## Цены и расчёт стоимости

Цены берутся из той же действующей конфигурации, что и при списании. Резервирование и создание задачи выполняются одной транзакцией. При успехе резерв списывается, при окончательном сбое возвращается.

При разрешении 480P с видеореференсом стоимость равна сумме длительностей видеореференсов и результата, умноженной на $0.036 за секунду. Суммарная длительность видеореференсов округляется вверх до целой секунды. Остаток менее 0.05 сек. отбрасывается. Без видеореференса тариф прежний. Референсные изображения и аудио бесплатны. Для ссылок от нашего API загрузки резерв рассчитывается по фактической длительности. Для остальных ссылок сначала резервируется максимум 30 сек. После измерения до начала генерации разница возвращается. В истории баланса появится запись «Излишек резерва возвращён».

При разрешении 720P с видеореференсом стоимость равна сумме длительностей видеореференсов и результата, умноженной на $0.08 за секунду. Суммарная длительность видеореференсов округляется вверх до целой секунды. Остаток менее 0.05 сек. отбрасывается. Без видеореференса тариф прежний. Референсные изображения и аудио бесплатны. Для ссылок от нашего API загрузки резерв рассчитывается по фактической длительности. Для остальных ссылок сначала резервируется максимум 30 сек. После измерения до начала генерации разница возвращается. В истории баланса появится запись «Излишек резерва возвращён».

| Разрешение | Цена за единицу (USD) | Пример стоимости |
| --- | --- | --- |
| 480P | 0.055 за секунду | 5 сек.: $0.28 |
| 720P | 0.125 за секунду | 5 сек.: $0.63 |
| 480P с видеореференсом | 0.036 за секунду (видеореференс + результат) | 5 сек. результата + 5 сек. видеореференса: $0.36 |
| 720P с видеореференсом | 0.08 за секунду (видеореференс + результат) | 5 сек. результата + 5 сек. видеореференса: $0.80 |

## Референсы и примеры

Загрузите файлы и проверьте статус задачи загрузки. Получив URL на media.vidbudget.com, поместите его в соответствующий массив. Подходят и публичные HTTPS-ссылки для скачивания. base64 и URI data: не принимаются.

Изображения задают образы персонажей и стиль, видео — движение и работу камеры, аудио — звук и ритм. Доступные типы и количество файлов указаны в характеристиках модели.

Файлы скачиваются и проверяются в фоне. Нечитаемый файл, неподходящий формат или нарушение правил содержимого могут привести к сбою. В этом случае резерв возвращается на баланс.

Правила генерации могут ограничивать использование фотографий реальных людей. Принятие каждого запроса и соответствие результата субъективным ожиданиям не гарантируются.

Видео и загруженные материалы хранятся 72 часа и 72 часа соответственно. Скачайте их вовремя. Временные ссылки не подходят для постоянного хранения.

### JSON · Изображение-референс

```
{
  "model": "seedance-2.5-flash",
  "prompt": "Soft light shimmers across the lake as the camera slowly pushes forward",
  "duration": 5,
  "resolution": "720P",
  "aspect_ratio": "16:9",
  "images": [
    "https://media.vidbudget.com/inputs/YOUR_IMAGE_UUID.png"
  ]
}
```

## Формат ответа

Ответ на отправку имеет ту же структуру: status равен queued, completed_at равен null, data — пустой массив. При сбое error содержит строковый код ошибки. При успехе или во время работы он равен null.

### JSON · Завершённая задача

```
{
  "id": "TASK_UUID",
  "object": "task",
  "kind": "video",
  "model": "seedance-2.5-flash",
  "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 · Обычная загрузка

```
curl https://vidbudget.com/v1/uploads -H "Authorization: Bearer $VIDBUDGET_API_KEY" -F "file=@reference.png"
```

### HTTP · Загрузка большого файла

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

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

```


---

# Seedance 2.5 Special · VidBudget API

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

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

## Быстрый старт: отправьте задачу, проверьте статус и скачайте видео

Генерация видео асинхронная. При успешной отправке API возвращает HTTP 202 и ID задачи. Генерация и обработка файлов идут в фоне. Не ждите готовое видео в ответе на отправку.

Сохраните ID задачи и проверяйте статус каждые 5–10 сек. При обрыве связи продолжайте проверять исходную задачу. Если необходимо отправить запрос снова, используйте тот же ключ идемпотентности и точно те же параметры.

### cURL · Отправка

```
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 · Проверка статуса

```
curl https://vidbudget.com/v1/videos/jobs/TASK_ID -H "Authorization: Bearer $VIDBUDGET_API_KEY"
```

### Python · Полный цикл опроса

```
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 · Полный цикл опроса

```
// 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 или журналы.

### HTTP

```
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 часа соответственно. Скачайте их вовремя. Временные ссылки не подходят для постоянного хранения.

### 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",
  "images": [
    "https://media.vidbudget.com/inputs/YOUR_IMAGE_UUID.png"
  ]
}
```

## Формат ответа

Ответ на отправку имеет ту же структуру: status равен queued, completed_at равен null, data — пустой массив. При сбое error содержит строковый код ошибки. При успехе или во время работы он равен null.

### JSON · Завершённая задача

```
{
  "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 · Обычная загрузка

```
curl https://vidbudget.com/v1/uploads -H "Authorization: Bearer $VIDBUDGET_API_KEY" -F "file=@reference.png"
```

### HTTP · Загрузка большого файла

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

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

```


---

# Wan 3.0 · VidBudget API

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

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

## Быстрый старт: отправьте задачу, проверьте статус и скачайте видео

Генерация видео асинхронная. При успешной отправке API возвращает HTTP 202 и ID задачи. Генерация и обработка файлов идут в фоне. Не ждите готовое видео в ответе на отправку.

Сохраните ID задачи и проверяйте статус каждые 5–10 сек. При обрыве связи продолжайте проверять исходную задачу. Если необходимо отправить запрос снова, используйте тот же ключ идемпотентности и точно те же параметры.

### cURL · Отправка

```
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": "wan-3.0",
  "prompt": "Soft light shimmers across the lake as the camera slowly pushes forward",
  "duration": 5,
  "resolution": "720P",
  "aspect_ratio": "16:9"
}'
```

### cURL · Проверка статуса

```
curl https://vidbudget.com/v1/videos/jobs/TASK_ID -H "Authorization: Bearer $VIDBUDGET_API_KEY"
```

### Python · Полный цикл опроса

```
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': 'wan-3.0', 'prompt': 'Soft light shimmers across the lake as the camera slowly pushes forward', 'duration': 5, '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 · Полный цикл опроса

```
// 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": "wan-3.0", "prompt": "Soft light shimmers across the lake as the camera slowly pushes forward", "duration": 5, "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 или журналы.

### HTTP

```
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
Idempotency-Key: YOUR_UNIQUE_REQUEST_ID
```

## Характеристики и ограничения

Референсные изображения описывают персонажей, сцены, товары и стиль. Если задать image_role = first_frame, первое изображение станет первым кадром видео, а второе — последним; первый и последний кадр нельзя сочетать с референсными видео или аудио. Убедитесь, что у вас есть право использовать исходные материалы и внешность людей на них.

Доступность сочетаний параметров сейчас указана в availability ответа GET /v1/models. Если сочетание временно недоступно, API вернёт 503 без списания.

| Параметр | Поддерживается |
| --- | --- |
| Длительность | 2 / 3 / 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 сек. |
| Разрешения | 480P / 720P / 1080P |
| Соотношения сторон | 16:9 / 9:16 / 1:1 / 4:3 / 3:4 |
| Изображения-референсы | До 10 изображений |
| Видеореференсы | До 5 видео |
| Аудиореференсы | До 5 аудиофайлов |
| Промпт | До 5000 байт UTF-8 (китайский иероглиф обычно занимает 3 байта) |
| Единица тарификации | За секунду готового видео. 480P с видеореференсом: длительность видеореференсов плюс длительность результата. 720P с видеореференсом: длительность видеореференсов плюс длительность результата. 1080P с видеореференсом: длительность видеореференсов плюс длительность результата |
| Срок хранения видео | 72 часа. Скачайте вовремя |

## Параметры запроса

Используйте Content-Type: application/json. Параметры callback_url и n (несколько результатов), первый и последний кадры и потоковая выдача не поддерживаются.

| Параметр | Тип | Обязательно | Описание |
| --- | --- | --- | --- |
| model | string | Да | wan-3.0 |
| prompt | string | Да | Описание видео. Ссылайтесь на файлы как @Image1 / @Video1 / @Audio1. Номер соответствует позиции файла в массиве. |
| duration | integer | Нет | По умолчанию 5 сек. Диапазон см. в характеристиках. Для вертикального Clip явно укажите 15 сек. |
| resolution | string | Нет | По умолчанию 720P. Доступно: 480P, 720P, 1080P |
| 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 (по умолчанию): изображения служат референсами. first_frame: первое изображение — первый кадр, второе — последний (1 или 2 изображения, без референсных видео и аудио). |

## Цены и расчёт стоимости

Цены берутся из той же действующей конфигурации, что и при списании. Резервирование и создание задачи выполняются одной транзакцией. При успехе резерв списывается, при окончательном сбое возвращается.

При разрешении 480P с видеореференсом стоимость равна сумме длительностей видеореференсов и результата, умноженной на $0.03 за секунду. Суммарная длительность видеореференсов округляется вверх до целой секунды. Остаток менее 0.05 сек. отбрасывается. Без видеореференса тариф прежний. Референсные изображения и аудио бесплатны. Для ссылок от нашего API загрузки резерв рассчитывается по фактической длительности. Для остальных ссылок сначала резервируется максимум 30 сек. После измерения до начала генерации разница возвращается. В истории баланса появится запись «Излишек резерва возвращён».

При разрешении 720P с видеореференсом стоимость равна сумме длительностей видеореференсов и результата, умноженной на $0.055 за секунду. Суммарная длительность видеореференсов округляется вверх до целой секунды. Остаток менее 0.05 сек. отбрасывается. Без видеореференса тариф прежний. Референсные изображения и аудио бесплатны. Для ссылок от нашего API загрузки резерв рассчитывается по фактической длительности. Для остальных ссылок сначала резервируется максимум 30 сек. После измерения до начала генерации разница возвращается. В истории баланса появится запись «Излишек резерва возвращён».

При разрешении 1080P с видеореференсом стоимость равна сумме длительностей видеореференсов и результата, умноженной на $0.11 за секунду. Суммарная длительность видеореференсов округляется вверх до целой секунды. Остаток менее 0.05 сек. отбрасывается. Без видеореференса тариф прежний. Референсные изображения и аудио бесплатны. Для ссылок от нашего API загрузки резерв рассчитывается по фактической длительности. Для остальных ссылок сначала резервируется максимум 30 сек. После измерения до начала генерации разница возвращается. В истории баланса появится запись «Излишек резерва возвращён».

| Разрешение | Цена за единицу (USD) | Пример стоимости |
| --- | --- | --- |
| 480P | 0.03 за секунду | 5 сек.: $0.15 |
| 720P | 0.055 за секунду | 5 сек.: $0.28 |
| 1080P | 0.11 за секунду | 5 сек.: $0.55 |
| 480P с видеореференсом | 0.03 за секунду (видеореференс + результат) | 5 сек. результата + 5 сек. видеореференса: $0.30 |
| 720P с видеореференсом | 0.055 за секунду (видеореференс + результат) | 5 сек. результата + 5 сек. видеореференса: $0.55 |
| 1080P с видеореференсом | 0.11 за секунду (видеореференс + результат) | 5 сек. результата + 5 сек. видеореференса: $1.10 |

## Референсы и примеры

Загрузите файлы и проверьте статус задачи загрузки. Получив URL на media.vidbudget.com, поместите его в соответствующий массив. Подходят и публичные HTTPS-ссылки для скачивания. base64 и URI data: не принимаются.

Изображения задают образы персонажей и стиль, видео — движение и работу камеры, аудио — звук и ритм. Доступные типы и количество файлов указаны в характеристиках модели.

Файлы скачиваются и проверяются в фоне. Нечитаемый файл, неподходящий формат или нарушение правил содержимого могут привести к сбою. В этом случае резерв возвращается на баланс.

Правила генерации могут ограничивать использование фотографий реальных людей. Принятие каждого запроса и соответствие результата субъективным ожиданиям не гарантируются.

Видео и загруженные материалы хранятся 72 часа и 72 часа соответственно. Скачайте их вовремя. Временные ссылки не подходят для постоянного хранения.

### JSON · Изображение-референс

```
{
  "model": "wan-3.0",
  "prompt": "Soft light shimmers across the lake as the camera slowly pushes forward",
  "duration": 5,
  "resolution": "720P",
  "aspect_ratio": "16:9",
  "images": [
    "https://media.vidbudget.com/inputs/YOUR_IMAGE_UUID.png"
  ]
}
```

### JSON · Первый и последний кадр

```
{
  "model": "wan-3.0",
  "prompt": "Soft light shimmers across the lake as the camera slowly pushes forward",
  "duration": 5,
  "resolution": "720P",
  "aspect_ratio": "16:9",
  "images": [
    "https://media.vidbudget.com/inputs/FIRST_FRAME_UUID.png",
    "https://media.vidbudget.com/inputs/LAST_FRAME_UUID.png"
  ],
  "image_role": "first_frame"
}
```

## Формат ответа

Ответ на отправку имеет ту же структуру: status равен queued, completed_at равен null, data — пустой массив. При сбое error содержит строковый код ошибки. При успехе или во время работы он равен null.

### JSON · Завершённая задача

```
{
  "id": "TASK_UUID",
  "object": "task",
  "kind": "video",
  "model": "wan-3.0",
  "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 · Обычная загрузка

```
curl https://vidbudget.com/v1/uploads -H "Authorization: Bearer $VIDBUDGET_API_KEY" -F "file=@reference.png"
```

### HTTP · Загрузка большого файла

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

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

```


---

# Vidu Q4 · VidBudget API

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

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

## Быстрый старт: отправьте задачу, проверьте статус и скачайте видео

Генерация видео асинхронная. При успешной отправке API возвращает HTTP 202 и ID задачи. Генерация и обработка файлов идут в фоне. Не ждите готовое видео в ответе на отправку.

Сохраните ID задачи и проверяйте статус каждые 5–10 сек. При обрыве связи продолжайте проверять исходную задачу. Если необходимо отправить запрос снова, используйте тот же ключ идемпотентности и точно те же параметры.

### cURL · Отправка

```
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": "vidu-q4",
  "prompt": "Soft light shimmers across the lake as the camera slowly pushes forward",
  "duration": 5,
  "resolution": "720P",
  "aspect_ratio": "16:9",
  "images": [
    "https://media.vidbudget.com/inputs/YOUR_IMAGE_UUID.png"
  ]
}'
```

### cURL · Проверка статуса

```
curl https://vidbudget.com/v1/videos/jobs/TASK_ID -H "Authorization: Bearer $VIDBUDGET_API_KEY"
```

### Python · Полный цикл опроса

```
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': 'vidu-q4', 'prompt': 'Soft light shimmers across the lake as the camera slowly pushes forward', 'duration': 5, 'resolution': '720P', 'aspect_ratio': '16:9', 'images': ['https://media.vidbudget.com/inputs/YOUR_IMAGE_UUID.png']}, 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 · Полный цикл опроса

```
// 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": "vidu-q4", "prompt": "Soft light shimmers across the lake as the camera slowly pushes forward", "duration": 5, "resolution": "720P", "aspect_ratio": "16:9", "images": ["https://media.vidbudget.com/inputs/YOUR_IMAGE_UUID.png"]})});
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 или журналы.

### HTTP

```
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
Idempotency-Key: YOUR_UNIQUE_REQUEST_ID
```

## Характеристики и ограничения

Эта модель создаёт видео по референсным изображениям: отправьте хотя бы 1 изображение. Референсные изображения описывают персонажей, сцены, товары и стиль; они не задают первый или последний кадр. Убедитесь, что у вас есть право использовать исходные материалы и внешность людей на них.

Доступность сочетаний параметров сейчас указана в availability ответа GET /v1/models. Если сочетание временно недоступно, API вернёт 503 без списания.

| Параметр | Поддерживается |
| --- | --- |
| Длительность | 3 / 4 / 5 / 6 / 7 / 8 / 9 / 10 / 11 / 12 / 13 / 14 / 15 / 16 сек. |
| Разрешения | 720P |
| Соотношения сторон | 16:9 / 9:16 / 1:1 / 4:3 / 3:4 |
| Изображения-референсы | До 10 изображений |
| Видеореференсы | Не поддерживается |
| Аудиореференсы | До 3 аудиофайлов |
| Промпт | До 2000 символов / 6000 байт UTF-8 |
| Единица тарификации | За секунду готового видео |
| Срок хранения видео | 72 часа. Скачайте вовремя |

## Параметры запроса

Используйте Content-Type: application/json. Параметры callback_url и n (несколько результатов), первый и последний кадры и потоковая выдача не поддерживаются.

| Параметр | Тип | Обязательно | Описание |
| --- | --- | --- | --- |
| model | string | Да | vidu-q4 |
| prompt | string | Да | Описание видео. Ссылайтесь на файлы как @Image1 / @Video1 / @Audio1. Номер соответствует позиции файла в массиве. |
| duration | integer | Нет | По умолчанию 5 сек. Диапазон см. в характеристиках. Для вертикального 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. Первый и последний кадры не поддерживаются. |

## Цены и расчёт стоимости

Цены берутся из той же действующей конфигурации, что и при списании. Резервирование и создание задачи выполняются одной транзакцией. При успехе резерв списывается, при окончательном сбое возвращается.

| Разрешение | Цена за единицу (USD) | Пример стоимости |
| --- | --- | --- |
| 720P | 0.065 за секунду | 5 сек.: $0.33 |

## Референсы и примеры

Загрузите файлы и проверьте статус задачи загрузки. Получив URL на media.vidbudget.com, поместите его в соответствующий массив. Подходят и публичные HTTPS-ссылки для скачивания. base64 и URI data: не принимаются.

Изображения задают образы персонажей и стиль, видео — движение и работу камеры, аудио — звук и ритм. Доступные типы и количество файлов указаны в характеристиках модели.

Файлы скачиваются и проверяются в фоне. Нечитаемый файл, неподходящий формат или нарушение правил содержимого могут привести к сбою. В этом случае резерв возвращается на баланс.

Правила генерации могут ограничивать использование фотографий реальных людей. Принятие каждого запроса и соответствие результата субъективным ожиданиям не гарантируются.

Видео и загруженные материалы хранятся 72 часа и 72 часа соответственно. Скачайте их вовремя. Временные ссылки не подходят для постоянного хранения.

### JSON · Изображение-референс

```
{
  "model": "vidu-q4",
  "prompt": "Soft light shimmers across the lake as the camera slowly pushes forward",
  "duration": 5,
  "resolution": "720P",
  "aspect_ratio": "16:9",
  "images": [
    "https://media.vidbudget.com/inputs/YOUR_IMAGE_UUID.png"
  ]
}
```

## Формат ответа

Ответ на отправку имеет ту же структуру: status равен queued, completed_at равен null, data — пустой массив. При сбое error содержит строковый код ошибки. При успехе или во время работы он равен null.

### JSON · Завершённая задача

```
{
  "id": "TASK_UUID",
  "object": "task",
  "kind": "video",
  "model": "vidu-q4",
  "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 · Обычная загрузка

```
curl https://vidbudget.com/v1/uploads -H "Authorization: Bearer $VIDBUDGET_API_KEY" -F "file=@reference.png"
```

### HTTP · Загрузка большого файла

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

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

```


---

# Muse Video · VidBudget API

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

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

## Быстрый старт: отправьте задачу, проверьте статус и скачайте видео

Генерация видео асинхронная. При успешной отправке API возвращает HTTP 202 и ID задачи. Генерация и обработка файлов идут в фоне. Не ждите готовое видео в ответе на отправку.

Сохраните ID задачи и проверяйте статус каждые 5–10 сек. При обрыве связи продолжайте проверять исходную задачу. Если необходимо отправить запрос снова, используйте тот же ключ идемпотентности и точно те же параметры.

### cURL · Отправка

```
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": "muse-video",
  "prompt": "Soft light shimmers across the lake as the camera slowly pushes forward",
  "duration": 5,
  "resolution": "720P",
  "aspect_ratio": "16:9",
  "images": [
    "https://media.vidbudget.com/inputs/YOUR_IMAGE_UUID.png"
  ]
}'
```

### cURL · Проверка статуса

```
curl https://vidbudget.com/v1/videos/jobs/TASK_ID -H "Authorization: Bearer $VIDBUDGET_API_KEY"
```

### Python · Полный цикл опроса

```
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': 'muse-video', 'prompt': 'Soft light shimmers across the lake as the camera slowly pushes forward', 'duration': 5, 'resolution': '720P', 'aspect_ratio': '16:9', 'images': ['https://media.vidbudget.com/inputs/YOUR_IMAGE_UUID.png']}, 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 · Полный цикл опроса

```
// 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": "muse-video", "prompt": "Soft light shimmers across the lake as the camera slowly pushes forward", "duration": 5, "resolution": "720P", "aspect_ratio": "16:9", "images": ["https://media.vidbudget.com/inputs/YOUR_IMAGE_UUID.png"]})});
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 или журналы.

### HTTP

```
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
Idempotency-Key: YOUR_UNIQUE_REQUEST_ID
```

## Характеристики и ограничения

Эта модель создаёт видео по референсным изображениям: отправьте хотя бы 1 изображение. Референсные изображения описывают персонажей, сцены, товары и стиль; они не задают первый или последний кадр. Убедитесь, что у вас есть право использовать исходные материалы и внешность людей на них.

Доступность сочетаний параметров сейчас указана в availability ответа GET /v1/models. Если сочетание временно недоступно, API вернёт 503 без списания.

| Параметр | Поддерживается |
| --- | --- |
| Длительность | 2 / 3 / 4 / 5 / 6 / 7 / 8 / 9 / 10 сек. |
| Разрешения | 720P |
| Соотношения сторон | 16:9 / 9:16 / 1:1 / 4:3 / 3:4 |
| Изображения-референсы | До 9 изображений |
| Видеореференсы | Не поддерживается |
| Аудиореференсы | Не поддерживается |
| Промпт | До 4000 символов / 12000 байт UTF-8 |
| Единица тарификации | За секунду готового видео |
| Срок хранения видео | 72 часа. Скачайте вовремя |

## Параметры запроса

Используйте Content-Type: application/json. Параметры callback_url и n (несколько результатов), первый и последний кадры и потоковая выдача не поддерживаются.

| Параметр | Тип | Обязательно | Описание |
| --- | --- | --- | --- |
| model | string | Да | muse-video |
| prompt | string | Да | Описание видео. Ссылайтесь на файлы как @Image1 / @Video1 / @Audio1. Номер соответствует позиции файла в массиве. |
| duration | integer | Нет | По умолчанию 5 сек. Диапазон см. в характеристиках. Для вертикального 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. Первый и последний кадры не поддерживаются. |

## Цены и расчёт стоимости

Цены берутся из той же действующей конфигурации, что и при списании. Резервирование и создание задачи выполняются одной транзакцией. При успехе резерв списывается, при окончательном сбое возвращается.

| Разрешение | Цена за единицу (USD) | Пример стоимости |
| --- | --- | --- |
| 720P | 0.02 за секунду | 5 сек.: $0.10 |

## Референсы и примеры

Загрузите файлы и проверьте статус задачи загрузки. Получив URL на media.vidbudget.com, поместите его в соответствующий массив. Подходят и публичные HTTPS-ссылки для скачивания. base64 и URI data: не принимаются.

Изображения задают образы персонажей и стиль, видео — движение и работу камеры, аудио — звук и ритм. Доступные типы и количество файлов указаны в характеристиках модели.

Файлы скачиваются и проверяются в фоне. Нечитаемый файл, неподходящий формат или нарушение правил содержимого могут привести к сбою. В этом случае резерв возвращается на баланс.

Правила генерации могут ограничивать использование фотографий реальных людей. Принятие каждого запроса и соответствие результата субъективным ожиданиям не гарантируются.

Видео и загруженные материалы хранятся 72 часа и 72 часа соответственно. Скачайте их вовремя. Временные ссылки не подходят для постоянного хранения.

### JSON · Изображение-референс

```
{
  "model": "muse-video",
  "prompt": "Soft light shimmers across the lake as the camera slowly pushes forward",
  "duration": 5,
  "resolution": "720P",
  "aspect_ratio": "16:9",
  "images": [
    "https://media.vidbudget.com/inputs/YOUR_IMAGE_UUID.png"
  ]
}
```

## Формат ответа

Ответ на отправку имеет ту же структуру: status равен queued, completed_at равен null, data — пустой массив. При сбое error содержит строковый код ошибки. При успехе или во время работы он равен null.

### JSON · Завершённая задача

```
{
  "id": "TASK_UUID",
  "object": "task",
  "kind": "video",
  "model": "muse-video",
  "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 · Обычная загрузка

```
curl https://vidbudget.com/v1/uploads -H "Authorization: Bearer $VIDBUDGET_API_KEY" -F "file=@reference.png"
```

### HTTP · Загрузка большого файла

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

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

```
