# POST /{owner}/{app}/{path} — создание видеозадания

Постановка задания генерации видео FLUX 3 Max в очередь /fal/api, параметры и валидация.

`POST /fal/api/blackforestlabs/flux-3-max/text-to-video` и `POST /fal/api/blackforestlabs/flux-3-max/image-to-video` ставят задание генерации видео в очередь для моделей [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). Общий протокол очереди описан в [документации fal Queue API](https://docs.fal.ai/model-apis/model-endpoints/queue), схема модели — в [описании FLUX 3 Max API](https://fal.ai/models/blackforestlabs/flux-3-max/text-to-video/api).

```bash
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"}'
```

Фрагмент ответа (`200 OK`):

```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"
}
```

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

Модель выбирается путем запроса после `/fal/api/`. Поддерживаются только `blackforestlabs/flux-3-max/text-to-video` и `blackforestlabs/flux-3-max/image-to-video`; любой другой путь возвращает ошибку со статус-кодом `404`. Стандартные поля модели (`prompt`, `aspect_ratio`, `reasoning_level`, `generate_audio`, `seed`) работают как описано в [документации FLUX 3 Max](https://fal.ai/models/blackforestlabs/flux-3-max/text-to-video/api).

* В `image-to-video` поля `image_url` и `end_image_url` принимают только данные в кодировке base64 (`data:image/...;base64,...`), например через `fal_client.encode_file()` или `fal_client.encode_image()`. Ссылки на внешние ресурсы (`http(s)`) отклоняются со статус-кодом `422`.
* До резервирования средств хаб проверяет параметры тарификации: `duration` должен быть целым числом секунд от `5` до `20` (по умолчанию `5`), а `resolution` — одним из значений `"720p"`, `"1080p"`, `"2K"` или `"4K"` (по умолчанию `"720p"`). Значения другого типа, `null` или вне допустимого списка отклоняются со статус-кодом `422`.
* Параметры вебхуков (`fal_webhook`) и заголовки `X-Fal-*` игнорируются. Синхронные вызовы `/fal/run/*` отклоняются со статус-кодом `400`.
* Максимальный размер тела запроса на `/fal/api` — **64 МиБ** (при превышении возвращается статус-код `413`).

### Резерв и списание

При постановке в очередь резервируется стоимость запрошенной длительности `duration` по ставке выбранного `resolution` на странице [«Тарифы»](https://hub.coreinfra.ai/pricing). Окончательное списание происходит при [чтении готового результата](https://coreinfra.ru/docs/reference/fal/result.md); прекращение опроса или отказ от чтения результата не отменяют запущенное задание и оплату выполненной генерации. При ошибке генерации или отмене в очереди до запуска резерв освобождается без списания (см. [«Стоимость видео»](https://coreinfra.ru/docs/video-billing.md)).

## Ошибки

| Статус-код | Условие                                                                                                                                                      |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `400`      | Вызов синхронного пути `/fal/run/*` (поддерживается только очередь `/fal/api/*`)                                                                             |
| `401`      | Недействителен ключ хаба                                                                                                                                     |
| `404`      | Неподдерживаемый путь модели                                                                                                                                 |
| `413`      | Тело запроса превышает допустимый размер (64 МиБ)                                                                                                            |
| `422`      | Некорректный JSON-объект, `duration` вне диапазона `5..20`, неподдерживаемое `resolution` или ссылка на внешний ресурс вместо изображения в кодировке base64 |

Формат ошибок описан в [разделе fal API](https://coreinfra.ru/docs/reference/fal.md#errors); общие ошибки авторизации, баланса и лимитов расходов — в [общем справочнике](https://coreinfra.ru/docs/reference.md#errors).
