Как вызывать flux-3-max/keyframes-to-video через API HiAPI: руководство по curl и Python

Что на самом деле делает эта интеграция

flux-3-max/keyframes-to-video — это API асинхронных задач для генерации видео по ключевым кадрам. В отличие от синхронных эндпоинтов, возвращающих результат в том же HTTP-ответе, эта модель принимает ваши ключевые кадры, создаёт фоновую задачу и возвращает идентификатор задачи, по которому можно отслеживать прогресс.

Жизненный цикл от начала до конца делится на четыре этапа:

1. Аутентификация — каждый запрос содержит ваш API-ключ HiAPI.
2. Отправка — отправка ключевых кадров и параметров для запуска задачи генерации видео.
3. Опрос — повторные запросы статуса задачи до достижения терминального состояния.
4. Получение — загрузка сгенерированного видео по URL, возвращённому при успешном завершении задачи.

Помните об этом жизненном цикле — он определяет, как писать клиент: отправка и получение результата — это отдельные вызовы, и ваше приложение должно выдерживать задачу, которая занимает от десятков секунд до нескольких минут. Приведённые ниже примеры на curl и Python следуют тем же четырём этапам, поэтому этот процесс можно перенести на любой язык или исполнитель задач.

Получение API-ключа и аутентификация

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

Аутентификация передаётся в каждом запросе в виде HTTP-заголовка:

Authorization: Bearer $HIAPI_API_KEY

На практике храните ключ в переменной окружения и читайте её во время выполнения. Для примеров в shell экспортируйте её один раз за сессию:

export HIAPI_API_KEY="your-key-here"

В Python читайте её через os.environ["HIAPI_API_KEY"], а не жёстко закодированную строку. Добавьте файл .env в .gitignore, а если вы логируете запросы для отладки, маскируйте заголовок Authorization до того, как он попадёт в агрегатор логов. Если ключ когда-либо был раскрыт, немедленно смените его в панели управления.

Создание запроса с помощью curl

Отправка задачи генерации видео означает отправку JSON-тела, в котором указана модель и ваши ключевые кадры. Точные имена полей для входных ключевых кадров и параметров генерации описаны на странице модели, поэтому используйте её как авторитетный источник; приведённая ниже структура показывает форму запроса.

curl -X POST "https://api.hiapi.ai/v1/tasks" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "flux-3-max/keyframes-to-video",
    "input": {
      "keyframes": [
        "https://example.com/frame-01.png",
        "https://example.com/frame-02.png"
      ]
    }
  }'

Что делает каждая часть:

• model — выбирает flux-3-max/keyframes-to-video, чтобы тот же эндпоинт позже можно было направить на другие модели без изменения транспортного кода.
• input.keyframes — упорядоченный список URL изображений. Порядок важен: первый кадр задаёт начало фрагмента, последующие кадры направляют дальнейшие моменты.
• Authorization — описанный выше заголовок bearer.
• Content-Type — обязателен для JSON-тела.

Ответом является объект задачи, содержащий идентификатор. Сохраните этот ID; это дескриптор для каждого последующего опроса.

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

Версия на Python повторяет вызов curl. Использование requests делает код кратким, но стандартная библиотека тоже подойдёт, если вы хотите обойтись без зависимостей.

import os
import requests

API_KEY = os.environ["HIAPI_API_KEY"]
BASE_URL = "https://api.hiapi.ai/v1"


def submit_video_task(keyframe_urls: list[str]) -> str:
    response = requests.post(
        f"{BASE_URL}/tasks",
        headers={
            "Authorization": f"Bearer {API_KEY}",
            "Content-Type": "application/json",
        },
        json={
            "model": "flux-3-max/keyframes-to-video",
            "input": {"keyframes": keyframe_urls},
        },
        timeout=30,
    )
    response.raise_for_status()
    return response.json()["id"]


task_id = submit_video_task([
    "https://example.com/frame-01.png",
    "https://example.com/frame-02.png",
])
print(task_id)

Две детали, которые стоит сохранить: явный timeout, чтобы зависшее соединение не блокировало ваш рабочий процесс навсегда; и raise_for_status(), чтобы 4xx или 5xx проявлялись как исключения, а не как молчаливая ошибочная нагрузка. Держите функцию маленькой и чистой — она должна отправлять задачу и возвращать ID, и ничего больше. Опрос — это отдельная история.

Опрос статуса задачи и получение результата

Генерация видео требует реального времени вычислений, поэтому API не блокируется до появления файла. Вместо этого вы опрашиваете задачу до её завершения. Статус succeeded содержит URL вывода; failed содержит ошибку; любое другое значение означает, что нужно продолжать ждать.

import time
import requests


def wait_for_video(task_id: str, poll_interval: int = 5, max_wait: int = 600) -> str:
    deadline = time.monotonic() + max_wait
    while time.monotonic() < deadline:
        response = requests.get(
            f"{BASE_URL}/tasks/{task_id}",
            headers={"Authorization": f"Bearer {API_KEY}"},
            timeout=30,
        )
        response.raise_for_status()
        task = response.json()

        if task["status"] == "succeeded":
            return task["output"]["video_url"]
        if task["status"] == "failed":
            raise RuntimeError(task.get("error", "task failed"))

        time.sleep(poll_interval)

    raise TimeoutError(f"task {task_id} did not finish in time")

Замечания по проектированию для продакшена:

• Интервал опроса — нескольких секунд достаточно. Частые обращения к эндпоинту увеличивают нагрузку, но не ускоряют выполнение задачи.
• Крайний срок — всегда ограничивайте общее время ожидания и при неудаче громко сообщайте об ошибке, а не зацикливайтесь навсегда.
• Загрузка — возвращаемый URL временный; сразу после успешного завершения задачи загрузите файл и переместите его в собственное хранилище.
• Развязка — в веб-приложении запускайте этот цикл в фоновом рабочем процессе и уведомляйте клиента через webhook или очередь, а не держите HTTP-запрос открытым.

Обработка ошибок и граничных случаев

Большинство сбоев интеграции делятся на четыре категории.

Ошибки аутентификации (401/403). Ключ отсутствует, имеет неверный формат или больше не действителен. Проверьте, что переменная окружения действительно экспортирована в процессе, совершающем вызов — распространённая ловушка: локальный shell работает, а в контейнере или cron-задаче переменная отсутствует.

Ошибки ввода (4xx). Недоступные URL ключевых кадров, неподдерживаемый формат изображения или параметры вне допустимого диапазона приведут к отклонению отправки. Перед отправкой проверьте, что каждый URL ключевого кадра общедоступен; медленные или ограниченные хосты — самая частая причина отказа seemingly корректных запросов.

Сбой задачи. Задача может быть принята, а затем завершиться неудачей во время генерации. Всегда проверяйте поле ошибки, а не считайте завершённый опрос успехом. Записывайте ID задачи вместе с ошибкой, чтобы можно было связать её с обращением в поддержку.

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

Последняя гигиеническая рекомендация: никогда не логируйте заголовок Authorization, а если URL ключевых кадров содержит подписанную строку запроса, очищайте её. Если возникнут сомнения по поводу имён полей или ограничений этой модели, обратитесь к документации flux-3-max/keyframes-to-video и точно повторяйте эти значения в своём клиенте.