AI Generations: Queue and Save Media with Prompt Bank

The generation system in Prompt Bank lets you queue AI image and video creation jobs with a single API call. You describe what you want, choose a model, and the API dispatches the job to fal.ai on your behalf. When the model finishes, the output is saved directly to your vault — no manual download required.

Generations are asynchronous. The response to POST /api/v1/generations confirms that your job was queued — it does not contain the finished image or video. Use the statusUrl from the response to track progress, and expect the output to appear in your vault once the job completes.

How generations work

Queuing a generation follows these steps:

Queue the job — Send POST /api/v1/generations with your prompt, model, and any generation parameters. The API returns HTTP 202 Accepted with a clientJobId, a falRequestId, and a statusUrl.
Job runs on fal.ai — Prompt Bank forwards the request to the fal.ai inference infrastructure. Processing time varies by model and content type — images typically finish in seconds; videos may take longer.
Output saved to your vault — Once the model finishes, Prompt Bank asynchronously saves the generated media to the vault you specified (or your General vault if you didn’t supply a vaultId). The asset becomes queryable via the prompts and vault endpoints.

Supported generation types

Type	`generationType` value	Notes
Image	`image`	Static image output. Supports aspect ratio, batch count, and image-to-image inputs. Default when `generationType` is omitted.
Video	`video`	Video clip output. Model availability varies — check fal.ai for supported video endpoints.

Key parameters

Parameter	Type	Required	Default	Description
`modelId`	string	Yes	—	The fal.ai model endpoint to run (e.g., `fal-ai/recraft/v4.1/text-to-image`).
`prompt`	string	Yes	—	The instruction text for the model. Maximum 100,000 characters.
`generationType`	string	No	`image`	`image` or `video`.
`aspectRatio`	string	No	`1:1`	Output dimensions, e.g. `16:9`, `1:1`, `9:16`, `4:3`.
`batchCount`	integer	No	`1`	Number of outputs to generate in one job. Accepted values: `1`–`4`.
`clientJobId`	string	No	—	An optional identifier you supply to correlate the job in your own system.
`imageInput`	string (URI)	No	—	A single image URL used as the base for image-to-image generation.
`imageInputs`	array (URI)	No	—	Up to 7 image URLs for models that accept multiple input images.
`negativePrompt`	string	No	—	Describes what you want the model to avoid in the output. Maximum 100,000 characters.
`referenceImageUrls`	array (URI)	No	—	Up to 7 image URLs provided as style or content references.
`parameters`	object	No	—	Model-specific parameters passed directly to the fal.ai endpoint.
`vaultId`	integer	No	—	The numeric ID of the vault where output will be saved. Defaults to your General vault.
`imageEditEndpointId`	string	No	—	Specifies an image-editing endpoint variant when using image-edit workflows.

Generation response

A successful POST /api/v1/generations returns HTTP 202 Accepted with the following JSON envelope:

Field	Description
`data.success`	`true` when the job was successfully queued.
`data.clientJobId`	A stable identifier you assigned or that Prompt Bank generated. Use this to correlate the job in your own system.
`data.falRequestId`	The request ID assigned by fal.ai. Useful for support or direct fal.ai status lookups.
`data.statusUrl`	A URL you can poll to check whether the job is pending, running, or complete.
`error`	`null` on success. Contains an error message string if the request failed.

Where output goes

Generated media is saved asynchronously to the vault identified by the vaultId you included in the request. If you omit vaultId, the output lands in your General vault. Each output is stored as a prompt entry so you can retrieve, share, or fork it like any other prompt. Because saving is asynchronous, the asset may not appear immediately after the statusUrl reports completion — allow a brief moment for the vault to update.

Example request and response

curl -X POST https://www.promptbank.club/api/v1/generations \
  -H "Authorization: Bearer pb_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "modelId": "fal-ai/recraft/v4.1/text-to-image",
    "prompt": "A vast cyberpunk city at dusk, towering neon-lit skyscrapers reflected in rain-soaked streets, volumetric fog, cinematic composition, 8k detail",
    "generationType": "image",
    "aspectRatio": "16:9",
    "batchCount": 2,
    "vaultId": 42
  }'

{
  "data": {
    "success": true,
    "clientJobId": "job_01hxyz5555aaaa6666bbbb",
    "falRequestId": "fal-req-abc123def456",
    "statusUrl": "https://www.promptbank.club/api/v1/generations/job_01hxyz5555aaaa6666bbbb/status"
  },
  "error": null
}

Next steps

See the Generate Media guide for complete examples covering image-to-image, video generation, batch jobs, and how to track your outputs.

Get Started

Core Concepts

Guides

AI Generations: Queue and Save Media with Prompt Bank

How generations work

Supported generation types

Key parameters

Generation response

Where output goes

Example request and response

Next steps

​How generations work

​Supported generation types

​Key parameters

​Generation response

​Where output goes

​Example request and response

​Next steps

How generations work

Supported generation types

Key parameters

Generation response

Where output goes

Example request and response

Next steps