Vidu Q3 Drama API

Vidu Q3 Drama API

Vidu Q3 Drama снимает короткую сцену по сценарию: вы описываете кадры, реплики и движение камеры, а героев, место действия и важные предметы задаёте отдельными референсами - ассетами. Модель держит внешность персонажей по их фотографиям, собирает сцену из нескольких планов и озвучивает реплики. Подходит для коротких сериалов, роликов с одними и теми же героями, раскадровок и рекламных мини-историй. Длина ролика - от 2 до 30 секунд.

Каждый вызов создаёт асинхронную операцию. После запуска сохраните id и проверяйте статус отдельным запросом.

Создание операции

• Endpoint: POST /api/v1/operations
• Авторизация: Authorization: Bearer brth_...
• Выполнение асинхронное: запрос сразу возвращает id операции и стартовый статус queued.

Основа запроса во всех сценариях одна: название name, сценарий content и массив ассетов assets. Дальше два варианта:

• сцена только по ассетам - без image, placement: "panorama" (так работает по умолчанию);
• сцена с изображением для позиционирования - дополнительная картинка image, которая подсказывает модели расстановку героев и композицию кадра; как её использовать, задаёт placement.

Тело запроса

{
  "tool": "vidu-q3-drama",
  "input": {
    "...": "..."
  }
}

• tool - slug нейросети, всегда "vidu-q3-drama".
• input - параметры запуска. Все поля передаются прямо внутри этого объекта, без дополнительной вложенности.

Параметры

Поля элемента assets:

Ссылки на картинки передавайте как внешние http/https URL. Файл должен открываться без авторизации, размер - до 128 МБ.

Примеры запросов

Сцена по ассетам

Три ассета: два персонажа и место действия. В сценарии каждый упомянут по номеру.

cURL

curl -X POST https://bratuha.ru/api/v1/operations \
  -H "Authorization: Bearer brth_ваш_ключ" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "vidu-q3-drama",
  "input": {
    "name": "Утро в пекарне",
    "content": "Кадр 1: утро, пекарня (03). Пекарь (01) выкладывает горячие круассаны на прилавок, над дверью звенит колокольчик.\nКадр 2: входит покупательница (02), стряхивает снег с пальто и говорит: \"Two croissants, please.\"\nКадр 3: крупный план пекаря, он улыбается и отвечает: \"Straight from the oven.\"",
    "assets": [
      {
        "id": "01",
        "name": "Пекарь",
        "type": "character",
        "image_uri": "https://cdn.example.com/baker-1.jpg",
        "description": "Мужчина около 45 лет, короткая борода, очки, белый фартук"
      },
      {
        "id": "02",
        "name": "Покупательница",
        "type": "character",
        "image_uri": "https://cdn.example.com/customer-2.jpg",
        "description": "Женщина около 30 лет, русые волосы, зелёное пальто"
      },
      {
        "id": "03",
        "name": "Пекарня",
        "type": "scene",
        "image_uri": "https://cdn.example.com/bakery-3.jpg",
        "description": "Маленькая пекарня: кирпичная печь, полки с хлебом, витрина"
      }
    ],
    "placement": "panorama",
    "quality": "high",
    "duration": 8,
    "resolution": "1080p",
    "aspect_ratio": "16:9",
    "style": "реалистично"
  }
}'

JavaScript / TypeScript

const response = await fetch('https://bratuha.ru/api/v1/operations', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer brth_ваш_ключ',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    tool: 'vidu-q3-drama',
    input: {
      name: 'Утро в пекарне',
      content: 'Кадр 1: утро, пекарня (03). Пекарь (01) выкладывает горячие круассаны на прилавок, над дверью звенит колокольчик.\nКадр 2: входит покупательница (02), стряхивает снег с пальто и говорит: "Two croissants, please."\nКадр 3: крупный план пекаря, он улыбается и отвечает: "Straight from the oven."',
      assets: [
        {
          id: '01',
          name: 'Пекарь',
          type: 'character',
          image_uri: 'https://cdn.example.com/baker-1.jpg',
          description: 'Мужчина около 45 лет, короткая борода, очки, белый фартук',
        },
        {
          id: '02',
          name: 'Покупательница',
          type: 'character',
          image_uri: 'https://cdn.example.com/customer-2.jpg',
          description: 'Женщина около 30 лет, русые волосы, зелёное пальто',
        },
        {
          id: '03',
          name: 'Пекарня',
          type: 'scene',
          image_uri: 'https://cdn.example.com/bakery-3.jpg',
          description: 'Маленькая пекарня: кирпичная печь, полки с хлебом, витрина',
        },
      ],
      placement: 'panorama',
      quality: 'high',
      duration: 8,
      resolution: '1080p',
      aspect_ratio: '16:9',
      style: 'реалистично',
    },
  }),
})

const data = await response.json()
console.log(data.id, data.status)

Python

import requests

