Skip to main content
This guide shows you how to turn written text into an engaging video with automatically selected visuals. Perfect for creating social media content, educational videos, or marketing materials from your written content.

What You’ll Learn

Text to Video

Transform written content into engaging videos

Auto Visuals

AI selects visuals based on your text content

Scene Control

Control how text is split into scenes

Job Monitoring

Track video creation progress in real-time

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

First, prepare your API credentials and the text you want to convert:
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

// Your text content - this will be converted into video
const SAMPLE_TEXT =
  "AI is transforming how we create content. By automating video production, " +
  "creators can focus on strategy while AI handles the technical work. " +
  "This means faster turnaround times and consistent quality across all videos.";

Step 2: Create the Video

Send your text to the API to start the video creation process:
async function createTextToVideo() {
  try {
    console.log("Creating video from text...");

    const response = await axios.post(
      `${API_BASE_URL}/v2/video/storyboard/render`,
      {
        videoName: "my_first_text_video",
        scenes: [
          {
            story: SAMPLE_TEXT,
            createSceneOnNewLine: true,
            createSceneOnEndOfSentence: true,
          },
        ],
      },
      {
        headers: {
          "Content-Type": "application/json",
          Authorization: API_KEY,
        },
      }
    );

    const jobId = response.data.data.jobId;
    console.log("✓ Video creation started!");
    console.log("Job ID:", jobId);

    return jobId;
  } catch (error) {
    console.error("Error creating video:", error.response?.data || error.message);
    throw error;
  }
}

Step 3: Monitor Progress

Check the status of your video until it’s ready:
async function waitForVideo(jobId) {
  console.log("\nMonitoring video creation...");

  while (true) {
    const statusResponse = await axios.get(
      `${API_BASE_URL}/v1/jobs/${jobId}`,
      {
        headers: { Authorization: API_KEY },
      }
    );

    const status = statusResponse.data.data.status;
    console.log("Status:", status);

    if (status === "completed") {
      console.log("\n✓ Video is ready!");
      console.log("Video URL:", statusResponse.data.data.videoURL);
      return statusResponse.data;
    } else if (status === "failed") {
      throw new Error("Video creation failed: " + JSON.stringify(statusResponse.data));
    }

    // Wait 5 seconds before checking again
    await new Promise(resolve => setTimeout(resolve, 5000));
  }
}

// Run the complete workflow
createTextToVideo()
  .then(jobId => waitForVideo(jobId))
  .then(result => console.log("\nDone!"))
  .catch(error => console.error("Error:", error));

Understanding the Parameters

Required Parameters

ParameterTypeDescription
videoNamestringA unique name for your video project (used for organization)
scenesarrayList of scenes to include in your video (minimum 1 scene)
scenes[].storystringThe text content that will be converted to video

Scene Control Options

ParameterTypeDefaultDescription
createSceneOnNewLinebooleanfalseCreates a new scene at each line break in your text
createSceneOnEndOfSentencebooleanfalseCreates a new scene at the end of each sentence
Scene Creation Best Practices:
  • For short, punchy videos (like social media): Set both createSceneOnNewLine and createSceneOnEndOfSentence to true
  • For longer, narrative videos: Set both to false to keep related content together
  • For paragraph-based content: Set createSceneOnNewLine to true only

How Scene Creation Works

The AI automatically determines scene breaks based on your settings:
{
  createSceneOnNewLine: true,
  createSceneOnEndOfSentence: true
}
Result: Maximum scene breaks - new scene for each sentence AND paragraph Best for: Short-form content, social media clips, dynamic videos

Only Sentence Breaks

{
  createSceneOnNewLine: false,
  createSceneOnEndOfSentence: true
}
Result: New scene at each sentence, paragraphs stay together Best for: Educational content, explainer videos

Only Line Breaks

{
  createSceneOnNewLine: true,
  createSceneOnEndOfSentence: false
}
Result: New scene at each paragraph/line break Best for: Article-to-video, blog content

No Automatic Breaks

{
  createSceneOnNewLine: false,
  createSceneOnEndOfSentence: false
}
Result: All text stays in one scene Best for: Short quotes, single-thought videos

What Happens Behind the Scenes

When you submit your text, Pictory’s AI:
  1. Analyzes Your Text - Understands the context and key concepts
  2. Breaks Into Scenes - Splits text based on your scene settings
  3. Selects Visuals - Automatically chooses relevant stock images/videos for each scene
  4. Generates Captions - Creates animated text overlays synchronized with the content
  5. Renders Video - Compiles everything into a polished video file
Processing Time: Videos typically take 3-10 minutes to create, depending on length. The API processes asynchronously, so you’ll receive a job ID immediately and can check status periodically.

Understanding the Response

Initial Response (Job Created)

{
  "success": true,
  "data": {
    "jobId": "abc123def456",
    "status": "in-progress"
  }
}

Completed Response

{
  "success": true,
  "data": {
    "jobId": "abc123def456",
    "status": "completed",
    "videoURL": "https://cdn.pictory.ai/videos/your-video.mp4",
    "duration": 45.5,
    "scenes": 5
  }
}

Common Use Cases

Marketing Content

const marketingText =
  "Introducing our new product! " +
  "50% faster than competitors. " +
  "Available now for $99.";

Educational Videos

const lessonText =
  "Today we'll learn about photosynthesis. " +
  "Plants convert sunlight into energy. " +
  "This process produces oxygen for us to breathe.";

Social Media Posts

const socialText =
  "5 tips for better productivity:\n" +
  "1. Start with your hardest task\n" +
  "2. Take regular breaks\n" +
  "3. Minimize distractions";

Troubleshooting Common Issues

Problem: Your API key is incorrect or expired.Solution:
  1. Check that your API key starts with pictai_
  2. Verify your subscription is active at API Access page
  3. Make sure you’re passing it in the Authorization header
Problem: The job may have encountered an issue.Solution:
  1. Check the job status one more time
  2. Verify your text content isn’t excessively long (keep under 5,000 characters for best results)
  3. Contact support with your job ID if it’s been over an hour
Problem: The story field is empty or missing.Solution: Ensure each scene has a story field with actual text content:
scenes: [{
  story: "Your text here",  // Must not be empty
  createSceneOnNewLine: true
}]
Problem: Scene creation settings don’t match your expectations.Solution:
  • Review the scene control options above
  • Test with both createSceneOnNewLine and createSceneOnEndOfSentence set to true for maximum control
  • Use manual line breaks (\n) in your text where you want scene breaks

Next Steps

Now that you know the basics, enhance your videos with these features:

API Reference

For complete technical details, see: