Inference API

The Inference API is the HTTP interface that the fal SDKs use. Use it from any language or HTTP client. This page gives the rules that apply to all operations. The operation pages give the request and response schemas.

Choose an API

API	Host	Use it when
Queue API	`https://queue.fal.run`	The request can take more than a few seconds, or you need retries, status, cancellation, or webhooks.
Synchronous API	`https://fal.run`	The request is short and you want the result in the same HTTP connection.

Use the queue for production traffic. The queue keeps the request until a runner is available, and it retries the request after a temporary runner error. The synchronous API does not retry, and it returns an error when it cannot get a runner.

Authentication

Send your API key in the Authorization header with the Key prefix:

curl -X POST https://queue.fal.run/blackforestlabs/flux-3-max/text-to-video \
  -H "Authorization: Key $FAL_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "a red fox in the snow"}'

The key must have the permission for the operation:

Operation	Permission
Submit a queue request, or run a model	`models:requests:submit`
Get the status or result of a request	`models:requests:read`
Cancel a request	`models:requests:cancel`

The API preset has all three permissions. See Key-based authentication.

Model IDs and paths

A model ID has an owner, an app, and an optional endpoint path. For the model ID blackforestlabs/flux-3-max/text-to-video, the owner is blackforestlabs, the app is flux-3-max, and the path is text-to-video. Put the full model ID in the submit or run URL. The status, result, and cancel URLs use only the owner and the app. Do not build these URLs yourself. Use the status_url, response_url, and cancel_url fields from the submit response.

Queue request lifecycle

Submit the request

Submit a request. The response has the status IN_QUEUE and a request_id.

Wait for completion

Get the status until status is COMPLETED. The API returns 202 while the request is in the queue or in progress, and 200 when it is complete. To receive updates without polling, stream the status or send a webhook URL with the submit request.

Get the result

Get the result. If the request failed, this operation returns the error.

A failed or cancelled request also has the status COMPLETED. Get the result to find out if the request succeeded.

Retries

The queue retries a request when the runner fails with a temporary error. Temporary errors are connection errors, 503, and 504. The queue makes up to 10 attempts. When your account has the maximum number of concurrent requests, the queue waits for capacity and does not count an attempt. Send X-Fal-No-Retry: 1 to turn off retries for one request. The synchronous API does not retry. When an error is temporary, the response has the header X-Fal-Needs-Retry: 1. Your client can retry these errors. See Reliability.

Timeouts

The X-Fal-Request-Start-Timeout header sets the maximum time in seconds for the request to start on a runner. The time includes queue time and retries. If the request does not start in this time, the API returns 504 with the header X-Fal-Request-Timeout-Type: user and the error type startup_timeout. This header does not limit the run time on the runner. The model app sets the maximum run time. If the runner does not respond in that time, the API returns 504 with the error type request_timeout.

Result retention

The queue keeps the result for 1 hour after the request completes. If the result is 10 KB or larger, the queue keeps it for 6 minutes. If payload storage is on, the result stays available for the storage period. Payload storage is on by default. Use the X-Fal-Store-IO header to change it for one request. After the result expires, the result operation returns 404. Get the result before it expires, or use a webhook.

Errors

The error body has one of these shapes:

Shape	Returned for
`{"detail": "...", "error_type": "..."}`	Errors from the request pipeline, for example timeouts and runner errors. The `X-Fal-Error-Type` header has the same value as `error_type`. See Request Error Types.
`{"detail": [{"loc": [...], "msg": "...", "type": "..."}]}`	Input errors from the model, with status `422`. See Model Errors.
`{"detail": "...", "type": "concurrent_requests_limit", "data": {...}}`	The synchronous API, with status `429`, when your account has the maximum number of concurrent requests. See Concurrency limit errors.
`{"detail": "..."}`	Authentication, permission, and lookup errors.
`{"status": "NOT_FOUND"}`	Queue status and cancel operations for a request that does not exist.

The queue API returns 404 for a request that belongs to a different account. It does not return 403, so that the response does not show that the request exists.

Response headers

Header	Description
`x-fal-request-id`	The request ID. Include it when you contact support.
`X-Fal-Error-Type`	The error category of a failed request.
`X-Fal-Request-Timeout-Type`	`user` when the `X-Fal-Request-Start-Timeout` deadline passed.
`X-Fal-Needs-Retry`	`1` when a retry can succeed. `0` when a retry cannot succeed.
`X-Fal-Served-From`	The ID of the runner that processed the request.
`X-Fal-Billable-Units`	The billable units of the request, when the model reports them.

For the request headers, see Platform Headers.

Backup hosts

Each host has a backup host. The backup host accepts the same API key, path, query parameters, and body.

Host	Backup host
`queue.fal.run`	`queue.falrun.com`
`fal.run`	`falrun.com`

When you use a backup host, replace the host in the status_url, response_url, and cancel_url values. See Reliability.

Operations

Submit request

Add a model request to the queue.

Get request status

Get the state of a queue request.

Stream request status

Receive status updates as server-sent events.

Get request result

Get the output of a completed request.

Cancel request

Remove a request from the queue or stop it.

Run model

Run a model and wait for the result.

​Choose an API

​Authentication

​Model IDs and paths

​Queue request lifecycle

​Retries

​Timeouts

​Result retention

​Errors

​Response headers

​Backup hosts

​Operations