Skip to main content
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

First Frame Control

Set a specific image as the opening frame of your video

Directed Animation

Describe how the scene should evolve from the starting frame

Video Continuations

Chain videos together using the last frame of a previous generation

Consistent Characters

Maintain visual consistency by starting from a known frame

​
Before You Begin

Make sure you have:
  • A Pictory API key (get one here)
  • Node.js or Python installed on your machine
  • The required packages installed
  • A publicly accessible URL for your first frame image
npm install axios
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. 
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"
};
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. 
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;
  }
}

​
Step 3: Poll for the Result

Check the job status at regular intervals until the video is ready. 
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));

​
Understanding the Parameters

ParameterTypeRequiredDefaultDescription
promptstringYes—A text description of how the video should animate from the first frame. Must be between 5 and 5,000 characters.
firstFrameImageUrlstringNo—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.
modelstringNopixverse5.5The AI model to use for generation. Supported values: veo3.1, veo3.1_fast, pixverse5.5. See Generate Video API for model capabilities and pricing.
aspectRatiostringNoFirst supported ratio of the selected modelThe 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.
durationstringNoFirst supported duration of the selected modelThe video length. Valid values depend on the model. For example, pixverse5.5 supports 5s, 8s, 10s, while veo3.1 supports 4s, 6s, 8s.
webhookstringNo—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