HeyGen Avatar IV API

HeyGen Avatar IV API

HeyGen Avatar IV превращает одну фотографию и запись речи в видео, где человек со снимка говорит: губы попадают в слова, лицо живёт, голова и плечи двигаются в такт голосу. Длина видео равна длине записи. Нейросеть берут для виртуального ведущего из портрета, озвученного аватара сотрудника, персонажа для соцсетей, говорящей открытки или объяснения продукта «от лица» основателя.

Отличия от простых «говорящих фото»: текстовым заданием можно подсказать мимику, выбрать силу выражения эмоций, добавить свою картинку в поле «Фон», задать разрешение до 1080p и пропорции кадра.

Каждый вызов создаёт асинхронную операцию. Сохраните id из ответа и проверяйте статус, пока видео не будет готово.

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

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

Режим один - фото плюс аудио. Остальные поля необязательны и уточняют результат:

• минимальный вызов - только image и audio;
• расширенный вызов - те же файлы плюс задание, фон, разрешение, пропорции и выразительность.

Тело запроса

{
  "tool": "heygen-avatar-iv",
  "input": {
    "image": "https://cdn.example.com/portrait.jpg",
    "audio": "https://cdn.example.com/voice.mp3",
    "resolution": "1080p",
    "aspect_ratio": "auto",
    "expressiveness": "low"
  }
}

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

Параметры

Ссылки на файлы должны открываться без авторизации по http/https. Расширение в ссылке должно совпадать с одним из допустимых форматов, иначе API вернёт validation_error.

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

Фото и аудио

Самый короткий вызов: разрешение 1080p, пропорции как у фото, сдержанная мимика.

cURL

curl -X POST https://bratuha.ru/api/v1/operations \
  -H "Authorization: Bearer brth_ваш_ключ" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "heygen-avatar-iv",
  "input": {
    "image": "https://cdn.example.com/portrait.jpg",
    "audio": "https://cdn.example.com/voice.mp3"
  }
}'

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: 'heygen-avatar-iv',
    input: {
      image: 'https://cdn.example.com/portrait.jpg',
      audio: 'https://cdn.example.com/voice.mp3',
    },
  }),
})

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

Python

import requests

response = requests.post(
    'https://bratuha.ru/api/v1/operations',
    headers={
        'Authorization': 'Bearer brth_ваш_ключ',
        'Content-Type': 'application/json',
    },
    json={
        'tool': 'heygen-avatar-iv',
        'input': {
            'image': 'https://cdn.example.com/portrait.jpg',
            'audio': 'https://cdn.example.com/voice.mp3',
        },
    },
    timeout=30,
)

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

Задание, фон, вертикальный кадр и яркая мимика

Пример расширенного вызова: ведущая с заданием и картинкой фона, видео 720p в 9:16. Учтите, что в нашей пробе при 9:16 картинка фона в кадре не появилась: это поле заметно только при пропорциях шире фото.

cURL

curl -X POST https://bratuha.ru/api/v1/operations \
  -H "Authorization: Bearer brth_ваш_ключ" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "heygen-avatar-iv",
  "input": {
    "image": "https://cdn.example.com/host.png",
    "audio": "https://cdn.example.com/intro.wav",
    "background": "https://cdn.example.com/studio-background.jpg",
    "prompt": "Говорит энергично, улыбается, жестикулирует обеими руками, в конце кивает",
    "resolution": "720p",
    "aspect_ratio": "9:16",
    "expressiveness": "high"
  }
}'

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: 'heygen-avatar-iv',
    input: {
      image: 'https://cdn.example.com/host.png',
      audio: 'https://cdn.example.com/intro.wav',
      background: 'https://cdn.example.com/studio-background.jpg',
      prompt:
        'Говорит энергично, улыбается, жестикулирует обеими руками, в конце кивает',
      resolution: '720p',
      aspect_ratio: '9:16',
      expressiveness: 'high',
    },
  }),
})

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

Python

import requests

response = requests.post(
    'https://bratuha.ru/api/v1/operations',
    headers={
        'Authorization': 'Bearer brth_ваш_ключ',
        'Content-Type': 'application/json',
    },
    json={
        'tool': 'heygen-avatar-iv',
        'input': {
            'image': 'https://cdn.example.com/host.png',
            'audio': 'https://cdn.example.com/intro.wav',
            'background': 'https://cdn.example.com/studio-background.jpg',
            'prompt': 'Говорит энергично, улыбается, жестикулирует обеими руками, в конце кивает',
            'resolution': '720p',
            'aspect_ratio': '9:16',
            'expressiveness': 'high',
        },
    },
    timeout=30,
)

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

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

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

