Как использовать omnihuman-1.5 через hiapi API: curl, Python и готовые к запуску запросы

omnihuman-1.5 берёт одну фотографию портрета и аудиофрагмент и генерирует видео говорящего человека с синхронизацией губ. В hiapi он, как и все остальные медиамодели, работает по единому протоколу асинхронных задач: сначала один вызов POST /v1/tasks для создания задачи, затем опрос (или получение webhook) до готовности URL видео. Это руководство использует реальную схему запросов — сверенную поле за полем с работающим API — поэтому приведённые ниже код на curl и Python можно скопировать и запустить, а не просто примеры.

Что вы создадите

Скрипт, который отправляет изображение лица и звуковую дорожку в omnihuman-1.5 и возвращает MP4-файл, где это лицо говорит в соответствии с аудио с синхронизацией губ. Длительность видеоклипа следует за вашим аудио — поля duration для настройки нет.

Предварительные требования

1. API-ключ hiapi. Создайте его в dashboard; он отправляется как Bearer token с каждым запросом. Формат заголовка см. в документации по аутентификации.
2. Публично доступный URL изображения и URL аудио. omnihuman-1.5 скачивает оба на сервере, поэтому подойдёт любой URL http(s), который анонимно открывается с вашей машины; пути localhost и подписанные URL, истекающие в ходе задачи, — нет.

Это всё — SDK не нужен, аккаунт кроме ключа не требуется.

Схема входных данных

omnihuman-1.5 принимает строгий объект input. Неизвестные поля отклоняются, поэтому это все доступные поля:

Поле	Тип	Обязательность	Описание
image_url	string	Да	URL одного портрета. Лучше всего работают чёткие фронтальные изображения с одним лицом.
audio_url	string	Да	Звуковая дорожка для синхронизации губ. Определяет длительность вывода.
prompt	string	Нет	Необязательное указание для анимации/мимики.
resolution	string	Нет	"720p" или "1080p".

Режима только с текстом нет: audio_url обязателен. Если у вас есть только сценарий, сначала сгенерируйте речь (с помощью TTS-модели или текстового цифрового человека, такого как heygen-avatar-v), а затем передайте полученный URL аудио сюда.

Минимальный рабочий пример (curl)

Создание задачи:

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "omnihuman-1.5",
    "input": {
      "image_url": "https://example.com/portrait.jpg",
      "audio_url": "https://example.com/voiceover.mp3",
      "resolution": "720p"
    }
  }'

Ответ содержит id задачи:

{ "code": 200, "data": { "taskId": "b3f1c2e8-...", "status": "pending" } }

Опрашивайте задачу, пока она не достигнет терминального состояния:

curl -s https://api.hiapi.ai/v1/tasks/b3f1c2e8-... \
  -H "Authorization: Bearer sk-YOUR_KEY"

После завершения data.status равен "success", а видео находится в data.output[0].url:

{
  "code": 200,
  "data": {
    "taskId": "b3f1c2e8-...",
    "status": "success",
    "output": [
      { "url": "https://temp.hiapi.ai/.../omnihuman.mp4", "expireAt": 1760000000 }
    ]
  }
}

URL в output временный (содержит expireAt). Скачивайте MP4 сразу после успеха задачи — не используйте этот адрес для горячих ссылок в продакшене.

Тот же вызов на Python

import time
import requests  # pip install requests

API = "https://api.hiapi.ai/v1/tasks"
KEY = "sk-YOUR_KEY"
HEADERS = {"Authorization": f"Bearer {KEY}", "Content-Type": "application/json"}


def create_task() -> str:
    payload = {
        "model": "omnihuman-1.5",
        "input": {
            "image_url": "https://example.com/portrait.jpg",
            "audio_url": "https://example.com/voiceover.mp3",
            "resolution": "720p",
        },
    }
    r = requests.post(API, headers=HEADERS, json=payload, timeout=60)
    r.raise_for_status()
    return r.json()["data"]["taskId"]


def wait_for_video(task_id: str, timeout: int = 600, interval: int = 5) -> str:
    deadline = time.time() + timeout
    while time.time() < deadline:
        r = requests.get(f"{API}/{task_id}", headers=HEADERS, timeout=30)
        data = r.json()["data"]
        status = data["status"]
        if status == "success":
            return data["output"][0]["url"]
        if status == "fail":
            raise RuntimeError(f"omnihuman-1.5 task failed: {data.get('error')}")
        time.sleep(interval)
    raise TimeoutError(f"task {task_id} did not finish in {timeout}s")


