FLUX 3 Max API: генерация видео из текста, из изображения и по ключевым кадрам на hiapi

Краткое содержание

• FLUX 3 Max на hiapi — это три отдельные ID моделей на одном эндпоинте POST /v1/tasks: flux-3-max/text-to-video, flux-3-max/image-to-video и flux-3-max/keyframes-to-video. Для смены режима достаточно изменить model и одно поле ввода.
• Все три генерируют клипы длительностью 5–20 секунд в 720p или 1080p, оплата рассчитывается по секундам выходного видео и разрешению. Актуальные цены смотрите на /en/pricing.
• Правила номеров кадров для ключевых кадров не проверяются при отправке. При ошибочном таймлайне API всё равно возвращает HTTP 200 и taskId, но задача завершается с ошибкой примерно через 2 секунды. Проверяйте локально заранее.

Это руководство посвящено уровню Max. Базовую модель flux-3 с черновым режимом и продолжением видео см. в руководстве по FLUX.3 Video API, редактирование существующих материалов — в редактировании видео flux-3.

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

Создайте ключ в консоли hiapi и экспортируйте его:

export HIAPI_KEY=sk-your-key

Поток запросов одинаков для всех режимов: POST /v1/tasks возвращает taskId, затем опрашивайте GET /v1/tasks/<taskId> (или используйте callback), пока status не станет success, после чего скачайте data.output[0].url.

Какой ID модели выбрать для разных входных данных

Что у вас есть на входе	ID модели	Какое поле ввода менять
Только текстовый запрос	flux-3-max/text-to-video	prompt
Одно статичное изображение (опционально ещё кадр конца)	flux-3-max/image-to-video	image_url, опционально end_image_url
От 1 до 10 изображений, привязанных к конкретным моментам времени	flux-3-max/keyframes-to-video	keyframes: [{image_url, frame_index}]

Общие опциональные поля для всех трёх: duration (целое число секунд, 5–20, по умолчанию 5), resolution (720p или 1080p), aspect_ratio (auto, 21:9, 2:1, 16:9, 4:3, 1:1, 3:4, 9:16), generate_audio (логическое значение, по умолчанию включено) и reasoning_level (low или high, по умолчанию high). Страницы моделей: текст в видео, изображение в видео, ключевые кадры в видео.

Минимальный пример: генерация видео из текста с помощью curl

curl -X POST "https://api.hiapi.ai/v1/tasks" \
  -H "Authorization: Bearer $HIAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "flux-3-max/text-to-video",
    "input": {
      "prompt": "медленный аэросъёмка океанских волн на рассвете, фотореалистично",
      "duration": 5,
      "resolution": "720p",
      "generate_audio": false,
      "reasoning_level": "low"
    }
  }'

При валидном запросе возвращается {"code":200,"data":{"taskId":"tk-hiapi-..."},"message":"success"}. Затем:

curl https://api.hiapi.ai/v1/tasks/tk-hiapi-... -H "Authorization: Bearer $HIAPI_KEY"

Конфигурация с generate_audio и 5-секундной генерацией с low reasoning — недорогой способ проверить качество запроса; на странице модели указано, что аудио не влияет на цену.

Один вспомогательный скрипт на Python для всех трёх режимов

# pip install requests
import os, time, requests

KEY = os.environ["HIAPI_KEY"]
H = {"Authorization": f"Bearer {KEY}"}
BASE = "https://api.hiapi.ai/v1/tasks"

def submit(mode: str, **inp) -> str:
    """mode: text-to-video | image-to-video | keyframes-to-video"""
    body = {"model": f"flux-3-max/{mode}", "input": inp}
    res = requests.post(BASE, json=body, headers=H, timeout=30).json()
    if res.get("code") != 200:
        # sync 400s look like {"code":400,"error_code":"INVALID_REQUEST","message":"invalid input: ..."}
        raise RuntimeError(res)
    return res["data"]["taskId"]

def wait(task_id: str, timeout_s: int = 900, every: int = 10) -> str:
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        d = requests.get(f"{BASE}/{task_id}", headers=H, timeout=30).json()["data"]
        if d["status"] == "success":
            return d["output"][0]["url"]
        if d["status"] == "fail":
            raise RuntimeError(d.get("error"))
        time.sleep(every)
    raise TimeoutError(task_id)

# 1) text-to-video
t2v = submit("text-to-video",
    prompt="Один белый кроссовок медленно вращается на мокром чёрном подиуме, студийный свет софтбокса, макросъёмка продукта",
    duration=5, resolution="720p", aspect_ratio="16:9", generate_audio=False)

# 2) image-to-video: first frame, optional last frame
i2v = submit("image-to-video",
    prompt="Утренний туман плывёт над гаванью; лодки мягко покачиваются, камера медленно движется вперёд.",
    image_url="https://example.com/harbor.jpg",
    # end_image_url="https://example.com/harbor-end.jpg",   # optional fixed ending
    duration=5, resolution="720p", generate_audio=False)

# 3) keyframes-to-video
FPS = 24
def keyframes_ok(duration: int, frames: list[dict]) -> None:
    idx = [f["frame_index"] for f in frames]
    assert 1 <= len(frames) <= 10, "1-10 keyframes"
    assert len(set(idx)) == len(idx), "frame_index must be unique"
    assert all(0 <= i <= duration * FPS for i in idx), f"frame_index must be 0..{duration * FPS}"