response = requests.post(
    'https://bratuha.ru/api/v1/operations',
    headers={
        'Authorization': 'Bearer brth_ваш_ключ',
        'Content-Type': 'application/json',
    },
    json={
        'tool': 'vidu-q3-drama',
        'input': {
            'name': 'Утро в пекарне',
            'content': 'Кадр 1: утро, пекарня (03). Пекарь (01) выкладывает горячие круассаны на прилавок, над дверью звенит колокольчик.\nКадр 2: входит покупательница (02), стряхивает снег с пальто и говорит: "Two croissants, please."\nКадр 3: крупный план пекаря, он улыбается и отвечает: "Straight from the oven."',
            'assets': [
                {
                    'id': '01',
                    'name': 'Пекарь',
                    'type': 'character',
                    'image_uri': 'https://cdn.example.com/baker-1.jpg',
                    'description': 'Мужчина около 45 лет, короткая борода, очки, белый фартук',
                },
                {
                    'id': '02',
                    'name': 'Покупательница',
                    'type': 'character',
                    'image_uri': 'https://cdn.example.com/customer-2.jpg',
                    'description': 'Женщина около 30 лет, русые волосы, зелёное пальто',
                },
                {
                    'id': '03',
                    'name': 'Пекарня',
                    'type': 'scene',
                    'image_uri': 'https://cdn.example.com/bakery-3.jpg',
                    'description': 'Маленькая пекарня: кирпичная печь, полки с хлебом, витрина',
                },
            ],
            'placement': 'panorama',
            'quality': 'high',
            'duration': 8,
            'resolution': '1080p',
            'aspect_ratio': '16:9',
            'style': 'реалистично',
        },
    },
    timeout=30,
)

print(response.status_code)
print(response.json())

Сцена с изображением для позиционирования

Помимо ассетов передаётся image - эскиз или кадр, по которому модель расставляет героев. Здесь его используют как загруженный референс (placement: "upload").

cURL

curl -X POST https://bratuha.ru/api/v1/operations \
  -H "Authorization: Bearer brth_ваш_ключ" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "vidu-q3-drama",
  "input": {
    "name": "Находка в саду",
    "content": "Кадр 1: сад у дома (02). Мальчик (01) копает грядку и находит старую шкатулку (03).\nКадр 2: крупный план, он открывает крышку и замирает от удивления.",
    "assets": [
      {
        "id": "01",
        "name": "Мальчик",
        "type": "character",
        "image_uri": "https://cdn.example.com/boy-1.png"
      },
      {
        "id": "02",
        "name": "Сад",
        "type": "scene",
        "image_uri": "https://cdn.example.com/garden-2.png"
      },
      {
        "id": "03",
        "name": "Шкатулка",
        "type": "tool",
        "image_uri": "https://cdn.example.com/box-3.png",
        "description": "Деревянная шкатулка с медными уголками"
      }
    ],
    "image": "https://cdn.example.com/layout-1.jpg",
    "placement": "upload",
    "quality": "standard",
    "duration": 5,
    "resolution": "720p",
    "aspect_ratio": "9:16"
  }
}'

JavaScript / TypeScript

const response = await fetch('https://bratuha.ru/api/v1/operations', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer brth_ваш_ключ',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    tool: 'vidu-q3-drama',
    input: {
      name: 'Находка в саду',
      content: 'Кадр 1: сад у дома (02). Мальчик (01) копает грядку и находит старую шкатулку (03).\nКадр 2: крупный план, он открывает крышку и замирает от удивления.',
      assets: [
        {
          id: '01',
          name: 'Мальчик',
          type: 'character',
          image_uri: 'https://cdn.example.com/boy-1.png',
        },
        {
          id: '02',
          name: 'Сад',
          type: 'scene',
          image_uri: 'https://cdn.example.com/garden-2.png',
        },
        {
          id: '03',
          name: 'Шкатулка',
          type: 'tool',
          image_uri: 'https://cdn.example.com/box-3.png',
          description: 'Деревянная шкатулка с медными уголками',
        },
      ],
      image: 'https://cdn.example.com/layout-1.jpg',
      placement: 'upload',
      quality: 'standard',
      duration: 5,
      resolution: '720p',
      aspect_ratio: '9:16',
    },
  }),
})

const data = await response.json()
console.log(data.id, data.status)

Python

import requests

response = requests.post(
    'https://bratuha.ru/api/v1/operations',
    headers={
        'Authorization': 'Bearer brth_ваш_ключ',
        'Content-Type': 'application/json',
    },
    json={
        'tool': 'vidu-q3-drama',
        'input': {
            'name': 'Находка в саду',
            'content': 'Кадр 1: сад у дома (02). Мальчик (01) копает грядку и находит старую шкатулку (03).\nКадр 2: крупный план, он открывает крышку и замирает от удивления.',
            'assets': [
                {
                    'id': '01',
                    'name': 'Мальчик',
                    'type': 'character',
                    'image_uri': 'https://cdn.example.com/boy-1.png',
                },
                {
                    'id': '02',
                    'name': 'Сад',
                    'type': 'scene',
                    'image_uri': 'https://cdn.example.com/garden-2.png',
                },
                {
                    'id': '03',
                    'name': 'Шкатулка',
                    'type': 'tool',
                    'image_uri': 'https://cdn.example.com/box-3.png',
                    'description': 'Деревянная шкатулка с медными уголками',
                },
            ],
            'image': 'https://cdn.example.com/layout-1.jpg',
            'placement': 'upload',
            'quality': 'standard',
            'duration': 5,
            'resolution': '720p',
            'aspect_ratio': '9:16',
        },
    },
    timeout=30,
)

