Skip to main content
POST
/
pictoryapis
/
v1
/
aistudio
/
videos
Generate Video
curl --request POST \
  --url https://api.pictory.ai/pictoryapis/v1/aistudio/videos \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: <content-type>' \
  --data '
{
  "prompt": "<string>",
  "model": "<string>",
  "aspectRatio": "<string>",
  "duration": "<string>",
  "firstFrameImageUrl": "<string>",
  "extendVideoUrl": "<string>",
  "referenceImageUrls": [
    {}
  ],
  "webhook": "<string>"
}
'
{
    "success": true,
    "data": {
        "jobId": "4a09edf9-d071-4847-bda5-8dea913d80fe"
    }
}

​
Overview

The Generate Video API creates an AI-generated video based on a text prompt. You can choose from multiple AI video models, specify an aspect ratio and duration, and optionally provide a first frame image, a video to extend, or reference images to guide the output. The API returns a job ID that you can use to poll for the result once the video generation is complete.
A valid API key is required to use this endpoint. Obtain your API key from the API Access page in your Pictory dashboard.

​
API Endpoint

POST https://api.pictory.ai/pictoryapis/v1/aistudio/videos

​
Request Headers

​
Authorization
string
required
API key for authentication (starts with pictai_)
Authorization: YOUR_API_KEY
​
Content-Type
string
required
Must be application/json

​
Request Body

​
prompt
string
required
A text description of the video you want to generate. The prompt must be between 5 and 5,000 characters.Example: "A drone flying over a lush green forest with sunlight filtering through the canopy"
​
model
string
The AI model to use for video generation. Each model offers different quality levels, durations, and aspect ratios. Defaults to pixverse5.5 if not specified.Supported models: veo3.1, veo3.1_fast, pixverse5.5Model Capabilities and Pricing:
ModelSupported Aspect RatiosSupported DurationsAI Credits per Second
veo3.116:9, 9:164s, 6s, 8s20
veo3.1_fast16:9, 9:164s, 6s, 8s10
pixverse5.516:9, 9:16, 1:1, 3:4, 4:35s, 8s, 10s1.6
​
aspectRatio
string
The aspect ratio for the generated video. The available values depend on the selected model. Defaults to the first supported aspect ratio of the chosen model. Refer to the model table above for supported aspect ratios per model.
​
duration
string
The duration of the generated video. The available values depend on the selected model. Defaults to the first supported duration of the chosen model. Refer to the model table above for supported durations per model.
​
firstFrameImageUrl
string
An optional URL of an image to use as the first frame of the video. This guides the visual starting point for the generation. The URL must be a valid, publicly accessible URI.
This parameter cannot be used together with extendVideoUrl or referenceImageUrls.
​
extendVideoUrl
string
An optional URL of an existing video to extend. The AI model will generate additional content that continues from the end of the provided video. The URL must be a valid, publicly accessible URI.
This parameter cannot be used together with firstFrameImageUrl.
​
referenceImageUrls
array
An optional array of image URLs (1 to 3) to use as visual references for the generated video. The AI model will use these images to influence the style and content of the output. Each URL must be a valid, publicly accessible URI.
This parameter cannot be used together with firstFrameImageUrl or extendVideoUrl.
​
webhook
string
An optional webhook URL that will receive a notification when the video generation job completes. The URL must be a valid URI.

​
Response

​
Success Response (200)

​
success
boolean
true when the job has been created successfully
​
data
object
​
jobId
string
The unique identifier (UUID) of the video generation job. Use this ID to poll for the result using the Get Video Generation Job endpoint.

​
Response Examples

{
    "success": true,
    "data": {
        "jobId": "4a09edf9-d071-4847-bda5-8dea913d80fe"
    }
}

​
Status Codes

Status CodeDescription
200Job created successfully. Use the returned jobId to poll for the result.
400Invalid request body. Check the fields array for specific validation errors. This also occurs when mutually exclusive parameters are used together.
401Unauthorized. The API key in the Authorization header is missing or invalid.
500Internal server error. Retry the request after a brief delay.

​
Parameter Exclusivity

The firstFrameImageUrl, extendVideoUrl, and referenceImageUrls parameters are mutually exclusive. You may use only one of these in a single request. Providing more than one will result in a 400 validation error.
ParameterCan be combined with
firstFrameImageUrlprompt, model, aspectRatio, duration, webhook only
extendVideoUrlprompt, model, aspectRatio, duration, webhook only
referenceImageUrlsprompt, model, aspectRatio, duration, webhook only

​
Code Examples

Replace YOUR_API_KEY with your actual API key from the API Access page.
curl --request POST \
  --url 'https://api.pictory.ai/pictoryapis/v1/aistudio/videos' \
  --header 'Authorization: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "prompt": "A drone flying over a lush green forest with sunlight filtering through the canopy",
    "model": "pixverse5.5",
    "aspectRatio": "16:9",
    "duration": "8s"
  }'

​
Next Steps

After receiving the jobId, poll for the video generation result using the Get Video Generation Job endpoint. Use a polling interval of 10–30 seconds to check the job status.