Пример для записи длиной 9,3 секунды: длительность округляется вверх до 10 секунд, 10 × 15 ₽ = 150 ₽.

{
  "id": "op_uuid-123",
  "status": "queued",
  "tool": "heygen-avatar-iv",
  "cost": 150,
  "balance_after": 850,
  "created_at": "2026-10-16T12:00:00.000000+00:00"
}

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

{
  "id": "op_uuid-123",
  "status": "completed",
  "tool": "heygen-avatar-iv",
  "cost": 150,
  "created_at": "2026-10-16T12:00:00.000000+00:00",
  "completed_at": "2026-10-16T12:04:10.000000+00:00",
  "result": {
    "type": "video",
    "urls": [
      "https://storage.bratuha.ru/results/heygen-avatar-iv/avatar-1.mp4"
    ]
  },
  "error_message": null
}

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

{
  "id": "op_uuid-123",
  "status": "failed",
  "tool": "heygen-avatar-iv",
  "cost": 150,
  "created_at": "2026-10-16T12:00:00.000000+00:00",
  "completed_at": "2026-10-16T12:02:10.000000+00:00",
  "result": null,
  "error_message": "Произошла ошибка, сервис временно недоступен. Попробуйте повторить запрос позже."
}

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

Сохраните id из ответа на создание и запрашивайте операцию, пока status не станет completed или failed:

GET /api/v1/operations/{id}

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

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

Видео готовится несколько минут, и чем длиннее запись и выше разрешение, тем дольше. Опрашивать одну операцию можно не чаще раза в секунду, иначе API ответит 429.

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

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

{
  "type": "video",
  "urls": [
    "https://storage.bratuha.ru/results/heygen-avatar-iv/avatar-1.mp4"
  ]
}

• type - всегда "video".
• urls - массив ссылок на готовые видео. Для этой нейросети в нём одна ссылка на MP4.

Видео идёт со звуком из вашей записи, его длина совпадает с длиной аудио. Пропорции кадра берутся из aspect_ratio, а при auto - подбираются по фотографии.

Если операция завершилась с ошибкой, result будет null, а причина придёт в error_message.

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

Цена одна: 15 ₽ за секунду аудио. Разрешение, пропорции, задание, фон и выразительность на цену не влияют.

Как считается итог:

1. Сервер сам определяет длительность записи по ссылке audio. Передавать длительность в запросе не нужно.
2. Длительность округляется вверх до целых секунд: 9,3 секунды считаются как 10.
3. Округлённая длительность умножается на 15 ₽.

Примеры:

Итоговая сумма приходит в поле cost сразу в ответе на создание операции и списывается с баланса в этот момент. Если операция завершилась ошибкой, деньги возвращаются на баланс, а cost в ответе остаётся суммой запуска.

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

• Без заголовка Idempotency-Key каждый повторный POST /api/v1/operations создаёт новую операцию и списывает деньги заново. Передайте в этом заголовке UUID - и повтор того же запроса в течение 24 часов вернёт исходную операцию без повторного списания.
• Передайте max_price в теле запроса, чтобы сервер отклонил запуск дороже согласованной суммы до списания.
• Операция выполняется асинхронно: сначала вы получаете queued, результат забираете по id.
• Файлы передаются только внешними http/https URL, доступными без авторизации. Для image и background - jpg, jpeg, png, webp, для audio - mp3, wav, m4a, aac, flac, ogg, opus. Локальные адреса и приватные сети не принимаются.
• Аудио должно длиться от 1 до 300 секунд. Если запись длиннее 5 минут или по ссылке не удалось прочитать её длительность (например, файл повреждён), API сразу вернёт validation_error, операция не создастся и деньги не спишутся.
• Тишина в начале и в конце записи тоже оплачивается, поэтому лучше её обрезать.
• Лучше всего работают фото одного человека анфас или вполоборота, где лицо хорошо видно и не закрыто руками, очками с бликами или волосами. Чистая речь без музыки и шума даёт самую точную синхронизацию губ, пение тоже подходит.
• Задание влияет на мимику и жесты, но не на слова: произносится только то, что есть в аудио. Если задание и expressiveness противоречат друг другу, сильнее сработает expressiveness.
• background не вырезает человека со снимка и не меняет обстановку за его спиной: по нашим пробам картинка идёт в поля, которые появляются, когда aspect_ratio шире фото. Чтобы сменить обстановку, сначала замените фон на самой фотографии.