Как использовать hiapi API для AI-редактирования видео с помощью flux-3

Здесь у слова «редактирование» есть особый смысл: flux-3 (FLUX.3 Video от Black Forest Labs) продлевает существующий фрагмент — продолжая его движение, движение камеры и звук и генерируя новые кадры — либо строит кадр на основе упорядоченного набора изображений-ключевых кадров. Он не обрезает, не вырезает, не маскирует, не корректирует цвет и не выполняет какую-либо иную обработку существующего материала на месте. Если вы пришли сюда в поисках видеоредактора, FAQ ниже — это самый быстрый способ понять, подходит ли вам flux-3, ещё до того, как вы напишете хоть строку кода.

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

1. Что вам понадобится

Ключ hiapi API из панели управления (sk-...). flux-3, как и все остальные модели hiapi, вызывается через единый task API, так что здесь нет никакой настройки, специфичной для модели — если вы когда-либо вызывали любую другую видео-модель hiapi, у вас уже всё готово.

2. Минимальный рабочий пример

Создайте задачу, затем опрашивайте её (или используйте callback — см. Режимы для продакшена), пока она не достигнет терминального состояния.

# 1. 创建任务——延续模式（start_video）
curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-<your-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "flux-3",
    "input": {
      "prompt": "继续平移，镜头继续向右漂移，保持相同光照",
      "start_video": "https://your-cdn.example.com/source-clip.mp4",
      "duration": 5,
      "resolution": "720p",
      "aspect_ratio": "16:9",
      "generate_audio": true
    }
  }'
# -> {"data": {"id": "task_...", "status": "pending"}}

# 2. 轮询直到终止
curl -s https://api.hiapi.ai/v1/tasks/task_... \
  -H "Authorization: Bearer sk-<your-key>"
# -> {"data": {"id": "task_...", "status": "succeeded",
#              "output": [{"url": "https://...mp4", "expireAt": "..."}]}}

start_video — это публичный HTTPS-URL, указывающий на MP4 (исходный материал ограничен 50MB и 15 секундами) — именно этот фрагмент flux-3 и продолжает. duration — целое число от 5 до 20 секунд, управляющее длиной нового сгенерированного фрагмента, а не длиной итогового вывода. resolution — 720p или 1080p; aspect_ratio принимает auto, 21:9, 2:1, 16:9, 4:3, 1:1, 3:4 или 9:16. generate_audio — логическое значение: при true сгенерированный моделью окружающий звук напрямую вшивается в выходной MP4, а не поставляется отдельным аудиофайлом. При итерации промптов устанавливайте draft: true; черновые задачи дешевле, но принудительно ограничивают resolution значением 720p (запрос с одновременно draft: true и resolution: "1080p" будет отклонён).

Раскадровка по ключевым кадрам (не редактирование существующего материала)

Другой режим ввода заменяет start_video на image_urls — упорядоченный массив из 1–10 URL изображений, который flux-3 рассматривает как раскадровку и генерирует движение, последовательно связывающее их:

{
  "model": "flux-3",
  "input": {
    "prompt": "平滑地推轨依次穿过每个场景",
    "image_urls": [
      "https://your-cdn.example.com/keyframe-1.jpg",
      "https://your-cdn.example.com/keyframe-2.jpg",
      "https://your-cdn.example.com/keyframe-3.jpg"
    ],
    "duration": 8,
    "resolution": "720p"
  }
}

image_urls и start_video — это две разные формы задачи на одной и той же модели — не отправляйте их одновременно в одном запросе. Используйте image_urls, когда строите кадр с нуля из статичных изображений; используйте start_video, когда у вас уже есть сгенерированный (или исходный) материал, который нужно продлить вперёд.

3. Режимы для продакшена

При масштабировании используйте callback вместо опроса. Передайте объект callback в том же теле запроса, а не опрашивайте в цикле:

{
  "model": "flux-3",
  "input": { "...": "..." },
  "callback": { "url": "https://your-service.example.com/hooks/hiapi", "when": "final" }
}

