Text to Video with Background Video Loop and Mute Settings

This example demonstrates how to create a video with custom background video settings, including the ability to mute the background video audio and control whether the video loops. These settings are specific to video backgrounds and are ignored for image or color backgrounds.

Overview

This example covers:

  • Getting an access token
  • Configuring background video settings (mute and loop)
  • Understanding how settings apply only to video backgrounds
  • 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. This allows creators to focus on higher-level strategies and ensures a cohesive brand presence.";

async function createTextToVideoWithBackgroundSettings() {
  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");

    // Step 2: Create Video with Background Video Settings
    console.log("Step 2: Creating video with background video settings...");
    const storyboardResponse = await axios.post(
      `${API_BASE_URL}/v2/video/storyboard/render`,
      {
        videoName: "text_to_video_background_settings",
        scenes: [
          {
            story: STORY_TEXT,
            createSceneOnNewLine: true,
            createSceneOnEndOfSentence: true,
            background: {
              settings: {
                mute: true, // Mute the background video audio
                loop: false, // Do not loop the background video
              },
            },
          },
        ],
      },
      {
        headers: {
          "Content-Type": "application/json",
          Authorization: accessToken,
        },
      }
    );

    const renderJobId = storyboardResponse.data.data.jobId;
    console.log("Storyboard render job created with background video settings");
    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 background settings 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
createTextToVideoWithBackgroundSettings();

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. This allows creators to focus on higher-level strategies and ensures a cohesive brand presence."

def create_text_to_video_with_background_settings():
    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')

        # Step 2: Create Video with Background Video Settings
        print('Step 2: Creating video with background video settings...')
        storyboard_response = requests.post(
            f'{API_BASE_URL}/v2/video/storyboard/render',
            json={
                'videoName': 'text_to_video_background_settings',
                'scenes': [
                    {
                        'story': STORY_TEXT,
                        'createSceneOnNewLine': True,
                        'createSceneOnEndOfSentence': True,
                        'background': {
                            'settings': {
                                'mute': True,  # Mute the background video audio
                                'loop': False  # Do not loop the background video
                            }
                        }
                    }
                ]
            },
            headers={
                'Content-Type': 'application/json',
                'Authorization': access_token
            }
        )
        storyboard_response.raise_for_status()

        render_job_id = storyboard_response.json()['data']['jobId']
        print('Storyboard render job created with background video settings')
        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 background settings 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_background_settings()

Key Parameters

Background Object

  • settings: Configuration object for background video behavior

Background Video Settings

  • mute (optional, boolean):

    • true - Mutes the audio from the background video
    • false - Keeps the audio from the background video (default)
    • Only applies to video backgrounds, ignored for images or colors
  • loop (optional, boolean):

    • true - Loops the background video if the scene duration is longer than the video duration (default)
    • false - Does not loop the background video; the video will play once and will freeze on the last frame
    • Only applies to video backgrounds, ignored for images or colors

Understanding Background Settings

When to Use Settings

Background settings are particularly useful when:

  1. Muting Background Audio:

    • You have a background video with audio that would conflict with voiceover or background music
    • You want to use only the visual elements of the background video
  2. Controlling Loop Behavior:

    • You have a specific background video that should play once without repeating
    • You want to ensure the video doesn't loop when the scene is longer than the video
  3. Combining with Other Features:

    • Use mute: true when you have voiceover or background music enabled
    • Use loop: false for intro/outro videos that should play exactly once

Settings Behavior with Different Background Types

SettingVideo BackgroundImage BackgroundColor Background
mute✅ Applied❌ Ignored❌ Ignored
loop✅ Applied❌ Ignored❌ Ignored

Response

The API returns a job ID for monitoring the video creation progress. Once completed, you'll receive a video URL with your custom background video settings applied.

Notes

  • Replace YOUR_CLIENT_ID and YOUR_CLIENT_SECRET with your actual API credentials
  • The mute and loop settings only apply when background visual is a video
  • If not specified, mute defaults to true and loop defaults to true for a stock library video
  • Settings for images and colors are ignored; they only affect video backgrounds