> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pictory.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Generate Video from Text Prompt
> Create AI-generated videos from descriptive text prompts using the Pictory AI Studio API
This guide walks you through generating an AI video from a text prompt using the Pictory AI Studio API. You will learn how to submit a prompt, select a model, configure the aspect ratio and duration, and retrieve the generated video by polling the job status.
## What You Will Build
Generate videos from descriptive text prompts
Choose from multiple AI video models
Set the video length based on your needs
Generate landscape, portrait, or square videos
## Before You Begin
Make sure you have:
* A Pictory API key ([get one here](https://app.pictory.ai/api-access))
* Node.js or Python installed on your machine
* The required packages installed
```bash npm theme={null}
npm install axios
```
```bash pip theme={null}
pip install requests
```
## Step-by-Step Guide
### Step 1: Set Up Your Request
Prepare your API credentials and define the video prompt along with the desired model, aspect ratio, and duration.
```javascript Node.js theme={null}
import axios from "axios";
const API_BASE_URL = "https://api.pictory.ai/pictoryapis";
const API_KEY = "YOUR_API_KEY"; // Replace with your actual API key
// Video generation configuration
const videoRequest = {
prompt: "A young woman sitting on a couch in a modern living room, watching television with soft ambient lighting in a wide camera shot",
model: "pixverse5.5",
aspectRatio: "9:16",
duration: "8s"
};
```
```python Python theme={null}
import requests
import time
API_BASE_URL = "https://api.pictory.ai/pictoryapis"
API_KEY = "YOUR_API_KEY" # Replace with your actual API key
# Video generation configuration
video_request = {
"prompt": "A young woman sitting on a couch in a modern living room, watching television with soft ambient lighting in a wide camera shot",
"model": "pixverse5.5",
"aspectRatio": "9:16",
"duration": "8s"
}
```
### Step 2: Submit the Video Generation Request
Send the request to the AI Studio video generation endpoint. On success, the API returns a `jobId` that you will use to poll for the result.
```javascript Node.js theme={null}
async function generateVideo() {
try {
console.log("Submitting video generation request...");
const response = await axios.post(
`${API_BASE_URL}/v1/aistudio/videos`,
videoRequest,
{
headers: {
"Content-Type": "application/json",
Authorization: API_KEY,
},
}
);
const jobId = response.data.data.jobId;
console.log("Video generation started.");
console.log("Job ID:", jobId);
return jobId;
} catch (error) {
console.error("Error submitting request:", error.response?.data || error.message);
throw error;
}
}
```
```python Python theme={null}
def generate_video():
try:
print("Submitting video generation request...")
response = requests.post(
f"{API_BASE_URL}/v1/aistudio/videos",
json=video_request,
headers={
"Content-Type": "application/json",
"Authorization": API_KEY
}
)
response.raise_for_status()
job_id = response.json()["data"]["jobId"]
print("Video generation started.")
print(f"Job ID: {job_id}")
return job_id
except requests.exceptions.RequestException as error:
print(f"Error submitting request: {error}")
raise
```
### Step 3: Poll for the Result
Check the job status at regular intervals until the video is ready. The recommended polling interval is 10 to 30 seconds. Video generation typically takes longer than image generation.
```javascript Node.js theme={null}
async function waitForVideo(jobId) {
console.log("\nPolling for video generation result...");
while (true) {
const response = await axios.get(
`${API_BASE_URL}/v1/jobs/${jobId}`,
{
headers: { Authorization: API_KEY },
}
);
const data = response.data;
const status = data.data.status;
console.log("Status:", status);
if (status === "completed") {
console.log("\nVideo generated successfully!");
console.log("Video URL:", data.data.url);
console.log("Duration:", data.data.duration);
console.log("Dimensions:", data.data.width, "x", data.data.height);
console.log("Thumbnail:", data.data.thumbnailImageUrl);
console.log("AI Credits Used:", data.data.aiCreditsUsed);
return data;
}
if (status === "failed") {
throw new Error("Video generation failed: " + JSON.stringify(data));
}
// Wait 15 seconds before polling again
await new Promise(resolve => setTimeout(resolve, 15000));
}
}
// Run the complete workflow
generateVideo()
.then(jobId => waitForVideo(jobId))
.then(result => console.log("\nDone!"))
.catch(error => console.error("Error:", error));
```
```python Python theme={null}
def wait_for_video(job_id):
print("\nPolling for video generation result...")
while True:
response = requests.get(
f"{API_BASE_URL}/v1/jobs/{job_id}",
headers={"Authorization": API_KEY}
)
response.raise_for_status()
data = response.json()
status = data["data"]["status"]
print(f"Status: {status}")
if status == "completed":
print("\nVideo generated successfully!")
print(f"Video URL: {data['data']['url']}")
print(f"Duration: {data['data']['duration']}")
print(f"Dimensions: {data['data']['width']} x {data['data']['height']}")
print(f"Thumbnail: {data['data']['thumbnailImageUrl']}")
print(f"AI Credits Used: {data['data']['aiCreditsUsed']}")
return data
if status == "failed":
raise Exception(f"Video generation failed: {data}")
# Wait 15 seconds before polling again
time.sleep(15)
# Run the complete workflow
if __name__ == "__main__":
job_id = generate_video()
result = wait_for_video(job_id)
print("\nDone!")
```
## Understanding the Parameters
| Parameter | Type | Required | Default | Description |
| ------------- | ------ | -------- | ---------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `prompt` | string | Yes | — | A descriptive text of the video to generate. Must be between 5 and 5,000 characters. |
| `model` | string | No | `pixverse5.5` | The AI model to use for generation. Supported values: `veo3.1`, `veo3.1_fast`, `pixverse5.5`. See [Generate Video API](/api-reference/ai-studio/generate-video) for model capabilities and pricing. |
| `aspectRatio` | string | No | First supported ratio of the selected model | The output aspect ratio. Valid values depend on the model. For example, `pixverse5.5` supports `16:9`, `9:16`, `1:1`, `3:4`, `4:3`, while `veo3.1` supports `16:9`, `9:16`. |
| `duration` | string | No | First supported duration of the selected model | The video length. Valid values depend on the model. For example, `pixverse5.5` supports `5s`, `8s`, `10s`, while `veo3.1` supports `4s`, `6s`, `8s`. |
| `webhook` | string | No | — | A URL to receive a POST notification when the job completes. Must be a valid URI. |
## Tips for Effective Video Prompts
* **Describe motion and action.** Unlike image prompts, video prompts benefit from describing movement. For example, "A bird taking flight from a tree branch" is more effective than "A bird on a tree."
* **Specify the camera angle.** Terms such as "wide shot", "close-up", "tracking shot", or "aerial view" help the model determine the framing and camera movement.
* **Keep the scene focused.** A single clear action with one or two subjects produces better results than a prompt describing multiple simultaneous events.
* **Consider the duration.** Shorter durations (4 to 5 seconds) work well for simple motions, while longer durations (8 to 10 seconds) allow for more complex scenes.
## Next Steps
* [Generate Video from First Frame](/guides/ai-studio/video-from-first-frame) to start a video from a specific image
* [Generate Video from Reference Images](/guides/ai-studio/video-from-reference-images) to guide video generation using reference visuals
* [Extend Video with AI](/guides/ai-studio/extend-video) to continue an existing video with new content
* [Generate Video API Reference](/api-reference/ai-studio/generate-video) for the complete parameter documentation