Как использовать Creatify Boreal API: генерация видео из текста, изображений и аудио

creatify-boreal — это видеомодель на hiapi, которая возвращает готовый клип с уже сведёнными голосом и звуком. Один id модели покрывает три отправные точки: только промпт, промпт плюс опорное изображение или промпт плюс ваш собственный аудиофайл озвучки. Это руководство показывает запрос, цикл опроса и результаты после одного реального запуска генерации.

Вам нужен API-ключ со страницы панели управления hiapi. Все вызовы идут через единый эндпоинт задач POST /v1/tasks.

Поля ввода

Эти поля сверены с актуальной страницей модели и проверены путём отправки на /v1/tasks заведомо недопустимых значений; недопустимые значения возвращают 400 и не тарифицируются.

Поле	Обязательно	Допустимые значения
prompt	Да	Текст, до 5000 символов
image_url	Нет	JPG/PNG/WebP, 10 MB; задаёт субъект и композицию
audio_url	Нет	MP3/WAV/M4A, 15 MB; используются только первые duration секунд
negative_prompt	Нет	До 2000 символов
resolution	Нет	720p, 1080p, 2k
aspect_ratio	Нет	auto, 16:9, 9:16, 1:1, 4:3, 3:4
duration	Нет	Целое число секунд, от 1 до 20

Эти три режима не являются отдельными id моделей. Для генерации видео из текста опустите image_url и audio_url; для генерации видео из изображения добавьте image_url; добавьте audio_url (обычно вместе с изображением), чтобы персонаж в кадре следовал вашей озвучке.

Минимальный рабочий запрос

curl -X POST 'https://api.hiapi.ai/v1/tasks' \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "creatify-boreal",
    "input": {
      "prompt": "Вертикальное UGC-видео в стиле селфи: молодая женщина в яркой спальне поднимает нежно-розовую губную помаду и говорит в камеру: \"Ладно, это единственная помада, которая пережила мою зиму.\" Естественный фоновый шум комнаты.",
      "resolution": "720p",
      "aspect_ratio": "9:16",
      "duration": 4
    }
  }'

В ответе возвращается id задачи:

{"code":200,"data":{"taskId":"tk-hiapi-01M5MJC8NG8E1E0XN9NEJRDBQH"},"message":"success"}

Python: отправка и опрос

import os, time, requests

BASE = "https://api.hiapi.ai/v1/tasks"
HEADERS = {"Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}"}

def create(payload: dict) -> str:
    r = requests.post(BASE, headers=HEADERS, json=payload, timeout=30)
    r.raise_for_status()
    return r.json()["data"]["taskId"]

def wait(task_id: str, every: int = 10, limit: int = 900) -> dict:
    start = time.time()
    while time.time() - start < limit:
        try:
            d = requests.get(f"{BASE}/{task_id}", headers=HEADERS, timeout=30).json()["data"]
        except (requests.RequestException, ValueError):
            time.sleep(every)  # временная сетевая ошибка: продолжаем опрашивать тот же id
            continue
        if d["status"] == "success":
            return d
        if d["status"] == "fail":
            raise RuntimeError(d.get("error"))
        time.sleep(every)
    raise TimeoutError(task_id)

task_id = create({
    "model": "creatify-boreal",
    "input": {
        "prompt": "Вертикальное UGC-видео в стиле селфи: молодая женщина поднимает нежно-розовую губную помаду и говорит в камеру: \"Ладно, это единственная помада, которая пережила мою зиму.\" Естественный фоновый шум комнаты.",
        "resolution": "720p",
        "aspect_ratio": "9:16",
        "duration": 4,
    },
})
result = wait(task_id)
print(result["output"][0]["url"])

Статус последовательно проходит handling, archiving, а затем success. URL видео находится в data.output[0].url.

Режимы изображения и аудио

Для генерации видео из изображения добавляется одно поле:

{"model": "creatify-boreal",
 "input": {"prompt": "Эта женщина на кухне улыбается камере и говорит: \"Я заменила кофе этим овсяным латте-миксом.\" Естественный фоновый шум кухни.",
           "image_url": "https://your-cdn.example/presenter.jpg",
           "resolution": "720p", "duration": 8}}

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

Как выглядит реальный запуск

Я выполнил запрос выше (только текст, 720p, 9:16, 4 секунды).

• Время генерации: задача находилась в статусе handling около 283 секунд, затем в статусе archiving около 10 секунд. Даже для 4-секундного клипа планируйте время в минутах, а не в секундах. Опрашивайте каждые 10 секунд или используйте callback, а не короткий таймаут.
• Выходной файл: MP4 720x1280, видео H.264 24 fps плюс аудиодорожка AAC, длительность 4,04 секунды. Хотя в запросе не было поля аудио, звук всё равно присутствует, что соответствует нативному звуковому дизайну модели.
• Временный URL: выходной URL находится на temp.hiapi.ai с параметром expireAt, истекающим примерно через 7 дней. Скачайте файл и храните его самостоятельно, а не ссылайтесь на него со страницы.
• Структура стоимости: оплата по секундам и зависит от resolution (см. страницу тарифов), поэтому самый дешёвый способ итерации промптов — 720p с коротким duration, а затем повторный рендеринг финальной версии в 1080p или 2k.

Подводные камни, с которыми я столкнулся

• Недопустимые значения быстро отклоняются и бесплатны. Отправка aspect_ratio: "7:5", duration: 25 или resolution: "4k" возвращает HTTP 400 INVALID_REQUEST, а сообщение перечисляет допустимые значения ('auto', '16:9', '9:16', '1:1', '4:3', '3:4', максимум 20, а также '720p', '1080p', '2k'). Используйте это для проверки собственных форм перед отправкой.
• Неверные URL медиафайлов приводят к сбою при последующем опросе. Я отправил audio_url: "https://example.com/a.mp3" (не реальный аудиофайл). Вызов создания вернул HTTP 200 и id задачи, а примерно через 15 секунд задача завершилась со status: "fail" и error.code: "INVALID_REQUEST". Таким образом, HTTP 200 при создании не означает, что ваши медиафайлы доступны; всегда проверяйте конечный статус и читайте data.error. В этом случае сбой проявляется внутри ответа на опрос с HTTP 200, а не как HTTP-ошибка.
• Сбой — это status: "fail", а не HTTP-статус. Сам запрос опроса возвращает 200, поэтому проверяйте data.status.

Связанные страницы

• Страница модели Creatify Boreal: Playground, актуальные тарифы и примеры клипов
• Тарифы hiapi
• Документация hiapi
• Как использовать OmniHuman 1.5 API: ещё одна видеомодель в стиле «персонаж в кадре»
• Ray 3.2 API генерации видео из изображения
• Руководство по Wan 3.0 Video API

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

Нужны ли отдельные id моделей для текста, изображения и аудио? Нет. Все три используют creatify-boreal; режим определяется полями, которые вы включаете в input.

Какой максимальной длины может быть клип? Целое число секунд от 1 до 20. Значение 25 отклоняется с HTTP 400.

Содержит ли выходной файл звук? Да. 4-секундный тестовый клип имеет аудиодорожку AAC, даже если аудио на вход не подавалось.

Какие доступны разрешения? 720p, 1080p и 2k. Тарификация зависит от разрешения; смотрите страницу тарифов.

Сколько ждать? Мой тест 4 секунды 720p занял около пяти минут от начала до конца. Используйте опрос с щедрым лимитом или callback.