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

Text to Video

Generate videos from descriptive text prompts

Model Selection

Choose from multiple AI video models

Duration Control

Set the video length based on your needs

Aspect Ratio

Generate landscape, portrait, or square videos

​
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
npm install axios

​
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. 
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"
};

​
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. 
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;
  }
}

​
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. 
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));

​
Understanding the Parameters

ParameterTypeRequiredDefaultDescription
promptstringYes—A descriptive text of the video to generate. Must be between 5 and 5,000 characters.
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.

​
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