Skip to main content
Synchronous endpoints are beneficial if when you know the request is quick and you are looking for minimal latency. The drawbacks are:
  • You need to keep the connection open until receiving the result
  • The request cannot be interrupted
  • If the connection is interrupted there is not way to obtain the result
  • You will be charged for the full request whether or not you were able to receive the result
The endpoint format and parameters are similar to the Queue ones:
EndpointMethodDescription
https://fal.run/{model_id}POSTAdds a request to the queue for a top-level path
https://fal.run/{model_id}/{subpath}POSTAdds a request to the queue for an optional subpath
Parameters:
  • model_id: the model ID consists of a namespace and model name separated by a slash, e.g. fal-ai/fast-sdxl. Many models expose only a single top-level endpoint, so you can directly call them by model_id.
  • subpath: some models expose different capabilities at different sub-paths, e.g. fal-ai/flux/dev. The subpath (/dev in this case) should be used

​
Submit a request

Here is an example of using the curl command to submit a synchronous request: 
curl -X POST https://fal.run/fal-ai/fast-sdxl \
  -H "Authorization: Key $FAL_KEY" \
  -d '{"prompt": "a cat"}'
The response will come directly from the model: 
{
  "images": [
    {
      "url": "https://v3.fal.media/files/rabbit/YYbm6L3DaXYHDL1_A4OaL.jpeg",
      "width": 1024,
      "height": 1024,
      "content_type": "image/jpeg"
    }
  ],
  "timings": {
    "inference": 2.507048434985336
  },
  "seed": 15860307465884635512,
  "has_nsfw_concepts": [
    false
  ],
  "prompt": "a cat"
}

​
Object Lifecycle

You can control how long images and other objects generated by your request remain available by including the X-Fal-Object-Lifecycle-Preference header. This header allows you to specify the expiration duration for objects created during the request processing. The header value must be a JSON object with an expiration_duration_seconds field specifying the number of seconds the objects should remain available: 
curl -X POST https://fal.run/fal-ai/fast-sdxl \
  -H "Authorization: Key $FAL_KEY" \
  -H 'X-Fal-Object-Lifecycle-Preference: {"expiration_duration_seconds": 3600}' \
  -d '{"prompt": "a cat"}'
In this example, images generated by the request will be available for 3600 seconds (1 hour) before expiring. The expiration duration is calculated from when the objects are created.
Object LifecycleThe X-Fal-Object-Lifecycle-Preference header applies to all objects (images, files, etc.) generated during request processing. If you need different expiration times for different requests, you can include this header with each request.

​
Start Timeout

You can set a maximum time for how long your request can wait before it starts processing using the X-Fal-Request-Timeout header. This is useful for fail-fast scenarios where you don’t want to wait indefinitely for a runner. 
curl -X POST https://fal.run/fal-ai/fast-sdxl \
  -H "Authorization: Key $FAL_KEY" \
  -H "X-Fal-Request-Timeout: 30" \
  -d '{"prompt": "a cat"}'
Start Timeout Behavior
  • The timeout value is in seconds and must be at least 1 second
  • The timeout applies while waiting for a runner to become available
  • Once processing starts, the timeout is no longer enforced
  • On timeout, the response is a 504 Gateway Timeout with header X-Fal-Request-Timeout-Type: user