when: "final" срабатывает один раз, при достижении задачей любого терминального состояния — succeeded и failed оба являются терминальными, поэтому дедуплицируйте обработчик webhook по taskId, а не полагайтесь на то, что callback означает только успех. Опрос GET /v1/tasks/:id лучше подходит для локальной отладки, редких одноразовых задач или как запасной вариант сверки, если callback не дошёл.

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

URL вывода истекают. Поле expireAt в каждой записи вывода — не украшение: независимо от того, узнали вы об успехе из callback или из опроса, сразу после успеха задачи скачивайте видео и сохраняйте его в собственное хранилище.

Ошибки аутентификации. Неверный или отсутствующий ключ возвращает HTTP 401 с телом {"error": {"code": "permission_denied", ...}}. Проверяйте этот статус/код явно, а не предполагайте, что любой не-2xx означает сбой самой генерации — «мой ключ неверен» и «модель отклонила мой ввод» требуют разных исправлений.

Проверяйте URL медиа перед отправкой. start_video и image_urls проверяют тип и формат, но не проверяют, действительно ли файл по этому URL существует или декодируется — синтаксически корректный, но битый URL всё равно создаст задачу, которая упадёт через несколько секунд, а не будет отклонена при отправке. Прежде чем подключать URL к пакетным задачам, убедитесь, что они действительно разрешаются.

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

• Страница модели flux-3 — полный справочник параметров, песочница, а также актуальные цены за секунду и за разрешение для всех трёх режимов (текст-в-видео, раскадровка по ключевым кадрам и продолжение).
• Документация по созданию задач — полный справочник запросов/ответов /v1/tasks, включая опции callback.
• Документация по аутентификации — как работают заголовок Authorization: Bearer sk-... и области действия ключа.
• Управление первым и последним кадром в AI-видео — связанный подход для моделей, интерполирующих между двумя статичными кадрами, если режим раскадровки flux-3 с несколькими ключевыми кадрами недостаточно точен для вашего кадра.
• Цены hiapi — актуальные тарифы (продолжение стоит дороже стандартной генерации, а черновой режим дешевле обоих — смотрите живую страницу, а не жёстко закодированные цифры).

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

Может ли flux-3 обрезать, вырезать, маскировать или корректировать цвет существующего видео? Нет. Режим «видео-в-видео» в flux-3 — это продолжение: он генерирует новые кадры, продолжая субъект, движение камеры и звук исходного фрагмента. Он не изменяет уже существующие кадры. В настоящее время ни одна модель hiapi не выполняет монтажное обрезание/вырезание по таймлайну или редактирование замаскированных областей на видео.

В чём разница между продолжением и раскадровкой по ключевым кадрам? Продолжение (start_video) требует существующего видеофайла и продлевает его. Раскадровка по ключевым кадрам (image_urls) требует только статичных изображений и генерирует движение между ними — исходное видео не нужно. Это взаимоисключающие варианты ввода для одного и того же id модели flux-3.

Можно ли использовать start_video и image_urls в одном запросе? Нет — для каждой задачи выбирается один режим. Отправка обоих не является поддерживаемой формой ввода.

Работает ли draft: true в режиме продолжения? Да, и это более дешёвый способ итерации промптов продолжения перед запуском в полном разрешении — но, как и в стандартном режиме, черновое продолжение ограничено 720p.

Почему моя задача завершилась с ошибкой почти мгновенно, а не за обычное время генерации? Самая частая причина — start_video или элемент image_urls на момент запроса фактически не разрешается в действительный файл — API принимает синтаксически корректные URL, не загружая их синхронно, поэтому битая ссылка проявляется как быстрое состояние failed, а не как ошибка валидации на входе.

Насколько длинным может быть исходный фрагмент в режиме продолжения? Не более 15 секунд и 50MB, в формате MP4. Более длинные или более крупные исходные файлы не принимаются в качестве ввода start_video.