Run a fal.ai model and block until the result is ready. Best for fast models (a few seconds up to ~2 minutes) like most image generation, image editing, and short text/audio models.

This does NOT use the queue — there is no request_id to check later. For slow models (video generation, training jobs) or when you want to fire off a job and check back later, use fal_submit_request instead.

Args:

• model_id (string): The fal.ai model id, e.g. "fal-ai/flux/dev"

• arguments (object): Model-specific input, e.g. { "prompt": "a cat astronaut" }

• response_format ('markdown' | 'json'): Output format (default: markdown)

Returns: The model's result payload (structure is model-specific — images/video/audio/text). For JSON format: the complete raw result object. For markdown format: a summary with any generated media URLs surfaced up top.

Examples:

• Use when: "Generate an image of a sunset" -> model_id="fal-ai/flux/dev", arguments={"prompt": "a sunset over mountains"}

• Use when: "Edit this image to add snow" -> model_id="fal-ai/flux-pro/kontext", arguments={"prompt": "add snow", "image_url": "https://..."}

• Don't use when: the model is slow (video, training) — use fal_submit_request instead

• Don't use when: you don't know the model's required fields — call fal_get_model_schema first

Error Handling:

• Returns "Authentication failed" if FAL_KEY is missing or invalid

• Returns "Invalid input (422)" if arguments don't match the model's schema — check fal_get_model_schema

• Returns "Request timed out" if the model takes longer than 5 minutes — use fal_submit_request instead

Submit a job to fal.ai's async queue and return immediately with a request_id. Use this for slow models (video generation, training jobs) or whenever you don't want to block waiting for a result.

After submitting, use fal_check_status to poll progress and fal_get_result once status is COMPLETED. This does NOT wait for or return the final result — see fal_run_model if you want a single blocking call instead.

Args:

• model_id (string): The fal.ai model id, e.g. "fal-ai/minimax/video-01"

• arguments (object): Model-specific input, e.g. { "prompt": "a cat astronaut" }

• webhook_url (string, optional): URL fal should POST the result to on completion

• response_format ('markdown' | 'json'): Output format (default: markdown)

Returns: For JSON format: { "request_id": string, "status": string, "status_url": string, "response_url": string, "cancel_url": string, "queue_position": number } For markdown format: the same fields, human-readable, plus next-step guidance.

Examples:

• Use when: "Generate a video of a rocket launch" -> model_id="fal-ai/minimax/video-01", arguments={"prompt": "a rocket launch"}

• Use when: "Kick off this training job and let me know status later" -> submit, then poll with fal_check_status

• Don't use when: the model is fast and you want the result immediately — use fal_run_model instead

Error Handling:

• Returns "Authentication failed" if FAL_KEY is missing or invalid

• Returns "Invalid input (422)" if arguments don't match the model's schema — check fal_get_model_schema

• Returns "Not found (404)" if the model_id doesn't exist

Check the status of a request previously submitted with fal_submit_request. Does NOT return the final output — once status is COMPLETED, call fal_get_result to fetch it.

Args:

• model_id (string): The same model id used when submitting, e.g. "fal-ai/minimax/video-01"

• request_id (string): The request_id returned by fal_submit_request

• include_logs (boolean): Include runner logs (default: false)

• response_format ('markdown' | 'json'): Output format (default: markdown)

