# fal API

API методы очереди генерации видео FLUX 3 Max, авторизация и форматы ответов fal-совместимого API хаба.

fal-совместимый API хаба обслуживает асинхронную очередь генерации видео для двух моделей **FLUX 3 Max**: `blackforestlabs/flux-3-max/text-to-video` и `blackforestlabs/flux-3-max/image-to-video`. Общее устройство очереди описано в [документации fal Queue API](https://docs.fal.ai/model-apis/model-endpoints/queue), а настройка Python SDK `fal-client` — на странице [«fal-совместимый API»](https://coreinfra.ru/docs/use/fal.md).

Базовый адрес очереди: `https://hub.coreinfra.ai/fal/api`.

## API методы

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

| Методы            | Путь                                                | Назначение                                                                        |
| ----------------- | --------------------------------------------------- | --------------------------------------------------------------------------------- |
| `POST`, `OPTIONS` | `/{owner}/{app}/{path}`                             | [Постановка задания в очередь](https://coreinfra.ru/docs/reference/fal/submit.md) |
| `GET`, `OPTIONS`  | `/{owner}/{app}/requests/{requestId}/status`        | [Статус задания](https://coreinfra.ru/docs/reference/fal/status.md)               |
| `GET`, `OPTIONS`  | `/{owner}/{app}/requests/{requestId}`               | [Результат генерации](https://coreinfra.ru/docs/reference/fal/result.md)          |
| `PUT`, `OPTIONS`  | `/{owner}/{app}/requests/{requestId}/cancel`        | [Отмена задания](https://coreinfra.ru/docs/reference/fal/cancel.md)               |
| `GET`, `OPTIONS`  | `/{owner}/{app}/requests/{requestId}/content?t=...` | [Скачивание видео](https://coreinfra.ru/docs/reference/fal/content.md)            |

API методы статуса, результата и отмены также принимают полный путь с `{path}`: `/{owner}/{app}/{path}/requests/{requestId}[/status|/cancel]`. Запросы `GET`, `POST` и `PUT` к `/fal/run/*` (синхронный хост `FAL_RUN_HOST`) возвращают ошибку со статус-кодом `400`.

## Общие правила

Для постановки в очередь, проверки статуса, чтения результата и отмены передавайте ключ хаба в заголовке `Authorization: Key sk-ci2-...` (используется в `fal-client` по умолчанию) или `Authorization: Bearer sk-ci2-...`. Доступ к заданию есть только у ключа, который его создал. Для [скачивания видео](https://coreinfra.ru/docs/reference/fal/content.md) заголовок `Authorization` не требуется — доступ подтверждается параметром `t` в подписанной ссылке.

Все ответы очереди (кроме потока байтов MP4 при скачивании видео) возвращаются в формате JSON. Потоковый SSE-режим (`status/stream`, `stream()`) не поддерживается.

## Ошибки

Пример ошибки обращения к очереди с полем `detail`:

```json
{"detail":"Endpoint 'fal-ai/fast-sdxl' is not available on this hub."}
```

Ошибки проверки входных параметров (`422 Unprocessable Entity`) содержат массив элементов валидации в `detail`:

```json
{
  "detail": [
    {
      "loc": ["body", "duration"],
      "msg": "duration must be a whole number of seconds from 5 to 20.",
      "type": "invalid_duration"
    }
  ]
}
```

Для неизвестного или чужого `requestId` API методы статуса и отмены возвращают статус-код `404` с полем `status: "NOT_FOUND"`, а чтение результата — `404` с полем `detail`. Недействительный ключ возвращает статус-код `401`; общие ошибки авторизации, баланса и лимитов расходов описаны в [общем справочнике](https://coreinfra.ru/docs/reference.md#errors) и на странице [«Лимиты и ограничения»](https://coreinfra.ru/docs/limits.md).
