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. Image/video variables are URLs (HTTP or S3).
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"
    },
    "webhook_url": "https://example.com/webhook"
  }'

​
Response

{
  "generations": [
    {
      "generation_id": "gen_abc123",
      "status": "generating"
    }
  ],
  "template_id": "abc123",
  "credits_charged": 50
}

​
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

​
Variable values

  • Text variables: Provide a string value. If omitted, the template’s default_value is used.
  • Image variables: Provide an HTTP(S) URL to the image. The server downloads and uploads it to S3 automatically. You can also provide an S3 key if you’ve pre-uploaded the file.
  • Video variables: Same as image — provide an HTTP(S) URL or S3 key.
  • Required variables: If a required variable has no value and no default, the request returns 400.

​
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.