Как вызывать flux-3-video через API HiAPI: curl, Python и рабочие примеры запросов

Что flux-3-video предоставляет через API

Прежде чем писать первую строку кода, полезно понять, что именно модель flux-3-video умеет через API HiAPI. Это семейство конечных точек охватывает два режима вызова с общей структурой запроса, а также опциональную возможность работы с аудио, которую можно включить или проигнорировать в зависимости от задачи.

Два режима вызова

• Генерация видео из текста — вы отправляете текстовый промпт и получаете новый сгенерированный видеоклип. Используйте этот режим, когда у вас есть только идея и вы хотите, чтобы модель создала движение, композицию и ритм.
• Продолжение видео — вы отправляете существующий видеоклип (или ссылку на него) вместе с инструкцией, и модель продлевает его. Используйте этот режим, когда у вас уже есть материал и вы хотите получить больше контента без видимых стыков.

Нативное аудио

Модель также может создавать нативное аудио вместе с видео; оно управляется опциональными параметрами в том же теле запроса. Поскольку эти параметры необязательны, чисто видеорабочие процессы могут их полностью игнорировать — достаточно опустить аудиополя, и запрос будет вести себя точно так же, как без них.

Ключевая мысль, на которой строится всё дальнейшее руководство: это не два независимых API и не два отдельных руководства. Это две формы одного запроса; как только вы поймёте общий каркас, переключение между ними сведётся к замене нескольких входных данных. Всё остальное — учётные данные, заголовки, идентификатор модели, обработка ответа — остаётся неизменным.

Это сделано намеренно. Это означает, что ваш код аутентификации, обработки ошибок, логики повторов и разбора ответа пишется один раз и переиспользуется в обоих режимах; добавление аудио позже не заставит вас переписывать код.

Аутентификация, конечная точка и структура запроса

Каждый вызов flux-3-video следует одному и тому же каркасу. Освойте его один раз — и оба режима вызова станут вариантами одной темы.

Учётные данные

HiAPI аутентифицирует запросы с помощью API-ключа. Вы передаёте его в заголовке, обычно в виде bearer-токена. Не записывайте ключ в исходный код — читайте его из переменной окружения или менеджера секретов, чтобы он никогда не попадал в систему контроля версий:

export HIAPI_API_KEY="your-key-here"

Конечная точка и идентификатор модели

Вызовы отправляются на базовый URL API HiAPI, а модель явно указывается в теле запроса идентификатором flux-3-video. Указание имени модели в теле запроса, а не жёсткое кодирование в URL, означает, что тот же клиентский код позже можно перенаправить на другую модель, изменив одну строку.

Общая структура тела запроса

Независимо от режима, тело запроса — это JSON-объект, концептуально состоящий из трёх частей:

• Поле model — всегда flux-3-video.
• Входные данные, определяющие режим — в генерации из текста это промпт; в продолжении — исходный видеоклип плюс промпт. Это единственная часть, которая существенно меняется между режимами.
• Опциональные модификаторы — параметры аудио и другие настройки. Если их опустить, вы получите поведение по умолчанию.

Псевдоструктура запроса выглядит так:

{
  "model": "flux-3-video",
  "input": {
    "prompt": "..."
  }
}

Вот и вся идея: идентификатор модели, вложенный объект input, содержащий поля, специфичные для режима, и необязательные ключи, добавляемые только при необходимости. В следующих разделах подробно описана каждая из частей.

Генерация видео из текста: первый рабочий запрос curl

Ниже — минимальный, но полный запрос, создающий видео из промпта. Он предполагает, что HIAPI_API_KEY уже экспортирован в вашей оболочке.

curl -X POST "$HIAPI_BASE_URL/v1/generate" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "flux-3-video",
    "input": {
      "prompt": "A slow dolly shot through a rain-soaked neon alley at night, reflections on wet asphalt, cinematic"
    }
  }'

Роль каждого поля

• Authorization — несёт ваш bearer-токен. Без него запрос будет отклонён ещё до начала какой-либо генерации.
• Content-Type: application/json — тело запроса является JSON, поэтому укажите это; его отсутствие — частая причина непонятных ответов 4xx.
• model — задаёт flux-3-video как целевую модель.
• input.prompt — единственный обязательный творческий вход в режиме генерации из текста. Пишите его как описание кадра: субъект, движение, композиция, свет, атмосфера.

Советы по составлению промптов, которые стоят внимания

