{"openapi":"3.0.0","info":{"description":"Fal.ai inference platform - run 1,000+ hosted models via fal.run (synchronous) and queue.fal.run (queue submit/status/result/cancel) with model ids in the URL path, plus platform APIs for model metadata, pricing, usage, analytics and compute instances. Authorization Key auth.","version":[{"name":"v1","value":"v1"}]},"servers":[{"description":"Fal.ai inference platform - run 1,000+ hosted models via fal.run (synchronous) and queue.fal.run (queue submit/status/result/cancel) with model ids in the URL path, plus platform APIs for model metadata, pricing, usage, analytics and compute instances. Authorization Key auth.","url":"https://api.apirails.com/falai"}],"paths":{"/v1/models":{"get":{"tags":["Models"],"parameters":[{"name":"limit","in":"query","description":"Maximum number of models to return","schema":{"type":"number","example":""}},{"name":"offset","in":"query","description":"Number of models to skip","schema":{"type":"number","example":""}},{"name":"search","in":"query","description":"Search query to filter models","schema":{"type":"string","example":""}}],"responses":{"401":{"description":"Bearer token required (Authorization header)","content":{"application/json":{}}}},"externalDocs":{"api_ref":"https://docs.fal.ai/platform-apis/for-models","api_endpoint":"https://api.fal.ai/v1/models"},"summary":"List Models","description":"Retrieve a list of available models with metadata including model information, availability, and basic details.","security":[{"bearerAuth":[]}]}},"/v1/models/{model_id}":{"get":{"tags":["Models"],"parameters":[{"name":"model_id","in":"path","description":"The unique identifier of the model","required":true,"schema":{"type":"string","example":""}}],"responses":{"401":{"description":"Bearer token required (Authorization header)","content":{"application/json":{}}}},"externalDocs":{"api_ref":"https://docs.fal.ai/platform-apis/for-models","api_endpoint":"https://api.fal.ai/v1/models/{model_id}"},"summary":"Get Model Details","description":"Get detailed information about a specific model including metadata, capabilities, and configuration.","security":[{"bearerAuth":[]}]}},"/v1/pricing":{"get":{"tags":["Pricing"],"parameters":[{"name":"model_id","in":"query","description":"Filter pricing by specific model ID","schema":{"type":"string","example":""}}],"responses":{"401":{"description":"Bearer token required (Authorization header)","content":{"application/json":{}}}},"externalDocs":{"api_ref":"https://docs.fal.ai/platform-apis/for-models","api_endpoint":"https://api.fal.ai/v1/pricing"},"summary":"Get Pricing Information","description":"Retrieve pricing information for models including cost per request, usage tiers, and billing details.","security":[{"bearerAuth":[]}]}},"/v1/usage":{"get":{"tags":["Usage"],"parameters":[{"name":"end_date","in":"query","description":"End date for usage statistics (ISO 8601 format)","schema":{"type":"string","example":""}},{"name":"model_id","in":"query","description":"Filter usage by specific model ID","schema":{"type":"string","example":""}},{"name":"start_date","in":"query","description":"Start date for usage statistics (ISO 8601 format)","schema":{"type":"string","example":""}}],"responses":{"401":{"description":"Bearer token required (Authorization header)","content":{"application/json":{}}}},"externalDocs":{"api_ref":"https://docs.fal.ai/platform-apis/for-models","api_endpoint":"https://api.fal.ai/v1/usage"},"summary":"Get Usage Statistics","description":"Retrieve usage statistics and tracking information for API requests including request counts, costs, and usage patterns.","security":[{"bearerAuth":[]}]}},"/v1/analytics":{"get":{"tags":["Analytics"],"parameters":[{"name":"end_date","in":"query","description":"End date for analytics data (ISO 8601 format)","schema":{"type":"string","example":""}},{"name":"metric","in":"query","description":"Specific metric to retrieve (e.g., requests, latency, errors)","schema":{"type":"string","example":""}},{"name":"model_id","in":"query","description":"Filter analytics by specific model ID","schema":{"type":"string","example":""}},{"name":"start_date","in":"query","description":"Start date for analytics data (ISO 8601 format)","schema":{"type":"string","example":""}}],"responses":{"401":{"description":"Bearer token required (Authorization header)","content":{"application/json":{}}}},"externalDocs":{"api_ref":"https://docs.fal.ai/platform-apis/for-models","api_endpoint":"https://api.fal.ai/v1/analytics"},"summary":"Get Analytics Data","description":"Retrieve analytics data including performance metrics, request patterns, error rates, and other analytical insights.","security":[{"bearerAuth":[]}]}},"/v1/compute/instances":{"get":{"tags":["Compute"],"parameters":[{"name":"limit","in":"query","description":"Maximum number of instances to return","schema":{"type":"number","example":""}},{"name":"offset","in":"query","description":"Number of instances to skip","schema":{"type":"number","example":""}},{"name":"status","in":"query","description":"Filter instances by status (active, stopped, etc.)","schema":{"type":"string","example":""}}],"responses":{"401":{"description":"Bearer token required (Authorization header)","content":{"application/json":{}}}},"externalDocs":{"api_ref":"https://docs.fal.ai/platform-apis/for-compute","api_endpoint":"https://api.fal.ai/v1/compute/instances"},"summary":"List Compute Instances","description":"List all compute instances with their current status, configuration, and lifecycle information.","security":[{"bearerAuth":[]}]},"post":{"tags":["Compute"],"parameters":[],"responses":{"401":{"description":"Bearer token required (Authorization header)","content":{"application/json":{}}}},"externalDocs":{"api_ref":"https://docs.fal.ai/platform-apis/for-compute","api_endpoint":"https://api.fal.ai/v1/compute/instances"},"summary":"Create Compute Instance","description":"Create a new compute instance with specified configuration and type.","security":[{"bearerAuth":[]}],"requestBody":{"description":"","required":true,"content":{"application/json":{"schema":{"type":"object","required":[],"properties":{"config":{"type":"object","description":"Configuration options for the instance","properties":{}},"instance_type":{"type":"string","description":"Type of compute instance to create","required":true},"name":{"type":"string","description":"Name for the compute instance"}}},"example":{"config":{},"instance_type":"","name":""}}}}}},"/v1/compute/instances/{instance_id}":{"get":{"tags":["Compute"],"parameters":[{"name":"instance_id","in":"path","description":"The unique identifier of the compute instance","required":true,"schema":{"type":"string","example":""}}],"responses":{"401":{"description":"Bearer token required (Authorization header)","content":{"application/json":{}}}},"externalDocs":{"api_ref":"https://docs.fal.ai/platform-apis/for-compute","api_endpoint":"https://api.fal.ai/v1/compute/instances/{instance_id}"},"summary":"Get Compute Instance Details","description":"Get detailed information about a specific compute instance including status, configuration, and monitoring data.","security":[{"bearerAuth":[]}]},"patch":{"tags":["Compute"],"parameters":[{"name":"instance_id","in":"path","description":"The unique identifier of the compute instance","required":true,"schema":{"type":"string","example":""}}],"responses":{"401":{"description":"Bearer token required (Authorization header)","content":{"application/json":{}}}},"externalDocs":{"api_ref":"https://docs.fal.ai/platform-apis/for-compute","api_endpoint":"https://api.fal.ai/v1/compute/instances/{instance_id}"},"summary":"Update Compute Instance","description":"Update configuration and settings for an existing compute instance.","security":[{"bearerAuth":[]}],"requestBody":{"description":"","required":true,"content":{"application/json":{"schema":{"type":"object","required":[],"properties":{"config":{"type":"object","description":"Updated configuration options for the instance","properties":{}},"name":{"type":"string","description":"Updated name for the compute instance"}}},"example":{"config":{},"name":""}}}}},"delete":{"tags":["Compute"],"parameters":[{"name":"instance_id","in":"path","description":"The unique identifier of the compute instance","required":true,"schema":{"type":"string","example":""}}],"responses":{"401":{"description":"Bearer token required (Authorization header)","content":{"application/json":{}}}},"externalDocs":{"api_ref":"https://docs.fal.ai/platform-apis/for-compute","api_endpoint":"https://api.fal.ai/v1/compute/instances/{instance_id}"},"summary":"Delete Compute Instance","description":"Delete a compute instance and release associated resources.","security":[{"bearerAuth":[]}],"requestBody":{"description":"","required":true,"content":{"application/json":{"schema":{"type":"object","required":[],"properties":{}},"example":{}}}}}},"/v1/compute/instances/{instance_id}/start":{"post":{"tags":["Compute"],"parameters":[{"name":"instance_id","in":"path","description":"The unique identifier of the compute instance","required":true,"schema":{"type":"string","example":""}}],"responses":{"401":{"description":"Bearer token required (Authorization header)","content":{"application/json":{}}}},"externalDocs":{"api_ref":"https://docs.fal.ai/platform-apis/for-compute","api_endpoint":"https://api.fal.ai/v1/compute/instances/{instance_id}/start"},"summary":"Start Compute Instance","description":"Start a stopped compute instance and make it available for use.","security":[{"bearerAuth":[]}],"requestBody":{"description":"","required":true,"content":{"application/json":{"schema":{"type":"object","required":[],"properties":{}},"example":{}}}}}},"/v1/compute/instances/{instance_id}/stop":{"post":{"tags":["Compute"],"parameters":[{"name":"instance_id","in":"path","description":"The unique identifier of the compute instance","required":true,"schema":{"type":"string","example":""}}],"responses":{"401":{"description":"Bearer token required (Authorization header)","content":{"application/json":{}}}},"externalDocs":{"api_ref":"https://docs.fal.ai/platform-apis/for-compute","api_endpoint":"https://api.fal.ai/v1/compute/instances/{instance_id}/stop"},"summary":"Stop Compute Instance","description":"Stop a running compute instance to pause its operation.","security":[{"bearerAuth":[]}],"requestBody":{"description":"","required":true,"content":{"application/json":{"schema":{"type":"object","required":[],"properties":{}},"example":{}}}}}},"/v1/compute/instances/{instance_id}/monitor":{"get":{"tags":["Compute"],"parameters":[{"name":"instance_id","in":"path","description":"The unique identifier of the compute instance","required":true,"schema":{"type":"string","example":""}},{"name":"end_time","in":"query","description":"End time for monitoring data (ISO 8601 format)","schema":{"type":"string","example":""}},{"name":"metrics","in":"query","description":"Comma-separated list of metrics to retrieve (e.g., cpu, memory, network)","schema":{"type":"string","example":""}},{"name":"start_time","in":"query","description":"Start time for monitoring data (ISO 8601 format)","schema":{"type":"string","example":""}}],"responses":{"401":{"description":"Bearer token required (Authorization header)","content":{"application/json":{}}}},"externalDocs":{"api_ref":"https://docs.fal.ai/platform-apis/for-compute","api_endpoint":"https://api.fal.ai/v1/compute/instances/{instance_id}/monitor"},"summary":"Monitor Compute Instance","description":"Retrieve monitoring data and metrics for a compute instance including CPU, memory, network usage, and performance statistics.","security":[{"bearerAuth":[]}]}},"/v1/batch":{"post":{"tags":["Batch"],"parameters":[],"responses":{"401":{"description":"Bearer token required (Authorization header)","content":{"application/json":{}}}},"externalDocs":{"api_ref":"https://docs.fal.ai/platform-apis","api_endpoint":"https://api.fal.ai/v1/batch"},"summary":"Batch Requests","description":"Combines multiple API calls into a single HTTP request to reduce the number of HTTP connections and improve performance.","security":[{"bearerAuth":[]}],"requestBody":{"description":"","required":true,"content":{"application/json":{"schema":{"type":"object","required":[],"properties":{"requests":{"type":"array","description":"Array of API requests to batch process. Each request should include method, path, and body/params as needed","required":true,"items":{"type":"string"}}}},"example":{"requests":[{"method":"GET","params":{"limit":10},"path":"/v1/models"},{"method":"GET","params":{"model_id":"model-123"},"path":"/v1/pricing"}]}}}}}},"/run/{model_id(.+)}":{"post":{"tags":["Inference"],"parameters":[{"name":"model_id","in":"path","description":"fal model endpoint id, may span multiple path segments (e.g. fal-ai/flux/schnell or fal-ai/any-llm)","required":true,"schema":{"type":"string","example":""}}],"responses":{"401":{"description":"Bearer token required (Authorization header)","content":{"application/json":{}}}},"externalDocs":{"api_ref":"https://fal.ai/docs/documentation/model-apis/inference/synchronous","api_endpoint":"https://fal.run/{model_id}"},"summary":"Run model (synchronous)","description":"Synchronous model inference - blocking call, no queue. Request body is the model's input schema (varies by model, e.g. {\"prompt\": \"...\"} for text-to-image); response is the model output (e.g. images array with url fields). Custom-regex path param spans segments for multi-part model ids.","security":[{"bearerAuth":[]}],"requestBody":{"description":"","required":true,"content":{"application/json":{"schema":{"type":"object","required":[],"properties":{"prompt":{"type":"string","description":"Text prompt - the most common input field; the request body is the model's input schema and varies by model (see the model page on fal.ai)"}}},"example":{"prompt":""}}}}}},"/queue/{model_id(.+)}":{"post":{"tags":["Inference"],"parameters":[{"name":"model_id","in":"path","description":"fal model endpoint id, may span multiple path segments (e.g. fal-ai/flux/schnell or fal-ai/any-llm)","required":true,"schema":{"type":"string","example":""}},{"name":"fal_webhook","in":"query","description":"Webhook URL to receive the completion payload","required":false,"schema":{"type":"string","example":""}}],"responses":{"401":{"description":"Bearer token required (Authorization header)","content":{"application/json":{}}}},"externalDocs":{"api_ref":"https://fal.ai/docs/documentation/model-apis/inference/queue","api_endpoint":"https://queue.fal.run/{model_id}"},"summary":"Queue model request","description":"Submit a request to the model's queue (recommended way to call models on fal). Returns request_id, response_url, status_url, cancel_url and queue_position. Optional fal_webhook query parameter to receive completion callbacks.","security":[{"bearerAuth":[]}],"requestBody":{"description":"","required":true,"content":{"application/json":{"schema":{"type":"object","required":[],"properties":{"prompt":{"type":"string","description":"Text prompt - the most common input field; the request body is the model's input schema and varies by model (see the model page on fal.ai)"}}},"example":{"prompt":""}}}}}},"/queue/{model_id(.+)}/requests/{request_id}/status":{"get":{"tags":["Inference"],"parameters":[{"name":"model_id","in":"path","description":"fal model endpoint id, may span multiple path segments (e.g. fal-ai/flux/schnell or fal-ai/any-llm)","required":true,"schema":{"type":"string","example":""}},{"name":"request_id","in":"path","description":"Queue request id from the submit response","required":true,"schema":{"type":"string","example":""}},{"name":"logs","in":"query","description":"Set to 1 to include runner logs","required":false,"schema":{"type":"string","example":""}}],"responses":{"401":{"description":"Bearer token required (Authorization header)","content":{"application/json":{}}}},"externalDocs":{"api_ref":"https://fal.ai/docs/documentation/model-apis/inference/queue","api_endpoint":"https://queue.fal.run/{model_id}/requests/{request_id}/status"},"summary":"Get queued request status","description":"Check queue status of a request: IN_QUEUE (queue_position), IN_PROGRESS (logs), or COMPLETED (logs, metrics.inference_time; error/error_type on failure). logs=1 includes runner logs.","security":[{"bearerAuth":[]}]}},"/queue/{model_id(.+)}/requests/{request_id}":{"get":{"tags":["Inference"],"parameters":[{"name":"model_id","in":"path","description":"fal model endpoint id, may span multiple path segments (e.g. fal-ai/flux/schnell or fal-ai/any-llm)","required":true,"schema":{"type":"string","example":""}},{"name":"request_id","in":"path","description":"Queue request id from the submit response","required":true,"schema":{"type":"string","example":""}}],"responses":{"401":{"description":"Bearer token required (Authorization header)","content":{"application/json":{}}}},"externalDocs":{"api_ref":"https://fal.ai/docs/documentation/model-apis/inference/queue","api_endpoint":"https://queue.fal.run/{model_id}/requests/{request_id}"},"summary":"Get queued request result","description":"Fetch the result of a completed queued request. Body is model-specific (image models return an images array with url, width, height, content_type).","security":[{"bearerAuth":[]}]}},"/queue/{model_id(.+)}/requests/{request_id}/cancel":{"put":{"tags":["Inference"],"parameters":[{"name":"model_id","in":"path","description":"fal model endpoint id, may span multiple path segments (e.g. fal-ai/flux/schnell or fal-ai/any-llm)","required":true,"schema":{"type":"string","example":""}},{"name":"request_id","in":"path","description":"Queue request id from the submit response","required":true,"schema":{"type":"string","example":""}}],"responses":{"401":{"description":"Bearer token required (Authorization header)","content":{"application/json":{}}}},"externalDocs":{"api_ref":"https://fal.ai/docs/documentation/model-apis/inference/queue","api_endpoint":"https://queue.fal.run/{model_id}/requests/{request_id}/cancel"},"summary":"Cancel queued request","description":"Request cancellation of a queued job. 202 CANCELLATION_REQUESTED, 400 ALREADY_COMPLETED, 404 NOT_FOUND.","security":[{"bearerAuth":[]}],"requestBody":{"description":"","required":true,"content":{"application/json":{"schema":{"type":"object","required":[],"properties":{}},"example":{}}}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}}},"security":[{"bearerAuth":[]}]}