Skip to main content
The generations endpoint lets you kick off an AI image or video generation without waiting for the result. You submit your model, prompt, and any options; Prompt Bank enqueues the job, forwards it to fal.ai, and saves the finished output directly to your vault. Your application gets a job ID and a status URL back immediately so it can move on while the generation runs in the background.

​
Endpoint

Required scope: prompts:write

​
Request Body

​
string
required
The fal.ai model endpoint ID to use for this generation. For example: fal-ai/recraft/v4.1/text-to-image. You can find supported model IDs in your Prompt Bank dashboard or in the fal.ai model library.
​
string
required
The generation prompt text. Maximum 100,000 characters. Describes what you want the model to produce.
​
string
default:"image"
The type of output to generate. Accepted values: image, video. Defaults to image.
​
string
An optional job correlation ID you supply for idempotency and tracking. If omitted, Prompt Bank generates one for you. The value is echoed back in the response and can be used to correlate status checks with the original request.
​
string
A description of things you want the model to exclude from the output. Maximum 100,000 characters. Not all models support this field; it is silently ignored when unsupported.
​
string
A URI pointing to a source image for image-to-image generations. Must be a publicly accessible URL or a Prompt Bank upload URL obtained from the Upload Image endpoint.
​
array
An array of image URIs for models that accept multiple input images (e.g. multi-reference or inpainting workflows). Maximum 7 items. Each item follows the same URI rules as imageInput.
​
string
default:"1:1"
The target aspect ratio of the generated output. Common values: "1:1", "9:16", "16:9", "4:5", "3:2". Support varies by model.
​
integer
default:"1"
Number of outputs to generate in a single job. Accepted range: 1–4. Each output is saved as a separate asset in the destination vault.
​
object
An object of model-specific extra parameters passed through directly to the fal.ai API. The accepted keys and value types depend on the chosen model. Refer to the fal.ai model documentation for available options.
​
integer
The numeric ID of the vault where the finished output should be saved. If omitted, the output is saved to your account’s General vault.
​
array
An array of image URIs used as style or content references for models that support reference-image conditioning. Maximum 7 items.
​
string
The model endpoint ID to use for image editing workflows. Supply this when you want to apply an editing model on top of imageInput rather than run a standard text-to-image generation.

​
Response — 202 Accepted

​
boolean
Always true for a successfully queued generation.
​
string
The job correlation ID. This is the value you supplied in the request, or an auto-generated UUID if you did not supply one.
​
string
The underlying fal.ai request ID. You can use this value to look up detailed processing logs in the fal.ai dashboard.
​
string
A URL you can poll to check the status of this generation. The generation is complete when the status transitions to completed, at which point the output is available in your vault.

​
Examples

Basic image generation
Video generation with a client-supplied job ID
This endpoint is asynchronous. A 202 response means the job has been accepted and queued — the finished image or video is not in the response body. The output appears in your vault only after the generation completes. Poll data.statusUrl or listen for a webhook to know when it is ready.
Always supply a clientJobId when you fire off multiple jobs in quick succession. A stable, unique ID per job lets you match status updates back to the original request without relying on the auto-generated UUID.