Поскольку промпт — единственный рычаг творческого управления в этом режиме, его качество напрямую определяет результат. Помогут две привычки:

• Описывайте движение, а не только содержание. «A dolly shot through…» (проезд камеры через…) даёт модели поведение камеры, которое можно анимировать; статичное описание не оставляет ей пространства для действий.
• Будьте конкретны. Конкретные подсказки о свете и материалах («wet asphalt», «neon reflections») часто дают более связную картинку, чем абстрактные прилагательные.

Выполнив этот запрос и проверив ответ, вы проверили ключ, заголовки и базовое тело запроса — основу всего дальнейшего.

Продолжение видео: продление существующего клипа

Продолжение использует тот же каркас, что и в предыдущем разделе, но форма объекта input меняется. Промпт больше не существует сам по себе — он сочетается с исходным клипом, который модель должна продлить.

curl -X POST "$HIAPI_BASE_URL/v1/generate" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "flux-3-video",
    "input": {
      "prompt": "Continue the camera push forward as the alley opens into a crowded market",
      "video": "<reference-to-existing-clip>"
    }
  }'

Что изменилось по сравнению с генерацией из текста

• Появился видеовход. Вы предоставляете существующий клип, на основе которого модель должна строить продолжение. Это определяющее различие между режимами.
• Промпт становится направляющим, а не порождающим. В генерации из текста вы описываете всю сцену; здесь вы описываете что произойдёт дальше. Пишите это как инструкцию для продолжения: куда движется камера, что входит в кадр, как развивается сцена.
• Всё остальное идентично. Та же конечная точка, те же заголовки, тот же идентификатор модели, та же обёртка input. Ваш клиентский код должен различаться только на этапе построения тела запроса.

Сохраняйте согласованность на стыке

Модель должна соответствовать внешнему виду исходного клипа, чтобы избежать видимого разрыва. Краткие и конкретные инструкции, сохраняющие существующий стиль, часто работают лучше, чем длинные описания, заново придумывающие сцену. Если первое продолжение «уплывает», приблизьте промпт к реальному содержанию исходника, а не добавляйте больше деталей в других местах.

Замечание о ссылках на клип

Точный формат входных данных для исходного клипа определяется схемой входных данных этой модели в HiAPI. Следуйте этой схеме, а не угадывайте формат полей — она является авторитетным источником того, какие входные данные принимаются для продолжения.

Добавление параметров нативного аудио

Именно здесь паттерн опциональных модификаторов раскрывается в полной мере. Параметры аудио находятся в том же объекте input, что и остальные поля, и поскольку они необязательны, запросы из предыдущих двух разделов остаются рабочими и без них.

Где они находятся

Настройки аудио относятся к внутренней части input, наряду с prompt и (в режиме продолжения) video. Концептуально:

{
  "model": "flux-3-video",
  "input": {
    "prompt": "...",
    "audio": {
      "enabled": true
    }
  }
}

Обеспечение безопасности чисто видеорабочих процессов

Важная здесь дисциплина проста: рассматривайте аудиоблок как чисто дополнительный.

• Не устанавливайте аудиополя явно в значение «выключено» — просто опускайте их. Отсутствие блока чище и меньше подвержено конфликтам с будущими изменениями схемы, чем явное отключение.
• Стройте тело запроса инкрементально. Начинайте с минимального тела и добавляйте ключ audio только в той ветке кода, где пользователь действительно запросил аудио. Так ваш путь по умолчанию останется полностью идентичным примерам чистого видео.
• Перед подключением аудио в продакшн сверьтесь со схемой, чтобы подтвердить точное имя флага и допустимые значения. Именование параметров определяется схемой входных данных этой модели в HiAPI; блок выше лишь показывает расположение, но не гарантирует написание полей.

Когда включать

Включайте аудио, когда результат — законченный самодостаточный видеоклип: контент для соцсетей, презентации, короткие нарративные работы. Отключайте, когда вы будете отдельно накладывать собственную музыку или закадровый голос на последующих этапах; генерация аудио, которое вы в итоге отбросите, — это пустая трата вычислительных ресурсов в конвейере.

Поскольку аудио передаётся в том же теле запроса, что и всё остальное, нет отдельного вызова, нет вторых учётных данных и нет необходимости поддерживать дополнительные ветки обработки ответа, кроме чтения того, что возвращает сервис.

Тот же запрос на Python

