VidBudget
muse-video

Muse Video · API

Markdown

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

Асинхронная генерация видео · Посекундная оплата · При сбое оплата не взимается

Попробовать онлайн →

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

Генерация видео асинхронная. При успешной отправке 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"
  ]
}'

Авторизация и заголовки

Создайте ключ 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"

Вебхуки: уведомления о завершении задачи

В разделе «Вебхуки» консоли добавьте до 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())

Вход в VidBudget

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

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

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

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

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

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

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