Run a model

POST

{owner}

{app}

Run a model

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

import requests

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

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://fal.run/{owner}/{app}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{}

{
  "detail": "<string>",
  "error_type": "request_timeout"
}

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

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

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

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>",
      "url": "<string>",
      "ctx": {},
      "input": "<unknown>"
    }
  ]
}

{
  "detail": "Reached concurrent requests limit of 2",
  "type": "concurrent_requests_limit",
  "data": {
    "limit": 123,
    "notify": true
  }
}

{
  "detail": "<string>",
  "error_type": "request_timeout"
}

{
  "detail": "<string>",
  "error_type": "request_timeout"
}

{
  "detail": "<string>",
  "error_type": "request_timeout"
}

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

Body

application/json

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

Response

The model output.

The model output. Each model has its own output schema.

⌘I

Run a model

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

import requests

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

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://fal.run/{owner}/{app}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{}

{
  "detail": "<string>",
  "error_type": "request_timeout"
}

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

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

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

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>",
      "url": "<string>",
      "ctx": {},
      "input": "<unknown>"
    }
  ]
}

{
  "detail": "Reached concurrent requests limit of 2",
  "type": "concurrent_requests_limit",
  "data": {
    "limit": 123,
    "notify": true
  }
}

{
  "detail": "<string>",
  "error_type": "request_timeout"
}

{
  "detail": "<string>",
  "error_type": "request_timeout"
}

{
  "detail": "<string>",
  "error_type": "request_timeout"
}

Queue API

Synchronous API

Run a model

Authorizations

Headers

Path Parameters

Body

Response