Create Generation

Submit a new video generation

POST /api/generations

Submits a new video generation for the API key owner. The request is queued immediately; poll Get Generation Status with the returned generation ID until the video is complete.

Request

curl "https://www.prismvideos.com/api/generations" \
  -X POST \
  -H "Authorization: Bearer prism_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A fast-paced product demo with bold captions",
    "modelName": "veo-3.1",
    "aspectRatio": "9:16",
    "duration": "8s",
    "resolution": "1080p",
    "count": 1,
    "hasAudio": true
  }'

Body parameters

Parameter	Type	Required	Description
prompt	string	Yes	Prompt for the generated video
modelName	string	Yes	Exact Prism video model ID, such as veo-3.1
aspectRatio	string	No	One of auto, 21:9, 16:9, 4:3, 1:1, 3:4, or 9:16
duration	string	No	Requested duration, such as 5s, 8s, or 10s
resolution	string	No	Requested resolution, such as 720p or 1080p
count	integer	No	Number of videos to queue, from 1 to 4
hasAudio	boolean	No	Whether to request generated audio for supported models
startFrameKey	string	No	S3 key for a start frame image returned by Upload Reference or asset APIs
endFrameKey	string	No	S3 key for an end frame image returned by upload or asset APIs
ingredientImageKeys	string[]	No	Image S3 keys to use as visual references
characterReferenceImageKeys	string[]	No	Image S3 keys to use as character references
sourceVideoKey	string	No	Uploaded source video S3 key for edit-capable models
referenceVideoKeys	string[]	No	Uploaded video S3 keys to use as video references
audioKey	string	No	Uploaded audio S3 key for audio-driven models
templateId	string	No	Template ID to associate with the generation

Using uploaded references

To generate from your own image, video, or audio file:

1. Call Upload Reference to get an upload_url and s3_key.
2. Upload the file with PUT upload_url.
3. Pass the returned s3_key into this endpoint.

For example, use an uploaded image as the first frame:

{
  "prompt": "Animate this product image into a clean studio video",
  "modelName": "veo-3.1",
  "startFrameKey": "users/user_abc/user-uploads/batch_abc/product.png"
}

Use the same s3_key pattern for other reference fields, such as ingredientImageKeys, characterReferenceImageKeys, sourceVideoKey, referenceVideoKeys, or audioKey.

Response

{
  "data": {
    "generations": [
      {
        "id": "gen_abc123",
        "asset_id": "asset_abc123",
        "request_id": "fal_request_abc123",
        "status": "queued"
      }
    ],
    "endpoint_id": "fal-ai/veo3",
    "variant": "text-to-video",
    "metadata": {
      "model_name": "veo-3.1",
      "selected_model_name": "veo-3.1",
      "credits_charged": 120,
      "num_generations": 1
    }
  }
}

Response fields

Field	Type	Description
data.generations[].id	string	Generation ID to pass to GET /api/generations/:id
data.generations[].asset_id	string or null	Asset record ID reserved for the generated video
data.generations[].request_id	string or null	Provider request ID when available
data.generations[].status	string or null	Initial queue status
data.endpoint_id	string or null	Provider endpoint used for the generation
data.variant	string or null	Resolved generation variant
data.metadata	object	Model and billing metadata for the submission

Errors

Status	Error	When
400	validation_error	Invalid JSON request body
400	model or parameter error	Missing or unsupported generation parameters
401	unauthorized	Missing or invalid API key
402	insufficient_credits	The account does not have enough credits
403	forbidden	API key lacks templates:read scope
503	free_tier_paused	Free tier generation is temporarily paused

See Errors for the full error reference.