Перейти к содержанию

fal-совместимый API

fal-совместимый API хаба позволяет генерировать видео моделями FLUX 3 Max (blackforestlabs/flux-3-max/text-to-video и blackforestlabs/flux-3-max/image-to-video) через очередь заданий хаба без VPN с помощью обычных HTTP-запросов или Python SDK fal-client.

1. Настройте адрес и ключ​

Передавайте ключ хаба в заголовке Authorization: Key sk-ci2-... (или Authorization: Bearer sk-ci2-...). Создайте задание в очереди:

export COREINFRA_API_KEY='sk-ci2-...'
curl https://hub.coreinfra.ai/fal/api/blackforestlabs/flux-3-max/text-to-video \
-H "Authorization: Key $COREINFRA_API_KEY" \
-H 'Content-Type: application/json' \
-d '{"prompt":"Бумажный кораблик плывет по ручью","duration":5,"resolution":"720p"}'

Ответ вернет request_id, status_url, response_url и cancel_url на домене hub.coreinfra.ai:

{
"status": "IN_QUEUE",
"request_id": "019a7b2e-...",
"response_url": "https://hub.coreinfra.ai/fal/api/blackforestlabs/flux-3-max/requests/019a7b2e-...",
"status_url": "https://hub.coreinfra.ai/fal/api/blackforestlabs/flux-3-max/requests/019a7b2e-.../status",
"cancel_url": "https://hub.coreinfra.ai/fal/api/blackforestlabs/flux-3-max/requests/019a7b2e-.../cancel"
}

Опрашивайте status_url до статуса COMPLETED, затем обязательно прочитайте результат по response_url — в нем придет ссылка video.url для скачивания MP4-файла.

Отличия от API fal​

Общий контракт очереди описан в документации fal Queue API. При работе через хаб действуют следующие правила и ограничения:

  • Доступные модели. Поддерживаются только два API метода FLUX 3 Max: blackforestlabs/flux-3-max/text-to-video и blackforestlabs/flux-3-max/image-to-video. Обращение к любому другому пути в /fal/api/... возвращает ошибку со статус-кодом 404.
  • Только очередь заданий. Синхронные вызовы fal_client.run(), run_async(), stream(), stream_async(), а также WebSocket, Realtime и SSE-потоки статуса (status/stream) не поддерживаются. Вызов /fal/run/... возвращает ошибку со статус-кодом 400 с подсказкой использовать submit() или subscribe().
  • Входные изображения и загрузка файлов. Поля image_url и end_image_url принимают только данные в кодировке base64 (data:image/...;base64,...). Ссылки на внешние ресурсы (http(s)) отклоняются со статус-кодом 422. Не вызывайте fal_client.upload(), upload_file() и upload_image() с ключом хаба — эти функции обращаются к внешнему хранилищу rest.fal.ai напрямую и передадут туда ваш ключ хаба; используйте fal_client.encode_file() или fal_client.encode_image().
  • Проверка параметров и стоимости. Поле duration принимает целое число секунд от 5 до 20 (по умолчанию 5), а resolution — "720p", "1080p", "2K" или "4K" (по умолчанию "720p"). Некорректные значения отклоняются со статус-кодом 422 до запуска задания. Стоимость равна запрошенной длительности duration, умноженной на ставку выбранного разрешения на странице «Тарифы» (подробнее — в разделе «Стоимость видео»).
  • Изоляция заданий и чтение результата. Для проверки статуса, чтения результата или отмены используйте ключ хаба, с помощью которого было создано задание (другой ключ получит ошибку со статус-кодом 404). При работе по HTTP после получения статуса COMPLETED обязательно выполните GET результата (response_url): этот вызов возвращает ссылку на видео и фиксирует расчет по заданию (fal_client.subscribe() и handle.get() делают это автоматически). Прекращение опроса или отказ от чтения результата не отменяют запущенное задание и не делают выполненную генерацию бесплатной.
  • Срок хранения JSON-результата и видео. JSON-ответ результата доступен по response_url в течение 1 часа после завершения генерации (или 6 минут, если размер JSON-ответа составляет 10 КБ и более); прочитайте результат сразу после завершения. Подписанная ссылка video.url (/fal/api/.../requests/{requestId}/content?t=...) действует 7 дней с момента отправки задания и не требует заголовка Authorization — храните ее как секрет и скачивайте нужные видеоролики к себе.
  • Игнорируемые параметры платформы. Вебхуки (webhook_url, query-параметр fal_webhook), заголовки X-Fal-* (приоритеты, таймауты, ретраи, правила хранения) и query-параметры кроме logs (0, 1, true, false при проверке статуса) игнорируются. При скачивании видео поддерживается заголовок Range.
  • JavaScript-клиент @fal-ai/client не поддерживается, так как его браузерный режим proxyUrl рассчитывает на прокси с заголовком x-fal-target-url. Используйте Python SDK fal-client или HTTP-запросы.

Что доступно​

В путях ниже {owner}/{app} — blackforestlabs/flux-3-max, а {path} — text-to-video или image-to-video. Пути указаны относительно https://hub.coreinfra.ai/fal/api:

МетодПутьНазначение и справочник
POST/{owner}/{app}/{path}Постановка задания в очередь
GET/{owner}/{app}/requests/{requestId}/statusСтатус задания в очереди
GET/{owner}/{app}/requests/{requestId}Получение результата генерации
PUT/{owner}/{app}/requests/{requestId}/cancelОтмена задания
GET/{owner}/{app}/requests/{requestId}/content?t=...Скачивание готового видео

Операции статуса, результата и отмены также принимают полный путь с {path}: /{owner}/{app}/{path}/requests/{requestId}[/status|/cancel]. Описание моделей и параметров приведено в карточках FLUX 3 Max Text to Video и FLUX 3 Max Image to Video в каталоге моделей, цены — на странице «Тарифы».

Ошибки​

При временной ошибке связи во время опроса статуса или чтения результата возвращается ответ со статус-кодом 429 и заголовком Retry-After: 1. Python SDK fal-client автоматически повторяет такие запросы; если попытки SDK исчерпаны, само задание продолжает выполняться и его результат можно запросить повторно по сохраненному request_id.

Формат и примеры ошибок очереди и валидации параметров (422) приведены в справочнике fal API. Общие ошибки авторизации, баланса и лимитов расходов описаны в общем справочнике API и на странице «Лимиты и ограничения».