frames = [
    {"image_url": "https://example.com/harbor.jpg", "frame_index": 0},
    {"image_url": "https://example.com/latte.jpg",  "frame_index": 120},
]
keyframes_ok(5, frames)
kf = submit("keyframes-to-video",
    prompt="Непрерывный кинематографичный морфинг из туманной гавани в крупный план холодного матча-латте.",
    keyframes=frames, duration=5, resolution="720p", generate_audio=False)

url = wait(kf)
open("clip.mp4", "wb").write(requests.get(url).content)

URL вывода истекают, поэтому после успешного завершения задачи сразу скачивайте или копируйте файл, а не сохраняйте ссылку.

Ключевые кадры: как работает таймлайн

frame_index — это позиция на 24-кадровой шкале времени с отсчётом от 0, а не процент. Максимально допустимое значение — duration × 24: 120 для 5 секунд, 240 для 10 секунд, 480 для 20 секунд. Индексы должны быть уникальными, можно передать от 1 до 10 ключевых кадров. Для чистого перехода от A к B поставьте первый якорь на 0, а последний на duration × 24; сдвиг последнего якоря назад сохраняет концовку, сдвиг вперёд сжимает изменения. Соблюдайте одинаковое соотношение сторон для всех ключевых кадров; для бесшовного цикла сделайте так, чтобы первое и последнее изображения выглядели как один и тот же момент.

Замечания для продакшена

• Опрос и callback. Task API принимает callback.url и when: "final", что избавляет от необходимости опрашивать; опрос раз в 10 секунд, как выше, тоже подходит для скриптов и пакетных задач.
• Всегда задавайте тайм-аут для цикла опроса и сохраняйте taskId до начала опроса, чтобы падение программы не привело к потере уже оплаченной задачи.
• Скачивайте сразу. Считайте output[0].url кратковременным.
• Контроль затрат. Оплата рассчитывается по секундам выходного видео и разрешению, поэтому 20-секундный клип 1080p стоит в несколько раз дороже теста на 5 секунд и 720p. Прототипируйте на 5 секундах и 720p, повышайте оба параметра после того, как запрос покажет хороший результат. Актуальные тарифы см. на странице цен.

Что я тестировал, а что нет

Эти проверки выполнялись 23 октября 2026 года против продакшен-API с использованием тестового ключа только для чтения. В этой статье не выполнялся рендеринг полных клипов, поэтому я не делаю никаких утверждений о качестве вывода; примеры запросов взяты из примеров на страницах моделей.

Синхронная валидация (HTTP 400, без постановки в очередь). Значения вне допустимого диапазона отклоняются при отправке с error_code: INVALID_REQUEST и читаемым message:

Запрос	Ответ message
duration: 3	invalid input: duration: minimum: got 3, want 5
resolution: "4k"	value must be one of '720p', '1080p'
aspect_ratio: "5:4"	value must be one of 'auto', '21:9', '2:1', '16:9', '4:3', '1:1', '3:4', '9:16'
reasoning_level: "medium"	value must be one of 'low', 'high'
В image-to-video использован image_urls вместо image_url	image_url: missing required field "image_url"; ... additional properties 'image_urls' not allowed

Последняя строка — распространённая ошибка: другие модели hiapi с изображениями на входе используют поле во множественном числе, но FLUX 3 Max image-to-video принимает только один image_url. Неизвестные поля отклоняются, а не игнорируются.

Ошибки таймлайна ключевых кадров асинхронны. Я отправил два 5-секундных запроса с ключевыми кадрами, и оба имели проблемы с таймлайном: в одном использовался frame_index: 121 (превышает лимит 120), в другом оба ключевых кадра были с frame_index: 0. Оба были приняты, вернув HTTP 200 и taskId. Примерно через 1–2 секунды после создания опрос вернул терминальное состояние:

{"code":200,"data":{"status":"fail","model":"flux-3-max/keyframes-to-video",
 "error":{"code":"INVALID_REQUEST","message":"Invalid request parameters for this model. Please check the request and try again."},
 "taskId":"tk-hiapi-..."},"message":"success"}

Отсюда следуют два вывода. Во-первых, то, что отправка возвращает 200, не означает, что таймлайн validен, поэтому при опросе проверяйте status и error.code. Во-вторых, сообщение об ошибке слишком общее и не указывает, какой кадр проблемный, поэтому проверка keyframes_ok выше стоит того, чтобы запускать её перед отправкой. На странице модели указано, что за неудачные задачи плата не взимается; я не проверял записи о списаниях для этих двух задач.

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

Какой ID модели использовать для первого и последнего кадра? Используйте flux-3-max/image-to-video, передав image_url и end_image_url. Ключевые кадры нужны только тогда, когда требуется задать якоря между началом и концом.

Увеличивает ли количество ключевых кадров стоимость? Согласно странице модели, нет: оплата рассчитывается по секундам выходного видео и разрешению, количество якорей не влияет на цену.

Чем это отличается от flux-3? flux-3-max/* — это отдельные ID моделей, разделённые по режимам (текст, изображение, ключевые кадры); базовая flux-3 — один ID, который переключает режим в зависимости от ввода и также поддерживает черновой режим и продолжение. См. руководство по FLUX.3 Video API. Я не сравнивал качество вывода обоих вариантов, поэтому выбирайте по возможностям и тарифам на странице цен.

Можно ли использовать другую модель image-to-video? Да. Другие решения для изображения в видео см. в руководстве по использованию Ray 3.2 Image-to-Video API.