print(response.status_code)
print(response.json())

Примеры ответов

Ответ после создания

{
  "id": "op_uuid-123",
  "status": "queued",
  "tool": "vidu-q3-drama",
  "cost": 28,
  "balance_after": 972,
  "created_at": "2026-10-01T16:10:38.940103+00:00"
}

Ответ после завершения

{
  "id": "op_uuid-123",
  "status": "completed",
  "tool": "vidu-q3-drama",
  "cost": 28,
  "created_at": "2026-10-01T16:10:38.940103+00:00",
  "completed_at": "2026-10-01T16:17:24.194731+00:00",
  "result": {
    "type": "video",
    "urls": [
      "https://storage.bratuha.ru/results/vidu-q3-drama/video-1.mp4"
    ]
  },
  "error_message": null
}

Ответ при ошибке

Если модель не смогла сделать ролик, операция завершается со статусом failed, в result приходит null, а причина - в error_message. Списанная сумма возвращается на баланс.

{
  "id": "op_uuid-123",
  "status": "failed",
  "tool": "vidu-q3-drama",
  "cost": 112,
  "created_at": "2026-10-01T16:10:38.940103+00:00",
  "completed_at": "2026-10-01T17:10:59.000000+00:00",
  "result": null,
  "error_message": "Превышено время ожидания (60 мин). Нейросеть временно недоступна."
}

Проверка статуса

Сохраните id из ответа на создание и проверяйте операцию по нему:

GET /api/v1/operations/{id}

curl -H "Authorization: Bearer brth_ваш_ключ" \
  https://bratuha.ru/api/v1/operations/op_uuid-123

async function waitForResult(id: string) {
  while (true) {
    const response = await fetch(`https://bratuha.ru/api/v1/operations/${id}`, {
      headers: { Authorization: 'Bearer brth_ваш_ключ' },
    })
    const operation = await response.json()
    if (operation.status === 'completed' || operation.status === 'failed') {
      return operation
    }
    await new Promise((resolve) => setTimeout(resolve, 15000))
  }
}

Статус меняется так: queued - в очереди, processing - ролик снимается, затем completed или failed. Ролик делается долго: двухсекундная сцена в 720p в пробном запуске была готова через 7 минут, восьмисекундная в 1080p - примерно через 11 минут. Одну операцию можно опрашивать не чаще раза в секунду, разумный интервал - 15-30 секунд.

Формат результата

После завершения в result приходит одно видео:

{
  "type": "video",
  "urls": [
    "https://storage.bratuha.ru/results/vidu-q3-drama/video-1.mp4"
  ]
}

• type - всегда "video".
• urls - массив с одной ссылкой на MP4 со звуком: реплики, шумы и музыка.
• Ролик идёт с частотой 24 кадра в секунду и длится почти на секунду дольше заказанного: при duration: 2 файл длится около 2,9 секунды, при duration: 8 - около 9 секунд. Цена считается по duration, а не по длине файла.
• Размер кадра соответствует resolution и aspect_ratio: вертикальный 9:16 в 720p приходит размером 720x1280, горизонтальный 16:9 в 1080p - 1920x1080.

Ценообразование

Цена - 14 ₽ за секунду ролика: duration × 14 ₽. Качество, разрешение, пропорции, число ассетов и изображение для позиционирования на цену не влияют.

Самый дешёвый запуск - 2 секунды за 28 ₽. Запрос со значениями по умолчанию (8 секунд) стоит 112 ₽. Сумма списывается при создании операции и видна в поле cost.

Ограничения и практические заметки

• POST /api/v1/operations не идемпотентен: каждый повторный запрос создаёт новую платную операцию. Если ответ на создание потерялся, не отправляйте запрос вслепую ещё раз - сначала проверьте историю операций в личном кабинете.
• Операция выполняется асинхронно: сначала приходит queued, результат забирайте через GET /api/v1/operations/{id}.
• Все ссылки на картинки, включая image_uri внутри assets, - только внешние http/https URL на jpg, jpeg, png или webp. Адреса localhost и внутренних сетей не принимаются.
• id ассета - строка из двух цифр ("01"…"14"). Это самая частая ошибка интеграции: число 1 или строка "1" не проходят проверку.
• duration - целое число от 2 до 30. Значение вроде 7.5 вернёт 400 validation_error.
• В style не ставьте знаки препинания: кино, реализм не пройдёт проверку, кинореализм или реалистично - пройдёт.
• Пишите сценарий по кадрам («Кадр 1: …, Кадр 2: …») и упоминайте ассеты по номерам - так модель точнее понимает, кто в каком плане. Реплики надёжнее писать в кавычках по-английски: английскую речь модель произносит слово в слово.
• Генерация долгая. Иногда модель не укладывается в отведённый час - тогда операция завершается failed с сообщением «Превышено время ожидания (60 мин). Нейросеть временно недоступна.», а деньги возвращаются на баланс.