This endpoint begins by converting your text prompt and chosen background footage into a complete video script, which is then used to create the video. Upon successful creation, you receive a unique identifier (apiFileId). You can use this apiFileId with the GET /get-file endpoint to monitor the video's export status—the export process generally takes about as long as the video's duration.For a more automated approach, you may also provide a webhook URL. With this option, status updates are sent directly to your endpoint, eliminating the need for manual polling of the GET /get-file endpoint.
Request
Authorization
Provide your bearer token in the
Authorization
header when making requests to protected resources.
Example:
Authorization: Bearer ********************
Body Params application/json
prompt
string
required
AI prompt that controls the script generation.
targetScriptWordCount
integer
optional
Target word count for the generated script. Not exact, but VideoGen's AI will attempt to generate a script close to this word count.
List of website URLs to be scanned by VideoGen's AI and included along with the AI prompt to generate the script.
useGetty
boolean
optional
Option to include Getty/iStock assets, if available.
useGenerativeImage
boolean
optional
Option to include generative images.
imageGenStyle
string
optional
Style used for the generative images.
voice
string
optional
Name of the voice for AI narration.
Default:
Matilda
voiceVolume
number
optional
Volume level for the voice narration, ranging from 0 (silent) to 1 (loudest).
>= 0<= 1
Default:
1
musicUrl
string
optional
URL of the background music.
musicVolume
number
optional
Volume level for the background music, ranging from 0 (silent) to 1 (loudest).
>= 0<= 1
Default:
0.15
captionDetails
object(Caption Details)
optional
Style of captions in the video.
captionFontName
string
optional
Font name for the captions text.
captionFontWeight
number
optional
Font weight for the captions text. Some fonts support 400 (normal) and 700 (bold), whereas other fonts don't support multiple font weights. The rendered font weight will be the supported font weight closest to captionFontWeight.
captionFontSize
number
optional
Font size for the captions text. 35 is tiny, 50 is small, 75 is medium, and 100 is large.
captionTextColor
object(Color)
optional
Color of the captions text.
captionTextJustification
enum<string>
optional
Text justification of the captions.
Allowed values:
LEFTCENTERRIGHT
captionVerticalAlignment
enum<string>
optional
Vertical alignment of the captions.
Allowed values:
TOPMIDDLEBOTTOM
captionStrokeColor
object(Color)
optional
Stroke color of the captions text.
captionStrokeWeight
number
optional
Stroke weight of the captions text. This determines the thickness of the border around each character of text. Normally ranges from 0 (no stroke) to 8 (thick stroke).
captionBackgroundStyleType
enum<string>
optional
Style of the background behind the captions text.
Allowed values:
RECTWRAPPED
captionBackgroundColor
object(Color)
optional
Color of the background behind the captions text.
captionBackgroundBorderRadius
number
optional
Border radius of the background behind the captions text, as a proportion of the smaller side length.
>= 0<= 1
captionBackgroundOpacity
number
optional
Opacity of the background behind the captions, ranging from 0 (fully hidden) to 1 (fully visible).
captionIsHidden
boolean
optional
Captions are hidden for the entire video. Use VGML for more fine-grained control.
aspectRatio
object(Aspect Ratio)
optional
Aspect ratio of the video.
width
number
required
Width component of the aspect ratio.
height
number
required
Height component of the aspect ratio.
minDimensionPixels
integer
optional
Minimum dimension of the video in pixels. Height and width will be calculated based on minDimensionPixels and aspectRatio.
<= 1080> 0
Default:
1080
webhookUrl
string
optional
URL for your webhook, which will receive a POST request with JSON body { apiFileId: string; apiFileSignedUrl: string } once the video is generated.
Example
{"prompt":"Best restaurants in San Francisco","targetScriptWordCount":50,"websiteUrls":["https://www.chezmamanrestos.com/"]}
Request samples
Shell
JavaScript
Java
Swift
Go
PHP
Python
HTTP
C
C#
Objective-C
Ruby
OCaml
Dart
R
Request Request Example
Shell
JavaScript
Java
Swift
curl--location--request POST 'https://ext.videogen.io/v2/prompt-to-video' \
--header'Content-Type: application/json' \
--data-raw'{
"prompt": "Best restaurants in San Francisco",
"targetScriptWordCount": 50,
"websiteUrls": [
"https://www.chezmamanrestos.com/"
]
}'