> ## 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 First Frame
> Create AI-generated videos starting from a specific image as the opening frame
This guide shows you how to generate an AI video that begins from a specific image. By providing a first frame image along with a text prompt, you can control the visual starting point of the video while letting the AI model animate the scene based on your description.
## What You Will Build
Set a specific image as the opening frame of your video
Describe how the scene should evolve from the starting frame
Chain videos together using the last frame of a previous generation
Maintain visual consistency by starting from a known frame
## 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
* A publicly accessible URL for your first frame image
```bash npm theme={null}
npm install axios
```
```bash pip theme={null}
pip install requests
```
You can use the `lastFrameImageUrl` from a completed video generation job as the `firstFrameImageUrl` for the next request. This technique allows you to create seamless multi-segment videos.
## Step-by-Step Guide
### Step 1: Set Up Your Request
Prepare your API credentials, the first frame image URL, and a prompt that describes how the video should proceed from that frame.
```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 from first frame
const videoRequest = {
prompt: "The woman in the frame stands up and walks towards the large window overlooking the city skyline in a wide shot",
firstFrameImageUrl: "https://example.com/images/woman-seated-living-room.png",
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 from first frame
video_request = {
"prompt": "The woman in the frame stands up and walks towards the large window overlooking the city skyline in a wide shot",
"firstFrameImageUrl": "https://example.com/images/woman-seated-living-room.png",
"model": "pixverse5.5",
"aspectRatio": "9:16",
"duration": "8s"
}
```
The `firstFrameImageUrl` must point to a publicly accessible image. This parameter cannot be used together with `extendVideoUrl` or `referenceImageUrls`.
### Step 2: Submit the Video Generation Request
Send the request to the AI Studio video generation endpoint.
```javascript Node.js theme={null}
async function generateVideoFromFrame() {
try {
console.log("Submitting first-frame 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_from_frame():
try:
print("Submitting first-frame 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.
```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("Last Frame URL:", data.data.lastFrameImageUrl);
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
generateVideoFromFrame()
.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"Last Frame URL: {data['data']['lastFrameImageUrl']}")
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_from_frame()
result = wait_for_video(job_id)
print("\nDone!")
```
## Understanding the Parameters
| Parameter | Type | Required | Default | Description |
| -------------------- | ------ | -------- | ---------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `prompt` | string | Yes | — | A text description of how the video should animate from the first frame. Must be between 5 and 5,000 characters. |
| `firstFrameImageUrl` | string | No | — | A publicly accessible URL of the image to use as the opening frame. Must be a valid URI. Cannot be used together with `extendVideoUrl` or `referenceImageUrls`. |
| `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. |
## Chaining Videos with Last Frame
The completed video response includes a `lastFrameImageUrl` field. You can use this URL as the `firstFrameImageUrl` in a new request to create a seamless continuation. This technique is useful for building longer narratives across multiple video segments.
**Example workflow:**
1. Generate the first video with a text prompt.
2. Retrieve the `lastFrameImageUrl` from the completed job.
3. Use that URL as the `firstFrameImageUrl` for the next video, with a new prompt describing the next action.
4. Repeat to build a multi-segment video sequence.
## Tips for First Frame Videos
* **Reference the frame content.** Describe actions relative to what is visible in the image. For example, "The person in the frame begins to walk" is more effective than a prompt that ignores the image content.
* **Describe motion direction.** Specify where subjects should move. For example, "walks towards the window" or "turns to face the camera."
* **Match the aspect ratio.** Use the same aspect ratio as your source image for the best visual continuity.
* **Use for scene transitions.** Generate an image with the AI Studio image endpoint, then animate it with this approach for full creative control over the opening frame.
## Next Steps
* [Generate Video from Text Prompt](/guides/ai-studio/text-to-video) to create videos without a starting frame
* [Generate Video from Reference Images](/guides/ai-studio/video-from-reference-images) to guide generation using multiple reference visuals
* [Extend Video with AI](/guides/ai-studio/extend-video) to continue an existing video
* [Generate Video API Reference](/api-reference/ai-studio/generate-video) for the complete parameter documentation