Skip to main content

​
Generate Video

POST /api/templates/:id/generate
Submit a video generation request using a template. Provide values for the template’s input variables and receive a generation ID to poll for status.

​
Path parameters

ParameterTypeDescription
idstringThe template ID

​
Request body

FieldTypeRequiredDescription
variablesobjectYesKey-value map of variable values. Text variables are strings. File variables (image, video, audio) can be URLs, uploads, data URIs, or S3 keys depending on how you submit the request.
character_variablesobjectNoMap of image variable keys to character IDs from GET /api/characters or POST /api/characters. Only supported for ingredients-to-video templates. For the same key, this overrides variables[key] and template default_value.
webhook_urlstringNoURL to receive a POST callback when generation completes or fails.

​
Request

curl -X POST "https://prismvideos.com/api/templates/abc123/generate" \
  -H "Authorization: Bearer prism_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "variables": {
      "hook": "Check out this amazing product",
      "productImage": "https://example.com/product.jpg",
      "benefit": "2x faster results"
    },
    "character_variables": {
      "personImage": "d2a7e0d5-1705-43b5-be96-85b9c5f25b80"
    },
    "webhook_url": "https://example.com/webhook"
  }'

​
Response

{
  "generations": [
    {
      "generation_id": "gen_abc123",
      "status": "generating"
    }
  ],
  "template_id": "abc123",
  "credits_charged": 50,
  "latency_estimate_sec": {
    "typical": 127,
    "busy": 241
  }
}

​
Response fields

FieldTypeDescription
generationsarrayList of generation objects (one per video)
generations[].generation_idstringUnique generation ID for polling status
generations[].statusstringAlways "generating" on success
template_idstringThe template used for generation
credits_chargednumberTotal credits deducted
latency_estimate_secobject or nullEstimated generation latency window for the selected model/mode
latency_estimate_sec.typicalnumberTypical completion time in seconds
latency_estimate_sec.busynumberBusy-period completion time in seconds
Use latency_estimate_sec to choose a polling cadence for GET /api/generations/:id (for example, every typical / 6 seconds, clamped to 10-30s).

​
Variable values

  • Text variables: Provide a string value. If omitted, the template’s default_value is used.
  • Image variables: Provide an HTTP(S) URL, an S3 key, a base64 data URI, or upload the file with multipart/form-data.
  • Video variables: Same as image — HTTP(S) URL, S3 key, data URI, or multipart upload.
  • Audio variables: Same as image/video — HTTP(S) URL, S3 key, data URI, or multipart upload.
  • Required variables: If a required variable has no value and no default, the request returns 400.
  • Character variables: For ingredients-to-video templates, provide character IDs keyed by image variable name (for example "personImage": "character-id"). IDs can come from public characters or private characters you created with your own API key.

​
Image input precedence

For image variable keys (for example personImage, productImage), generation resolves values in this order:
  1. character_variables[key] (Prism character ID)
  2. variables[key] (image URL/S3 key/data URI/upload)
  3. template default_value
This means you can supply a person either as an image or as a Prism character. If both are provided for the same key, the character mapping wins. When you send JSON:
  • Public HTTP(S) URLs are downloaded by the server and re-hosted before generation.
  • Base64 data URIs are converted to hosted files automatically.
  • S3 keys are accepted for files you’ve already uploaded into Prism storage.
When you have local files:
  • Send multipart/form-data and attach the file directly to variables[KEY].
  • Example:
curl -X POST "https://prismvideos.com/api/templates/abc123/generate" \
  -H "Authorization: Bearer prism_sk_your_key_here" \
  -F "variables[avatarImage]=@./avatar.png" \
  -F "variables[voiceAudio]=@./voiceover.mp3"

​
Webhook callback

If webhook_url is provided, the server POSTs to that URL when the generation completes or fails: 
{
  "generation_id": "gen_abc123",
  "status": "completed",
  "template_id": "abc123",
  "video_url": "https://presigned-s3-url...",
  "error": null
}
For failed generations: 
{
  "generation_id": "gen_abc123",
  "status": "failed",
  "template_id": "abc123",
  "video_url": null,
  "error": "Generation timed out"
}

​
Errors

StatusErrorWhen
400validation_errorMissing required variables or invalid input
401unauthorizedMissing or invalid API key
402insufficient_creditsNot enough credits for generation
403forbiddenAPI key lacks templates:read scope
404not_foundNo template exists with the given ID
422invalid_templateTemplate has invalid configuration
500generation_errorUnexpected server error during generation
See Errors for the full error reference.