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

Настройка HTTP-вызовов и Python SDK fal-client для генерации видео FLUX 3 Max через очередь заданий CoreInfra AI Hub.

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**

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

```bash
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`:

```json
{
  "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-файла.

**Python SDK (fal-client)**

Установите пакет `fal-client`:

```bash
pip install fal-client httpx
```

Задайте три переменные окружения **до импорта `fal_client`** (SDK считывает хосты в момент импорта и сам подставляет `https://`, поэтому указывайте хосты **без схемы** `https://`):

```bash
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` и скачайте готовое видео:

```python
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()`:

```python
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](https://docs.fal.ai/model-apis/model-endpoints/queue). При работе через хаб действуют следующие правила и ограничения:

* **Доступные модели.** Поддерживаются только два 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`, умноженной на ставку выбранного разрешения на странице [«Тарифы»](https://hub.coreinfra.ai/pricing) (подробнее — в разделе [«Стоимость видео»](https://coreinfra.ru/docs/video-billing.md)).
* **Изоляция заданий и чтение результата.** Для проверки статуса, чтения результата или отмены используйте ключ хаба, с помощью которого было создано задание (другой ключ получит ошибку со статус-кодом `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}`                             | [Постановка задания в очередь](https://coreinfra.ru/docs/reference/fal/submit.md)   |
| `GET`  | `/{owner}/{app}/requests/{requestId}/status`        | [Статус задания в очереди](https://coreinfra.ru/docs/reference/fal/status.md)       |
| `GET`  | `/{owner}/{app}/requests/{requestId}`               | [Получение результата генерации](https://coreinfra.ru/docs/reference/fal/result.md) |
| `PUT`  | `/{owner}/{app}/requests/{requestId}/cancel`        | [Отмена задания](https://coreinfra.ru/docs/reference/fal/cancel.md)                 |
| `GET`  | `/{owner}/{app}/requests/{requestId}/content?t=...` | [Скачивание готового видео](https://coreinfra.ru/docs/reference/fal/content.md)     |

Операции статуса, результата и отмены также принимают полный путь с `{path}`: `/{owner}/{app}/{path}/requests/{requestId}[/status|/cancel]`. Описание моделей и параметров приведено в карточках [FLUX 3 Max Text to Video](https://coreinfra.ru/docs/catalog/blackforestlabs-flux-3-max-text-to-video.md) и [FLUX 3 Max Image to Video](https://coreinfra.ru/docs/catalog/blackforestlabs-flux-3-max-image-to-video.md) в [каталоге моделей](https://coreinfra.ru/docs/catalog.md), цены — на странице [«Тарифы»](https://hub.coreinfra.ai/pricing).

## Ошибки

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

Формат и примеры ошибок очереди и валидации параметров (`422`) приведены в [справочнике fal API](https://coreinfra.ru/docs/reference/fal.md#errors). Общие ошибки авторизации, баланса и лимитов расходов описаны в [общем справочнике API](https://coreinfra.ru/docs/reference.md#errors) и на странице [«Лимиты и ограничения»](https://coreinfra.ru/docs/limits.md).