Returns: Status object with fields: { "status": "IN_QUEUE" | "IN_PROGRESS" | "COMPLETED", "request_id": string, "queue_position": number, // present while IN_QUEUE "logs": array | null // present if include_logs=true }

Examples:

• Use when: "Is my video ready yet?" -> check status, then fal_get_result if COMPLETED

• Don't use when: you haven't submitted a request yet — use fal_submit_request first

• Don't use when: you want the actual output — use fal_get_result after status is COMPLETED

Error Handling:

• Returns "Not found (404)" if the request_id is wrong or the request has expired

• Returns "Authentication failed" if FAL_KEY is missing or invalid

Fetch the final output of a queued request submitted with fal_submit_request. Only call this once fal_check_status reports status COMPLETED — calling it earlier will error.

Args:

• model_id (string): The same model id used when submitting, e.g. "fal-ai/minimax/video-01"

• request_id (string): The request_id returned by fal_submit_request

• response_format ('markdown' | 'json'): Output format (default: markdown)

Returns: The model's result payload (structure is model-specific — images/video/audio/text). For JSON format: the complete raw result object. For markdown format: a summary with any generated media URLs surfaced up top.

Examples:

• Use when: fal_check_status just reported "COMPLETED" for this request_id

• Don't use when: status is still IN_QUEUE or IN_PROGRESS — check status again instead

Error Handling:

• Returns "Not found (404)" if the request_id is wrong, expired, or not yet completed

• Returns "Authentication failed" if FAL_KEY is missing or invalid

Cancel a queued request before it finishes processing. Only works while status is IN_QUEUE — requests already IN_PROGRESS or COMPLETED cannot be cancelled and this will return an error.

Args:

• model_id (string): The same model id used when submitting, e.g. "fal-ai/minimax/video-01"

• request_id (string): The request_id returned by fal_submit_request

Returns: A confirmation message once the cancellation is accepted.

Examples:

• Use when: "Actually, cancel that video job I just started" -> cancel while still IN_QUEUE

• Don't use when: the job is already IN_PROGRESS or COMPLETED (use fal_check_status to confirm first)

Error Handling:

• Returns "Not found (404)" if the request_id is wrong

• Returns an error if the request already started processing or completed (cannot be cancelled)

Search or browse fal.ai's catalog of 600+ hosted models to find the right model id for a task. Does NOT run any model — this is discovery only.

Args:

• query (string, optional): Keyword search, e.g. "flux", "upscale", "text to speech"

• category (string, optional): Category filter, e.g. "text-to-image", "image-to-video"

• limit (number): Maximum results to return, 1-100 (default: 20)

• cursor (string, optional): Pagination cursor from a previous response's next_cursor

• response_format ('markdown' | 'json'): Output format (default: markdown)

Returns: For JSON format: { "count": number, "models": [ { "endpoint_id": string, "title": string, "category": string, "short_description": string } ], "has_more": boolean, "next_cursor": string | null } For markdown format: a readable list of matching models with their ids.

Examples:

• Use when: "What model should I use to generate a video?" -> query="video" or category="text-to-video"

• Use when: "Find a background removal model" -> query="background removal"

• Don't use when: you already know the exact model_id — go straight to fal_run_model or fal_submit_request

Error Handling:

• Returns "No models found matching ''" if the search returns empty

• Returns "Authentication failed" if FAL_KEY is missing or invalid

Fetch the OpenAPI schema for a specific fal.ai model, showing exactly which input fields it accepts (names, types, defaults, enums) and what its output looks like. Call this before fal_run_model or fal_submit_request whenever you're unsure of a model's required arguments.

Args:

• model_id (string): The fal.ai model id, e.g. "fal-ai/flux-pro/kontext"

• response_format ('markdown' | 'json'): Output format (default: markdown)

Returns: For JSON format: the raw OpenAPI document for that model endpoint. For markdown format: a summary of the request/response schemas.

Examples:

• Use when: "What parameters does fal-ai/flux-pro/kontext take?" -> model_id="fal-ai/flux-pro/kontext"

• Use when: you got a 422 error from fal_run_model and need to see the correct field names

• Don't use when: you already know the model's arguments from prior use

Error Handling:

• Returns "Not found (404)" if the model_id doesn't exist

• Returns "Authentication failed" if FAL_KEY is missing or invalid

Reads a local file and returns it as a base64 data: URI that can be passed directly into fal model arguments (e.g. as an image_url field) wherever a hosted file URL is expected. fal's API accepts base64 data URIs anywhere it accepts a file URL — no separate upload step is required.

This is a local, offline operation — it does not contact fal.ai or any network service.

Args:

• file_path (string): Absolute path to a local file (e.g. an image to use in an image-to-image model)

Returns: A data: URI string, e.g. "data:image/png;base64,iVBORw0KG...". Use this string directly as the value of an image_url (or similar) field in fal_run_model / fal_submit_request arguments.

Examples:

• Use when: "Use this local screenshot as input for the kontext model" -> encode it, then pass the result as image_url

• Don't use when: the file is already hosted at a public URL — just pass that URL directly

• Don't use when: the file is very large (>10MB) — large data URIs slow down requests; host the file publicly instead

Error Handling:

• Returns "File not found" if the path doesn't exist

• Returns "File too large" if the file exceeds 15MB (data URI overhead makes this impractical)