Переписать вызов curl на Python — механическая работа, поскольку структура запроса идентична. Пример ниже использует только стандартную библиотеку, поэтому работает в любом окружении; если вы предпочитаете requests или httpx, структура отображается напрямую.

import json
import os
import urllib.request

API_KEY = os.environ["HIAPI_API_KEY"]
BASE_URL = os.environ["HIAPI_BASE_URL"]

def generate_video(prompt, video=None, audio=False):
    input_block = {"prompt": prompt}

    # Continuation mode: attach the source clip.
    if video is not None:
        input_block["video"] = video

    # Audio is strictly additive and omitted by default.
    if audio:
        input_block["audio"] = {"enabled": True}

    payload = {"model": "flux-3-video", "input": input_block}

    request = urllib.request.Request(
        f"{BASE_URL}/v1/generate",
        data=json.dumps(payload).encode("utf-8"),
        headers={
            "Authorization": f"Bearer {API_KEY}",
            "Content-Type": "application/json",
        },
        method="POST",
    )

    with urllib.request.urlopen(request) as response:
        return json.loads(response.read().decode("utf-8"))


if __name__ == "__main__":
    # Text-to-video
    result = generate_video(
        "A slow dolly shot through a rain-soaked neon alley at night"
    )
    print(result)

    # Video continuation with native audio
    result = generate_video(
        "Continue the camera push forward as the alley opens into a market",
        video="<reference-to-existing-clip>",
        audio=True,
    )
    print(result)

Почему код организован именно так

• Одна функция, два режима. Параметр video необязателен; когда он равен None, функция формирует запрос генерации из текста. Когда он задан, та же функция формирует запрос продолжения. Нет отдельного клиента и дублирования заголовков.
• Аудио включается явно. Флаг audio по умолчанию равен False, поэтому аудиоблок никогда не добавляется, если он не запрошен явно — в точности тот паттерн, что описан выше.
• Ключ берётся из окружения. API-ключ читается из HIAPI_API_KEY и никогда не жёстко кодируется.

При адаптации просто замените вызов print на действие, необходимое вашему конвейеру — запись ответа в манифест, постановку следующей задачи в очередь или отправку уведомления в очередь. Сама логика запроса менять не требуется.

Диагностика неполадок и чек-лист для продакшна

Когда вызов завершается ошибкой, проверьте следующий список по порядку — он охватывает подавляющее большинство проблем.

Диагностический список

• 401 или ошибка аутентификации — действительно ли HIAPI_API_KEY экспортирован в оболочке или процессе, где выполняется код? Ключ, заданный в одном терминале, не передаётся в cron-задание.
• 415 или неожиданная ошибка разбора — присутствует ли Content-Type: application/json? Его отсутствие — самая типичная причина «молчаливого» сбоя.
• Вызов продолжения возвращает 4xx — содержит ли ваше тело исходный клип в форме, ожидаемой схемой входных данных модели? Ссылка на клип неверного формата приведёт к ошибке ещё до начала генерации.
• В результате отсутствует аудио — действительно ли блок audio попал в тело запроса? При отладке записывайте сериализованное тело запроса; ситуация, когда словарь создан, но ключ забыли добавить, случается легко.
• input пустой или обрезан — распечатайте точный JSON, который вы фактически отправляете. Почти каждая «загадочная» ошибка перестаёт быть загадочной, когда вы видите тело запроса, ушедшее по сети.

Перед выпуском

• Никогда не жёстко кодируйте ключи. Всегда используйте переменные окружения или менеджер секретов.
• Логируйте и тело запроса, и тело ответа, как минимум в среде предварительного развёртывания. Воспроизвести ошибку без точного тела запроса — значит только гадать.
• Относитесь к необязательным полям как к необязательным. Стройте тело инкрементально — сначала минимальное тело, затем добавляйте video, и наконец audio только при необходимости. Это сохраняет ваш путь по умолчанию совпадающим с примерами из документации.
• Оставляйте выбор режима явно видимым в своём коде. Функция с необязательным параметром video — это нормально; булево значение, закопанное на три уровня вглубь, — нет.
• Каждый раз, добавляя поля, перепроверяйте схему входных данных этой модели в HiAPI. Это авторитетный источник по именам параметров и допустимым форматам, и он будет актуальнее любого руководства.

Главную мысль стоит повторить: генерация видео из текста, продолжение и нативное аудио — это три варианта одной формы запроса. Освойте каркас один раз, и каждая новая возможность станет лишь дополнением, а не переписыванием. Удачной разработки.