The Prompt Bank generation API lets you queue image and video creation jobs with a single POST request to /api/v1/generations. Your job is dispatched asynchronously to fal.ai, and the output is saved directly to the vault you specify once processing completes. This guide covers every major generation scenario with complete, ready-to-run curl examples.
Generate an image
Send a POST /api/v1/generations request with generationType: "image" and a fal.ai modelId. The request requires the prompts:write scope. The example below uses Recraft v4.1:
The API responds with 202 Accepted to confirm your job is queued:
The generated image will appear in vault 42 once the fal.ai job completes. Use the statusUrl from the response to check progress.
Generate a video
Use generationType: "video" and a video-capable fal.ai endpoint. Everything else works the same as an image generation:
Video jobs typically take longer to process than image jobs. Use the returned statusUrl to check progress, or wait for the asset to appear in your vault.
Image-to-image
To use an existing image as the base for a new generation, provide its URL in the imageInput field. For models that accept multiple inputs, use imageInputs (up to 7 URLs):
Single input:
Multiple inputs:
To upload your own images for use as inputs, see the Upload Images guide.
Batch generation
Set batchCount to generate multiple variations from the same prompt in one job. Accepted values are 1 through 4:
All four images are saved to the specified vault when the job completes.
Saving to a specific vault
Supply an integer vaultId in your request to direct the output to a particular vault. If you omit vaultId, the output is saved to your General vault — the system vault created automatically for every account:
You can retrieve the output later by listing prompts in that vault: GET /api/v1/prompts?vaultId=99.
Tracking the generation
The 202 Accepted response includes a statusUrl you can poll to check the state of your job:
Poll the statusUrl until the job reaches a terminal state, or simply wait for the generated asset to appear in your vault.
The clientJobId is an optional identifier you supply when submitting the generation request. Providing your own value (for example, a UUID tied to a user action in your application) lets you correlate the job back to your own records, deduplicate retries, and look up the statusUrl by a stable key you control. If you omit clientJobId, one is generated automatically and returned in the 202 response.
Next steps