Text to Video with Intro Image and Outro Video

Overview

This example covers:

Getting an access token
Adding an intro scene with static image background
Adding an outro scene with video background
Setting minimum durations for intro/outro scenes
Understanding background-only scenes
Monitoring job status and retrieving the final video

Node.js Example

Prerequisites

npm install axios

Complete Code

import axios from "axios";

const API_BASE_URL = "https://api.pictory.ai/pictoryapis";
const CLIENT_ID = "YOUR_CLIENT_ID";
const CLIENT_SECRET = "YOUR_CLIENT_SECRET";

const STORY_TEXT =
  "AI is poised to significantly impact educators and course creators on social media. By automating tasks like content generation, visual design, and video editing, AI will save time and enhance consistency.";
const INTRO_IMAGE_URL = "https://pictory-static.pictorycontent.com/Backgorund2X.png";
const OUTRO_VIDEO_URL = "https://pictory-static.pictorycontent.com/brand/outro.mp4";

async function createTextToVideoWithIntroOutro() {
  try {
    // Step 1: Get Access Token
    console.log("Step 1: Getting access token...");
    const tokenResponse = await axios.post(
      `${API_BASE_URL}/v1/oauth2/token`,
      {
        client_id: CLIENT_ID,
        client_secret: CLIENT_SECRET,
      },
      {
        headers: {
          "Content-Type": "application/json",
        },
      }
    );

    const accessToken = tokenResponse.data.access_token;
    console.log("Access token obtained successfully");
    console.log("Token expires in:", tokenResponse.data.expires_in, "seconds\n");

    // Step 2: Create Video with Intro Image and Outro Video
    console.log("Step 2: Creating video with intro and outro...");
    const storyboardResponse = await axios.post(
      `${API_BASE_URL}/v2/video/storyboard/render`,
      {
        videoName: "text_to_video_intro_outro",
        scenes: [
          // Intro scene with image background
          {
            background: {
              type: "image",
              visualUrl: INTRO_IMAGE_URL,
            },
            minimumDuration: 5, // 5 seconds intro
          },
          // Main content scene
          {
            story: STORY_TEXT,
            createSceneOnNewLine: true,
            createSceneOnEndOfSentence: true,
          },
          // Outro scene with video background
          {
            background: {
              type: "video",
              visualUrl: OUTRO_VIDEO_URL,
            },
            minimumDuration: 5, // 5 seconds outro
          },
        ],
      },
      {
        headers: {
          "Content-Type": "application/json",
          Authorization: accessToken,
        },
      }
    );

    const renderJobId = storyboardResponse.data.data.jobId;
    console.log("Video with intro and outro render job created");
    console.log("Job ID:", renderJobId, "\n");

    // Step 3: Monitor Job Status
    console.log("Step 3: Monitoring job status...");
    let jobCompleted = false;
    let jobResult = null;

    while (!jobCompleted) {
      const jobStatusResponse = await axios.get(`${API_BASE_URL}/v1/jobs/${renderJobId}`, {
        headers: {
          Authorization: accessToken,
        },
      });

      const status = jobStatusResponse.data.data.status;
      console.log("Current status:", status);

      if (status === "completed") {
        jobCompleted = true;
        jobResult = jobStatusResponse.data;
        console.log("\nVideo with intro and outro created successfully!");
        console.log("Video URL:", jobResult.data.videoURL);
      } else if (status === "failed") {
        throw new Error("Job failed: " + JSON.stringify(jobStatusResponse.data));
      } else {
        // Wait 5 seconds before checking again
        await new Promise(resolve => setTimeout(resolve, 5000));
      }
    }

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

// Run the function
createTextToVideoWithIntroOutro();

Python Example

Prerequisites

pip install requests

Complete Code

import requests
import time
import json

API_BASE_URL = 'https://api.pictory.ai/pictoryapis'
CLIENT_ID = 'YOUR_CLIENT_ID'
CLIENT_SECRET = 'YOUR_CLIENT_SECRET'

STORY_TEXT = "AI is poised to significantly impact educators and course creators on social media. By automating tasks like content generation, visual design, and video editing, AI will save time and enhance consistency."
INTRO_IMAGE_URL = "https://pictory-static.pictorycontent.com/Backgorund2X.png"
OUTRO_VIDEO_URL = "https://pictory-static.pictorycontent.com/brand/outro.mp4"

def create_text_to_video_with_intro_outro():
    try:
        # Step 1: Get Access Token
        print('Step 1: Getting access token...')
        token_response = requests.post(
            f'{API_BASE_URL}/v1/oauth2/token',
            json={
                'client_id': CLIENT_ID,
                'client_secret': CLIENT_SECRET
            },
            headers={
                'Content-Type': 'application/json'
            }
        )
        token_response.raise_for_status()

        access_token = token_response.json()['access_token']
        print('Access token obtained successfully')
        print(f"Token expires in: {token_response.json()['expires_in']} seconds\n")

        # Step 2: Create Video with Intro Image and Outro Video
        print('Step 2: Creating video with intro and outro...')
        storyboard_response = requests.post(
            f'{API_BASE_URL}/v2/video/storyboard/render',
            json={
                'videoName': 'text_to_video_intro_outro',
                'scenes': [
                    # Intro scene with image background
                    {
                        'background': {
                            'type': 'image',
                            'visualUrl': INTRO_IMAGE_URL
                        },
                        'minimumDuration': 5  # 5 seconds intro
                    },
                    # Main content scene
                    {
                        'story': STORY_TEXT,
                        'createSceneOnNewLine': True,
                        'createSceneOnEndOfSentence': True
                    },
                    # Outro scene with video background
                    {
                        'background': {
                            'type': 'video',
                            'visualUrl': OUTRO_VIDEO_URL
                        },
                        'minimumDuration': 5  # 5 seconds outro
                    }
                ]
            },
            headers={
                'Content-Type': 'application/json',
                'Authorization': access_token
            }
        )
        storyboard_response.raise_for_status()

        render_job_id = storyboard_response.json()['data']['jobId']
        print('Video with intro and outro render job created')
        print(f'Job ID: {render_job_id}\n')

        # Step 3: Monitor Job Status
        print('Step 3: Monitoring job status...')
        job_completed = False
        job_result = None

        while not job_completed:
            job_status_response = requests.get(
                f'{API_BASE_URL}/v1/jobs/{render_job_id}',
                headers={
                    'Authorization': access_token
                }
            )
            job_status_response.raise_for_status()

            status = job_status_response.json()['data']['status']
            print(f'Current status: {status}')

            if status == 'completed':
                job_completed = True
                job_result = job_status_response.json()
                print('\nVideo with intro and outro created successfully!')
                print(f"Video URL: {job_result['data']['videoURL']}")
            elif status == 'failed':
                raise Exception(f"Job failed: {json.dumps(job_status_response.json())}")
            else:
                # Wait 5 seconds before checking again
                time.sleep(5)

        return job_result

    except requests.exceptions.RequestException as error:
        print(f'Error: {error}')
        if hasattr(error, 'response') and error.response is not None:
            print(f'Response: {error.response.text}')
        raise

# Run the function
if __name__ == '__main__':
    create_text_to_video_with_intro_outro()

Key Parameters

Background Object

background.type: Type of background
- "image" - For static image backgrounds (intros)
- "video" - For video backgrounds (outros)
background.visualUrl: URL to the background image or video file

Minimum Duration

minimumDuration: Duration in seconds for background-only scenes
- Required for scenes with only background and no story content
- Ensures intro/outro scenes play for a specific time

Scene Structure

Background-Only Scene (Intro/Outro)

A scene with only a background (no story text) requires:

A background object with type and visualUrl
A minimumDuration to specify how long the scene should display

Regular Content Scene

A scene with story text:

Has a story field with text content
Duration is calculated based on text length and voice-over
Can optionally have a background as well

Use Cases

Intro Scenes

Company logo display
Channel branding
Title cards
Episode numbers
Series branding

Outro Scenes

Subscribe/follow calls-to-action
Social media links
Next episode teasers
Credits
Thank you messages

Advanced Examples

Intro with Text Overlay

{
  background: {
    type: "image",
    visualUrl: "https://example.com/intro.png"
  },
  story: "Welcome to our channel",
  minimumDuration: 5
}

Multiple Outros

scenes: [
  { story: "Main content..." },
  {
    background: {
      type: "video",
      visualUrl: "https://example.com/cta.mp4",
    },
    minimumDuration: 5,
  },
  {
    background: {
      type: "image",
      visualUrl: "https://example.com/thankyou.png",
    },
    minimumDuration: 3,
  },
];

Video Background Settings

You can also control video background behavior:

background: {
  type: "video",
  visualUrl: OUTRO_VIDEO_URL,
  settings: {
    mute: true,   // Mute the outro video audio
    loop: false   // Don't loop the video
  }
}

Best Practices

Intro Duration: Keep intros short (3-5 seconds) to maintain viewer engagement
Outro Duration: Outros can be longer (5-10 seconds) for calls-to-action
Image Format: Use high-resolution images (1920x1080 or higher)
Video Format: Use MP4 format for best compatibility
Branding: Use consistent intro/outro across your video series

Common Intro/Outro Durations

Quick Intro: 2-3 seconds
Standard Intro: 4-5 seconds
Detailed Intro: 6-8 seconds
Short Outro: 3-5 seconds
Standard Outro: 5-8 seconds
Long Outro: 10-15 seconds

Response

The API returns a job ID for monitoring the video creation progress. Once completed, you'll receive a video URL with intro and outro scenes included.

Notes

Replace YOUR_CLIENT_ID and YOUR_CLIENT_SECRET with your actual API credentials
Image and video files must be accessible via public URLs
Minimum duration ensures scenes play for at least the specified time
You can add background music to intro/outro scenes
You can add voice-over to intro/outro scenes by including a story field