if __name__ == "__main__":
    tid = create_task()
    print("task:", tid)
    video_url = wait_for_video(tid)
    # URLs expire — persist the bytes immediately.
    mp4 = requests.get(video_url, timeout=120).content
    with open("talking_head.mp4", "wb") as f:
        f.write(mp4)
    print("saved talking_head.mp4")

Вывод в продакшен

Предпочитайте callback, а не интенсивный опрос. Добавьте объект верхнего уровня callback, и hiapi отправит завершённую задачу на ваш эндпоинт вместо того, чтобы вы опрашивали:

{
  "model": "omnihuman-1.5",
  "input": {
    "image_url": "https://example.com/portrait.jpg",
    "audio_url": "https://example.com/voiceover.mp3",
    "resolution": "1080p"
  },
  "callback": { "url": "https://your.app/webhooks/hiapi", "when": "final" }
}

when принимает только "final" и срабатывает как при успехе, так и при неудаче — поэтому ваш webhook должен ветвиться по data.status. Тело доставки — тот же объект, что и при GET /v1/tasks/{id}. Доставка имеет семантику «хотя бы один раз», поэтому устраняйте дубликаты по taskId.

Никогда не отправляйте повторно при временной ошибке. Если запрос опроса истёк по таймауту или соединение оборвалось, опрашивайте тот же taskId — не вызывайте POST /v1/tasks снова. Повторная отправка запустит вторую тарифицируемую задачу. Сохраните taskId сразу после его получения.

Обрабатывайте три формы отказа по отдельности:

• Ошибка аутентификации → HTTP 401, тело {"error": {"code": "permission_denied", "type": "hiapi_error", ...}}. Исправьте ключ; не повторяйте попытку.
• Некорректный запрос (отсутствующее/недопустимое поле) → HTTP 400, тело {"code": 400, "error_code": "INVALID_REQUEST", "message": "..."}. В message указано проблемное поле — исправьте и отправьте снова.
• Запущенная, но неудачная задача → HTTP 200 и data.status == "fail" с data.error. Самая частая причина — сервер не может скачать image_url/audio_url. Проверьте, что оба публично доступны и всё ещё действительны. Всегда ветвитесь по data.status, а не только по HTTP-коду состояния.

Цена тарифицируется по секундам вывода и указана на странице pricing; поскольку длительность клипа следует за вашим аудио, стоимость зависит от длительности аудио.

Связанные руководства

• Введение в единый асинхронный API —— контракт создания и опроса /v1/tasks, общий для всех моделей.
• Быстрый старт —— выполните свой первый запрос к hiapi от начала до конца.
• Учебник по HeyGen Avatar IV API —— ещё одна модель фото-в-говорящее-видео, с которой можно сравнить подходы к синхронизации губ.
• HeyGen Avatar V —— цифровой человек, управляемый сценарием (текст-в-видео), когда у вас нет аудиофайла.

Частые вопросы

Можно ли управлять omnihuman-1.5 текстом вместо аудиофайла? Нет. audio_url обязателен, и модель синхронизирует губы с этим аудио. Если нужен процесс от сценария к видео, сначала синтезируйте речь (любым TTS) или используйте текстового цифрового человека, такого как heygen-avatar-v, а затем передайте URL аудио сюда.

Какова длительность выходного видео? Она следует за вашим аудиофрагментом — параметра duration нет. Звуковая дорожка длительностью 12 секунд даст примерно 12-секундное видео.

Какие изображения работают лучше всего? Один портрет человека с чётким освещением, фронтально, по публичному URL. Групповые фото или сильно перекрытые лица дают худшую синхронизацию губ.

720p или 1080p? Оба доступны для resolution. Начинайте с 720p при итерациях; переключайтесь на 1080p для финального рендера. Более высокое разрешение стоит дороже за секунду — см. pricing.

Моя задача сразу возвращает status: "fail". Почему? Почти всегда сервер не может получить какой-либо входной URL. Убедитесь, что image_url и audio_url публично доступны (откройте их в окне инкогнито) и не истекли. Сообщение в data.error поможет сузить круг.

Нужно ли опрашивать или можно использовать webhook? Можно и то, и другое. Для простых скриптов используйте опрос GET /v1/tasks/{id}; в продакшене зарегистрируйте callback.url и установите when в "final", чтобы не держать цикл опроса.