Submit a request to an endpoint path

POST

{owner}

{app}

{path}

curl --request POST \
  --url https://queue.fal.run/{owner}/{app}/{path} \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "prompt": "a red fox in the snow"
}
'

import requests

url = "https://queue.fal.run/{owner}/{app}/{path}"

payload = { "prompt": "a red fox in the snow" }
headers = {
    "Authorization": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({prompt: 'a red fox in the snow'})
};

fetch('https://queue.fal.run/{owner}/{app}/{path}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "status": "IN_QUEUE",
  "request_id": "019a1b2c-3d4e-7f80-9a1b-2c3d4e5f6a7b",
  "response_url": "https://queue.fal.run/blackforestlabs/flux-3-max/requests/019a1b2c-3d4e-7f80-9a1b-2c3d4e5f6a7b",
  "status_url": "https://queue.fal.run/blackforestlabs/flux-3-max/requests/019a1b2c-3d4e-7f80-9a1b-2c3d4e5f6a7b/status",
  "cancel_url": "https://queue.fal.run/blackforestlabs/flux-3-max/requests/019a1b2c-3d4e-7f80-9a1b-2c3d4e5f6a7b/cancel",
  "queue_position": 0,
  "logs": null,
  "metrics": {}
}

{
  "detail": "<string>",
  "type": "<string>"
}

{
  "detail": "<string>",
  "type": "<string>"
}

{
  "detail": "<string>",
  "type": "<string>"
}

{
  "detail": "<string>",
  "type": "<string>"
}

{
  "error": "<string>",
  "request_id": null
}

{
  "detail": "<string>",
  "type": "<string>"
}

Authorizations

Authorization

string

header

required

Send your fal API key in the Authorization header with the Key prefix, for example Authorization: Key $FAL_KEY. Public models also accept requests without a key. See Authentication.

Headers

X-Fal-Request-Start-Timeout

number

The maximum time in seconds for the request to start on a runner. The time starts when fal receives the request and includes queue time and retries. The value must be greater than 0.1. If the request does not start in this time, the API returns 504 with X-Fal-Request-Timeout-Type: user. This header does not limit the run time on the runner. There is no default.

X-Fal-Request-Timeout

number

Deprecated. Use X-Fal-Request-Start-Timeout. If you send both headers, the API uses X-Fal-Request-Start-Timeout.

X-Fal-Queue-Priority

enum<string>

The queue priority for this request. The default is normal. Use low for background work. This header can only lower the priority of your account. It cannot raise it. The API ignores values that it does not recognize.

Available options:

normal,

low

X-Fal-Runner-Hint

string

A routing hint. fal tries to send requests with the same hint to the same runner. Use it when a runner keeps state in memory, for example a loaded LoRA.

X-Fal-No-Retry

enum<string>

Set to 1, true, or yes to turn off automatic retries for this queue request. See Reliability.

Available options:

1,

true,

yes

X-Fal-Retry-Config

string

A JSON object that sets the number of retries for each retry condition. The keys are timeout, connection_error, and server_error. Each value is {"retries": N}, where N is from 0 to 10. The API uses this header only when you own the app.

X-Fal-Store-IO

string

Controls if fal stores the request and response payloads. Set to 0 to turn off storage. Set to 1 to store the payloads for the default period. If you do not send this header, fal uses your account setting.

X-Fal-Object-Lifecycle-Preference

string

A JSON object that sets the expiration and access rules for the files that the model creates. See Platform Headers.

x-app-fal-disable-fallback

enum<string>

Set to true to ask the model app not to send the request to a fallback model. fal forwards this header to the app.

Available options:

true

Path Parameters

owner

string

required

The owner of the model, for example blackforestlabs.

app

string

required

The model app name, for example flux-3-max.

path

string

required

The endpoint path inside the app. 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. The path can contain more than one segment.

Query Parameters

fal_webhook

string<uri>

An http or https URL. fal sends a POST request to this URL when the request completes. See Webhooks.

fal_max_queue_length

integer

The maximum number of queued requests. If the queue for this endpoint already has this number of requests, the API rejects the request with 429.

Body

application/json

The model input. Each model has its own input schema. See the model page in the Model API Reference.

Response

The request is in the queue.

The state of a queue request.

status

enum<string>

required

COMPLETED is the final state. A failed or cancelled request also has the status COMPLETED.

Available options:

IN_QUEUE,

IN_PROGRESS,

COMPLETED

request_id

string

required

response_url

string<uri> | null

The URL of the result.

status_url

string<uri> | null

cancel_url

string<uri> | null

queue_position

integer

The number of requests in front of this request. Present only when the status is IN_QUEUE.

logs

object[] | null

The runner logs. The value is null unless you send logs=1.

Hide child attributes

logs.message

string

required

logs.timestamp

string<date-time>

required

logs.labels

object

metrics

object

Present when the status is COMPLETED. Empty in other states.

Hide child attributes

metrics.inference_time

number

The run time on the runner, in seconds.

error

string

The error message. Present only when the request failed.

error_type

string

The error category. Present only when the request failed. See Request Error Types.

⌘I

Submit a request to an endpoint path

curl --request POST \
  --url https://queue.fal.run/{owner}/{app}/{path} \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "prompt": "a red fox in the snow"
}
'

import requests

url = "https://queue.fal.run/{owner}/{app}/{path}"

payload = { "prompt": "a red fox in the snow" }
headers = {
    "Authorization": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({prompt: 'a red fox in the snow'})
};

fetch('https://queue.fal.run/{owner}/{app}/{path}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "status": "IN_QUEUE",
  "request_id": "019a1b2c-3d4e-7f80-9a1b-2c3d4e5f6a7b",
  "response_url": "https://queue.fal.run/blackforestlabs/flux-3-max/requests/019a1b2c-3d4e-7f80-9a1b-2c3d4e5f6a7b",
  "status_url": "https://queue.fal.run/blackforestlabs/flux-3-max/requests/019a1b2c-3d4e-7f80-9a1b-2c3d4e5f6a7b/status",
  "cancel_url": "https://queue.fal.run/blackforestlabs/flux-3-max/requests/019a1b2c-3d4e-7f80-9a1b-2c3d4e5f6a7b/cancel",
  "queue_position": 0,
  "logs": null,
  "metrics": {}
}

{
  "detail": "<string>",
  "type": "<string>"
}

{
  "detail": "<string>",
  "type": "<string>"
}

{
  "detail": "<string>",
  "type": "<string>"
}

{
  "detail": "<string>",
  "type": "<string>"
}

{
  "error": "<string>",
  "request_id": null
}

{
  "detail": "<string>",
  "type": "<string>"
}

Queue API

Synchronous API

Submit a request to an endpoint path

Authorizations

Headers

Path Parameters

Query Parameters

Body

Response