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. Настройте адрес и ключ
- cURL
- Python SDK (fal-client)
Передавайте ключ хаба в заголовке 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-файла.
Установите пакет fal-client:
pip install fal-client httpx
Задайте три переменные окружения до импорта fal_client (SDK считывает хосты в момент импорта и сам подставляет https://, поэтому указывайте хосты без схемы https://):
export FAL_KEY="sk-ci2-..."
export FAL_QUEUE_RUN_HOST="hub.coreinfra.ai/fal/api"
export FAL_RUN_HOST="hub.coreinfra.ai/fal/run"
Переменная FAL_RUN_HOST направляет синхронные вызовы run() на хаб, чтобы они сразу завершались понятной ошибкой 400 и не отправляли ваш ключ хаба напрямую во внешний сервис.
Отправьте задание через fal_client.subscribe() (или fal_client.submit()), сохраните request_id в колбэке on_enqueue и скачайте готовое видео:
import fal_client
import httpx
result = fal_client.subscribe(
"blackforestlabs/flux-3-max/text-to-video",
arguments={
"prompt": "Бумажный кораблик плывет по вечернему ручью после дождя",
"duration": 5,
"resolution": "720p",
"aspect_ratio": "16:9",
},
with_logs=True,
on_enqueue=lambda request_id: print("request_id:", request_id),
)
video = httpx.get(result["video"]["url"], timeout=300)
video.raise_for_status()
with open("boat.mp4", "wb") as f:
f.write(video.content)
Для генерации видео по первому кадру (blackforestlabs/flux-3-max/image-to-video) кодируйте локальный файл в base64 data URI с помощью fal_client.encode_file() или fal_client.encode_image():
result = fal_client.subscribe(
"blackforestlabs/flux-3-max/image-to-video",
arguments={
"prompt": "Камера плавно отдаляется от кораблика",
"image_url": fal_client.encode_file("first_frame.png"),
"duration": 5,
"resolution": "720p",
},
)
Отличия от 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 SDKfal-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 и на странице «Лимиты и ограничения».
