{
  "openapi": "3.1.0",
  "info": {
    "title": "Queue API",
    "version": "v1",
    "description": "Submit a model request to the fal queue, then read its status and result. The queue retries requests that fail because of a temporary runner error."
  },
  "servers": [
    {
      "url": "https://queue.fal.run",
      "description": "Queue API. The backup host is https://queue.falrun.com."
    }
  ],
  "security": [
    {
      "apiKey": []
    }
  ],
  "tags": [
    {
      "name": "Queue"
    }
  ],
  "paths": {
    "/{owner}/{app}": {
      "post": {
        "tags": [
          "Queue"
        ],
        "operationId": "submitQueueRequest",
        "summary": "Submit a request",
        "description": "Add a model request to the queue. The response contains the request ID and the URLs for status, result, and cancellation. The queue keeps the request until a runner is available. The queue has no size limit unless you send `fal_max_queue_length`.",
        "parameters": [
          {
            "$ref": "#/components/parameters/Owner"
          },
          {
            "$ref": "#/components/parameters/App"
          },
          {
            "$ref": "#/components/parameters/FalWebhook"
          },
          {
            "$ref": "#/components/parameters/FalMaxQueueLength"
          },
          {
            "$ref": "#/components/parameters/StartTimeout"
          },
          {
            "$ref": "#/components/parameters/LegacyTimeout"
          },
          {
            "$ref": "#/components/parameters/QueuePriority"
          },
          {
            "$ref": "#/components/parameters/RunnerHint"
          },
          {
            "$ref": "#/components/parameters/NoRetry"
          },
          {
            "$ref": "#/components/parameters/RetryConfig"
          },
          {
            "$ref": "#/components/parameters/StoreIO"
          },
          {
            "$ref": "#/components/parameters/ObjectLifecycle"
          },
          {
            "$ref": "#/components/parameters/DisableFallback"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ModelInput"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The request is in the queue.",
            "headers": {
              "x-fal-request-id": {
                "$ref": "#/components/headers/RequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SubmitResponse"
                }
              }
            }
          },
          "400": {
            "description": "A header or query parameter is not valid.",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/DetailError"
                    },
                    {
                      "$ref": "#/components/schemas/QueueSubmitError"
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/BadCredentials"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/AppNotFound"
          },
          "413": {
            "$ref": "#/components/responses/PayloadTooLarge"
          },
          "429": {
            "description": "The queue has `fal_max_queue_length` requests or more.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/QueueSubmitError"
                }
              }
            }
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          }
        },
        "x-mint": {
          "href": "/api-reference/inference-api/queue/submit",
          "metadata": {
            "sidebarTitle": "Submit request"
          }
        }
      }
    },
    "/{owner}/{app}/{path}": {
      "post": {
        "tags": [
          "Queue"
        ],
        "operationId": "submitQueueRequestWithPath",
        "summary": "Submit a request to an endpoint path",
        "description": "Add a request for a model endpoint path to the queue. Use this operation when the model ID has more than two segments, for example `blackforestlabs/flux-3-max/text-to-video`. The response contains the request ID and the URLs for status, result, and cancellation. The queue keeps the request until a runner is available. The queue has no size limit unless you send `fal_max_queue_length`.",
        "parameters": [
          {
            "$ref": "#/components/parameters/Owner"
          },
          {
            "$ref": "#/components/parameters/App"
          },
          {
            "$ref": "#/components/parameters/EndpointPath"
          },
          {
            "$ref": "#/components/parameters/FalWebhook"
          },
          {
            "$ref": "#/components/parameters/FalMaxQueueLength"
          },
          {
            "$ref": "#/components/parameters/StartTimeout"
          },
          {
            "$ref": "#/components/parameters/LegacyTimeout"
          },
          {
            "$ref": "#/components/parameters/QueuePriority"
          },
          {
            "$ref": "#/components/parameters/RunnerHint"
          },
          {
            "$ref": "#/components/parameters/NoRetry"
          },
          {
            "$ref": "#/components/parameters/RetryConfig"
          },
          {
            "$ref": "#/components/parameters/StoreIO"
          },
          {
            "$ref": "#/components/parameters/ObjectLifecycle"
          },
          {
            "$ref": "#/components/parameters/DisableFallback"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ModelInput"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The request is in the queue.",
            "headers": {
              "x-fal-request-id": {
                "$ref": "#/components/headers/RequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SubmitResponse"
                }
              }
            }
          },
          "400": {
            "description": "A header or query parameter is not valid.",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/DetailError"
                    },
                    {
                      "$ref": "#/components/schemas/QueueSubmitError"
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/BadCredentials"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/AppNotFound"
          },
          "413": {
            "$ref": "#/components/responses/PayloadTooLarge"
          },
          "429": {
            "description": "The queue has `fal_max_queue_length` requests or more.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/QueueSubmitError"
                }
              }
            }
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          }
        },
        "x-mint": {
          "href": "/api-reference/inference-api/queue/submit-path",
          "metadata": {
            "sidebarTitle": "Submit to endpoint path"
          }
        }
      }
    },
    "/{owner}/{app}/requests/{request_id}/status": {
      "get": {
        "tags": [
          "Queue"
        ],
        "operationId": "getQueueRequestStatus",
        "summary": "Get request status",
        "description": "Get the state of a queue request. Poll this operation until `status` is `COMPLETED`, then get the result. To receive updates without polling, use the status stream.",
        "parameters": [
          {
            "$ref": "#/components/parameters/StatusOwner"
          },
          {
            "$ref": "#/components/parameters/StatusApp"
          },
          {
            "$ref": "#/components/parameters/RequestId"
          },
          {
            "$ref": "#/components/parameters/Logs"
          }
        ],
        "responses": {
          "200": {
            "description": "The request is complete.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/QueueStatus"
                }
              }
            }
          },
          "202": {
            "description": "The request is in the queue or in progress.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/QueueStatus"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/BadCredentials"
          },
          "404": {
            "description": "The request does not exist, or it belongs to a different account. The API returns the same response in both cases.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NotFoundStatus"
                }
              }
            }
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          }
        },
        "x-mint": {
          "href": "/api-reference/inference-api/queue/status",
          "metadata": {
            "sidebarTitle": "Get request status"
          }
        }
      }
    },
    "/{owner}/{app}/requests/{request_id}/status/stream": {
      "get": {
        "tags": [
          "Queue"
        ],
        "operationId": "streamQueueRequestStatus",
        "summary": "Stream request status",
        "description": "Receive status updates as server-sent events. Each event has a `data:` line with a status object. The status object has the same fields as the response of Get request status. The server closes the stream after it sends the `COMPLETED` event. The server sends a comment line every 15 seconds to keep the connection open.",
        "parameters": [
          {
            "$ref": "#/components/parameters/StatusOwner"
          },
          {
            "$ref": "#/components/parameters/StatusApp"
          },
          {
            "$ref": "#/components/parameters/RequestId"
          },
          {
            "$ref": "#/components/parameters/Logs"
          }
        ],
        "responses": {
          "200": {
            "description": "A stream of status events.",
            "content": {
              "text/event-stream": {
                "schema": {
                  "type": "string"
                },
                "example": "data: {\"status\":\"IN_PROGRESS\",\"request_id\":\"019a1b2c-...\",\"logs\":null,\"metrics\":{}}\n\ndata: {\"status\":\"COMPLETED\",\"request_id\":\"019a1b2c-...\",\"logs\":null,\"metrics\":{\"inference_time\":1.82}}\n\n"
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/BadCredentials"
          },
          "404": {
            "description": "The request does not exist, or it belongs to a different account. The API returns the same response in both cases.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NotFoundStatus"
                }
              }
            }
          }
        },
        "x-mint": {
          "href": "/api-reference/inference-api/queue/status-stream",
          "metadata": {
            "sidebarTitle": "Stream request status"
          }
        }
      }
    },
    "/{owner}/{app}/requests/{request_id}": {
      "get": {
        "tags": [
          "Queue"
        ],
        "operationId": "getQueueRequestResult",
        "summary": "Get request result",
        "description": "Get the result of a completed request. The response has the status code, headers, and body that the model returned. If the model returned an error, this operation returns the same error.\n\nfal keeps the result for 1 hour after the request completes. If the result is 10 KB or larger, fal keeps it for 6 minutes. If payload storage is on, the result stays available for the storage period. See `X-Fal-Store-IO`.",
        "parameters": [
          {
            "$ref": "#/components/parameters/StatusOwner"
          },
          {
            "$ref": "#/components/parameters/StatusApp"
          },
          {
            "$ref": "#/components/parameters/RequestId"
          }
        ],
        "responses": {
          "200": {
            "description": "The model output.",
            "headers": {
              "x-fal-request-id": {
                "$ref": "#/components/headers/RequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ModelOutput"
                }
              }
            }
          },
          "400": {
            "description": "The request is not complete.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InProgressError"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/BadCredentials"
          },
          "404": {
            "description": "The request does not exist, the result expired, or the request belongs to a different account.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DetailError"
                }
              }
            }
          },
          "422": {
            "description": "The model rejected the input.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ModelValidationError"
                }
              }
            }
          },
          "499": {
            "description": "The request was cancelled.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DetailError"
                }
              }
            }
          },
          "500": {
            "description": "The model or the platform failed. The body is the error that the model or the platform returned.",
            "content": {
              "application/json": {
                "schema": {
                  "anyOf": [
                    {
                      "$ref": "#/components/schemas/RequestError"
                    },
                    {
                      "$ref": "#/components/schemas/DetailError"
                    }
                  ]
                }
              }
            }
          },
          "504": {
            "description": "The request did not start before the `X-Fal-Request-Start-Timeout` deadline.",
            "headers": {
              "X-Fal-Request-Timeout-Type": {
                "$ref": "#/components/headers/TimeoutType"
              },
              "X-Fal-Error-Type": {
                "$ref": "#/components/headers/ErrorType"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RequestError"
                }
              }
            }
          }
        },
        "x-mint": {
          "href": "/api-reference/inference-api/queue/result",
          "metadata": {
            "sidebarTitle": "Get request result"
          }
        }
      }
    },
    "/{owner}/{app}/requests/{request_id}/cancel": {
      "put": {
        "tags": [
          "Queue"
        ],
        "operationId": "cancelQueueRequest",
        "summary": "Cancel a request",
        "description": "Cancel a queue request. If the request is in the queue, fal removes it. If the request is in progress, fal sends a cancellation signal to the runner. The model app decides how to stop the work. See [Handle cancellations](/documentation/development/handle-cancellations).",
        "parameters": [
          {
            "$ref": "#/components/parameters/StatusOwner"
          },
          {
            "$ref": "#/components/parameters/StatusApp"
          },
          {
            "$ref": "#/components/parameters/RequestId"
          }
        ],
        "responses": {
          "200": {
            "description": "fal removed the request from the queue.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CancelResponse"
                },
                "example": {
                  "status": "OK"
                }
              }
            }
          },
          "202": {
            "description": "The request is in progress. fal sent a cancellation signal to the runner.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CancelResponse"
                },
                "example": {
                  "status": "CANCELLATION_REQUESTED"
                }
              }
            }
          },
          "400": {
            "description": "The request is already complete.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CancelResponse"
                },
                "example": {
                  "status": "ALREADY_COMPLETED"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/BadCredentials"
          },
          "404": {
            "description": "The request does not exist, or it belongs to a different account. The API returns the same response in both cases.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NotFoundStatus"
                }
              }
            }
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          }
        },
        "x-mint": {
          "href": "/api-reference/inference-api/queue/cancel",
          "metadata": {
            "sidebarTitle": "Cancel request"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "apiKey": {
        "type": "apiKey",
        "in": "header",
        "name": "Authorization",
        "description": "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](/documentation/model-apis/authentication/key-based)."
      }
    },
    "parameters": {
      "Owner": {
        "name": "owner",
        "in": "path",
        "required": true,
        "description": "The owner of the model, for example `blackforestlabs`.",
        "schema": {
          "type": "string"
        },
        "example": "blackforestlabs"
      },
      "App": {
        "name": "app",
        "in": "path",
        "required": true,
        "description": "The model app name, for example `flux-3-max`.",
        "schema": {
          "type": "string"
        },
        "example": "flux-3-max"
      },
      "EndpointPath": {
        "name": "path",
        "in": "path",
        "required": true,
        "description": "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.",
        "schema": {
          "type": "string"
        },
        "example": "text-to-video"
      },
      "RequestId": {
        "name": "request_id",
        "in": "path",
        "required": true,
        "description": "The request ID that the submit response returned.",
        "schema": {
          "type": "string",
          "format": "uuid"
        }
      },
      "StatusOwner": {
        "name": "owner",
        "in": "path",
        "required": true,
        "description": "The owner of the model, for example `blackforestlabs`. Use the same value as in the submit request.",
        "schema": {
          "type": "string"
        },
        "example": "blackforestlabs"
      },
      "StatusApp": {
        "name": "app",
        "in": "path",
        "required": true,
        "description": "The model app name, for example `flux-3-max`. Do not add the endpoint path. The `status_url`, `response_url`, and `cancel_url` fields contain the correct URL.",
        "schema": {
          "type": "string"
        },
        "example": "flux-3-max"
      },
      "Logs": {
        "name": "logs",
        "in": "query",
        "required": false,
        "description": "Set to `1` to include runner logs in the response. Logs are not available for all models.",
        "schema": {
          "type": "string",
          "enum": [
            "1",
            "0"
          ]
        }
      },
      "FalWebhook": {
        "name": "fal_webhook",
        "in": "query",
        "required": false,
        "description": "An `http` or `https` URL. fal sends a `POST` request to this URL when the request completes. See [Webhooks](/documentation/model-apis/inference/webhooks).",
        "schema": {
          "type": "string",
          "format": "uri"
        },
        "example": "https://example.com/fal-webhook"
      },
      "FalMaxQueueLength": {
        "name": "fal_max_queue_length",
        "in": "query",
        "required": false,
        "description": "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`.",
        "schema": {
          "type": "integer"
        }
      },
      "StartTimeout": {
        "name": "X-Fal-Request-Start-Timeout",
        "in": "header",
        "required": false,
        "description": "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.",
        "schema": {
          "type": "number",
          "exclusiveMinimum": 0.1
        },
        "example": "30"
      },
      "LegacyTimeout": {
        "name": "X-Fal-Request-Timeout",
        "in": "header",
        "required": false,
        "description": "Deprecated. Use `X-Fal-Request-Start-Timeout`. If you send both headers, the API uses `X-Fal-Request-Start-Timeout`.",
        "schema": {
          "type": "number",
          "exclusiveMinimum": 0.1
        },
        "deprecated": true
      },
      "QueuePriority": {
        "name": "X-Fal-Queue-Priority",
        "in": "header",
        "required": false,
        "description": "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.",
        "schema": {
          "type": "string",
          "enum": [
            "normal",
            "low"
          ]
        }
      },
      "RunnerHint": {
        "name": "X-Fal-Runner-Hint",
        "in": "header",
        "required": false,
        "description": "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.",
        "schema": {
          "type": "string"
        },
        "example": "lora:my-style"
      },
      "NoRetry": {
        "name": "X-Fal-No-Retry",
        "in": "header",
        "required": false,
        "description": "Set to `1`, `true`, or `yes` to turn off automatic retries for this queue request. See [Reliability](/documentation/model-apis/inference/reliability).",
        "schema": {
          "type": "string",
          "enum": [
            "1",
            "true",
            "yes"
          ]
        }
      },
      "RetryConfig": {
        "name": "X-Fal-Retry-Config",
        "in": "header",
        "required": false,
        "description": "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.",
        "schema": {
          "type": "string"
        },
        "example": "{\"server_error\": {\"retries\": 2}}"
      },
      "StoreIO": {
        "name": "X-Fal-Store-IO",
        "in": "header",
        "required": false,
        "description": "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.",
        "schema": {
          "type": "string"
        },
        "example": "0"
      },
      "ObjectLifecycle": {
        "name": "X-Fal-Object-Lifecycle-Preference",
        "in": "header",
        "required": false,
        "description": "A JSON object that sets the expiration and access rules for the files that the model creates. See [Platform Headers](/documentation/model-apis/common-parameters).",
        "schema": {
          "type": "string"
        },
        "example": "{\"expiration_duration_seconds\": 86400}"
      },
      "DisableFallback": {
        "name": "x-app-fal-disable-fallback",
        "in": "header",
        "required": false,
        "description": "Set to `true` to ask the model app not to send the request to a fallback model. fal forwards this header to the app.",
        "schema": {
          "type": "string",
          "enum": [
            "true"
          ]
        }
      }
    },
    "headers": {
      "RequestId": {
        "description": "The request ID. Include it when you contact support.",
        "schema": {
          "type": "string"
        }
      },
      "ErrorType": {
        "description": "The same value as the `error_type` field. See [Request Error Types](/documentation/model-apis/request-errors).",
        "schema": {
          "type": "string",
          "enum": [
            "request_timeout",
            "startup_timeout",
            "runner_scheduling_failure",
            "runner_connection_timeout",
            "runner_disconnected",
            "runner_connection_refused",
            "runner_connection_error",
            "runner_incomplete_response",
            "runner_server_error",
            "client_disconnected",
            "client_cancelled",
            "bad_request",
            "internal_error"
          ]
        }
      },
      "TimeoutType": {
        "description": "`user` when the request did not start before the `X-Fal-Request-Start-Timeout` deadline.",
        "schema": {
          "type": "string",
          "enum": [
            "user"
          ]
        }
      }
    },
    "schemas": {
      "QueueStatus": {
        "type": "object",
        "description": "The state of a queue request.",
        "properties": {
          "status": {
            "type": "string",
            "enum": [
              "IN_QUEUE",
              "IN_PROGRESS",
              "COMPLETED"
            ],
            "description": "`COMPLETED` is the final state. A failed or cancelled request also has the status `COMPLETED`."
          },
          "request_id": {
            "type": "string"
          },
          "response_url": {
            "type": [
              "string",
              "null"
            ],
            "format": "uri",
            "description": "The URL of the result."
          },
          "status_url": {
            "type": [
              "string",
              "null"
            ],
            "format": "uri"
          },
          "cancel_url": {
            "type": [
              "string",
              "null"
            ],
            "format": "uri"
          },
          "queue_position": {
            "type": "integer",
            "description": "The number of requests in front of this request. Present only when the status is `IN_QUEUE`."
          },
          "logs": {
            "type": [
              "array",
              "null"
            ],
            "items": {
              "$ref": "#/components/schemas/LogEntry"
            },
            "description": "The runner logs. The value is `null` unless you send `logs=1`."
          },
          "metrics": {
            "type": "object",
            "properties": {
              "inference_time": {
                "type": "number",
                "description": "The run time on the runner, in seconds."
              }
            },
            "description": "Present when the status is `COMPLETED`. Empty in other states."
          },
          "error": {
            "type": "string",
            "description": "The error message. Present only when the request failed."
          },
          "error_type": {
            "type": "string",
            "description": "The error category. Present only when the request failed. See [Request Error Types](/documentation/model-apis/request-errors)."
          }
        },
        "required": [
          "status",
          "request_id"
        ]
      },
      "LogEntry": {
        "type": "object",
        "properties": {
          "message": {
            "type": "string"
          },
          "timestamp": {
            "type": "string",
            "format": "date-time"
          },
          "labels": {
            "type": "object",
            "additionalProperties": true
          }
        },
        "required": [
          "message",
          "timestamp"
        ]
      },
      "SubmitResponse": {
        "allOf": [
          {
            "$ref": "#/components/schemas/QueueStatus"
          }
        ],
        "example": {
          "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": {}
        }
      },
      "NotFoundStatus": {
        "type": "object",
        "properties": {
          "status": {
            "type": "string",
            "enum": [
              "NOT_FOUND"
            ]
          }
        },
        "required": [
          "status"
        ]
      },
      "CancelResponse": {
        "type": "object",
        "properties": {
          "status": {
            "type": "string",
            "enum": [
              "OK",
              "CANCELLATION_REQUESTED",
              "ALREADY_COMPLETED",
              "NOT_FOUND"
            ]
          }
        },
        "required": [
          "status"
        ]
      },
      "DetailError": {
        "type": "object",
        "description": "A general error.",
        "properties": {
          "detail": {
            "type": "string"
          },
          "type": {
            "type": "string",
            "description": "A machine-readable reason, for some errors. Examples are `rejected_key`, `permission_denied`, and `resource_restricted`."
          }
        },
        "required": [
          "detail"
        ]
      },
      "RequestError": {
        "type": "object",
        "description": "An error from the request pipeline. See [Request Error Types](/documentation/model-apis/request-errors).",
        "properties": {
          "detail": {
            "type": "string"
          },
          "error_type": {
            "type": "string",
            "enum": [
              "request_timeout",
              "startup_timeout",
              "runner_scheduling_failure",
              "runner_connection_timeout",
              "runner_disconnected",
              "runner_connection_refused",
              "runner_connection_error",
              "runner_incomplete_response",
              "runner_server_error",
              "client_disconnected",
              "client_cancelled",
              "bad_request",
              "internal_error"
            ]
          }
        },
        "required": [
          "detail",
          "error_type"
        ]
      },
      "QueueSubmitError": {
        "type": "object",
        "description": "A queue submit error for a query parameter.",
        "properties": {
          "request_id": {
            "type": "null"
          },
          "error": {
            "type": "string"
          }
        },
        "required": [
          "error"
        ]
      },
      "InProgressError": {
        "type": "object",
        "properties": {
          "detail": {
            "type": "string",
            "enum": [
              "Request is still in progress"
            ]
          },
          "request_id": {
            "type": "string"
          },
          "response_url": {
            "type": "string",
            "format": "uri"
          },
          "status_url": {
            "type": "string",
            "format": "uri"
          },
          "cancel_url": {
            "type": "string",
            "format": "uri"
          }
        },
        "required": [
          "detail"
        ]
      },
      "ModelValidationError": {
        "type": "object",
        "description": "An input validation error from the model. See [Model Errors](/documentation/model-apis/errors).",
        "properties": {
          "detail": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "loc": {
                  "type": "array",
                  "items": {
                    "type": [
                      "string",
                      "integer"
                    ]
                  }
                },
                "msg": {
                  "type": "string"
                },
                "type": {
                  "type": "string"
                },
                "url": {
                  "type": "string"
                },
                "ctx": {
                  "type": "object"
                },
                "input": {}
              },
              "required": [
                "loc",
                "msg",
                "type"
              ]
            }
          }
        },
        "required": [
          "detail"
        ]
      },
      "ModelInput": {
        "type": "object",
        "description": "The model input. Each model has its own input schema. See the model page in the [Model API Reference](/model-api-reference).",
        "additionalProperties": true,
        "example": {
          "prompt": "a red fox in the snow"
        }
      },
      "ModelOutput": {
        "type": "object",
        "description": "The model output. Each model has its own output schema.",
        "additionalProperties": true
      },
      "WebhookPayload": {
        "type": "object",
        "properties": {
          "request_id": {
            "type": "string"
          },
          "gateway_request_id": {
            "type": "string",
            "description": "The ID of the last attempt. It is different from `request_id` when fal retried the request."
          },
          "status": {
            "type": "string",
            "enum": [
              "OK",
              "ERROR"
            ]
          },
          "payload": {
            "type": [
              "object",
              "null"
            ],
            "description": "The model output, or the error body when `status` is `ERROR`."
          },
          "error": {
            "type": "string",
            "description": "Present when `status` is `ERROR`."
          },
          "payload_error": {
            "type": "string",
            "description": "Present when fal could not include the output in the webhook. `payload` is then `null`."
          }
        },
        "required": [
          "request_id",
          "status"
        ]
      }
    },
    "responses": {
      "BadCredentials": {
        "description": "The credentials are not valid, or the app requires authentication.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/DetailError"
            }
          }
        }
      },
      "Forbidden": {
        "description": "The key cannot use this model. Reasons include missing permissions, a model restriction on the key, a locked account, or a spending limit.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/DetailError"
            }
          }
        }
      },
      "AppNotFound": {
        "description": "The model does not exist.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/DetailError"
            }
          }
        }
      },
      "PayloadTooLarge": {
        "description": "The request body is larger than 64 MiB."
      },
      "InternalError": {
        "description": "An internal error occurred. Retry the request.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/DetailError"
            }
          }
        }
      }
    }
  },
  "webhooks": {
    "queueRequestCompleted": {
      "post": {
        "tags": [
          "Queue"
        ],
        "operationId": "queueRequestCompleted",
        "summary": "Request completed webhook",
        "description": "fal sends this request to the `fal_webhook` URL when a queue request completes. Your endpoint must return a `2xx` status code. Verify the signature headers before you use the payload. See [Webhooks](/documentation/model-apis/inference/webhooks).",
        "parameters": [
          {
            "name": "X-Fal-Webhook-Request-Id",
            "in": "header",
            "required": false,
            "description": "The request ID.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "X-Fal-Webhook-User-Id",
            "in": "header",
            "required": false,
            "description": "The ID of the account that sent the request.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "X-Fal-Webhook-Timestamp",
            "in": "header",
            "required": false,
            "description": "The time of the delivery, in Unix epoch seconds.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "X-Fal-Webhook-Signature",
            "in": "header",
            "required": false,
            "description": "The ED25519 signature, in hexadecimal.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/WebhookPayload"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Your endpoint received the webhook."
          }
        },
        "security": [],
        "x-mint": {
          "href": "/api-reference/inference-api/queue/webhook",
          "metadata": {
            "sidebarTitle": "Completion webhook"
          }
        }
      }
    }
  }
}