Submit fal.ai Request to Queue
fal_submit_requestSubmit a generative AI job to fal.ai's async queue and get a request ID for tracking progress. Use for slow models like video generation or training jobs.
Instructions
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
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| model_id | Yes | The fal.ai model/endpoint id, e.g. "fal-ai/flux/dev", "fal-ai/flux-pro/kontext", or "fal-ai/minimax/video-01". Find valid ids with fal_list_models or at https://fal.ai/models. | |
| arguments | Yes | The model's input arguments as a JSON object, matching that model's own schema (e.g. { "prompt": "a cat astronaut", "image_size": "square_hd" }). Call fal_get_model_schema first if you're unsure what fields a model accepts. | |
| webhook_url | No | Optional. If set, fal POSTs the result here when done instead of requiring polling. | |
| response_format | No | Output format: 'markdown' for human-readable or 'json' for machine-readable (default: markdown) | markdown |