Text to Video with Caption and Caption Language

This example demonstrates how to create a video with custom captions in a specific language. The caption allows you to provide alternative or translated text that will be displayed in the video, different from the original story text used for generating visuals.

Overview

This example covers:

  • Getting an access token
  • Creating a video with a story text for visuals
  • Adding a custom caption in a specific language
  • Understanding the difference between story and caption
  • 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";

// Story text used for generating visuals and AI understanding
const STORY_TEXT = "AI is poised to significantly impact educators and course creators on social media.";

// Caption text that will be displayed in the video
const CAPTION_TEXT =
  "La IA está destinada a impactar significativamente a los educadores y creadores de cursos en las redes sociales.";

async function createTextToVideoWithCaption() {
  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 Storyboard with Caption
    console.log("Step 2: Creating video storyboard with custom caption...");
    const storyboardResponse = await axios.post(
      `${API_BASE_URL}/v2/video/storyboard/render`,
      {
        videoName: "text_to_video_with_caption",
        scenes: [
          {
            story: STORY_TEXT,
            caption: CAPTION_TEXT,
            captionLanguage: "es",
            // Note: createSceneOnNewLine and createSceneOnEndOfSentence
            // cannot be used when caption is provided
            createSceneOnNewLine: false,
            createSceneOnEndOfSentence: false,
          },
        ],
      },
      {
        headers: {
          "Content-Type": "application/json",
          Authorization: accessToken,
        },
      }
    );

    const renderJobId = storyboardResponse.data.data.jobId;
    console.log("Storyboard render job created with custom caption");
    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 custom caption 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
createTextToVideoWithCaption();

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 used for generating visuals and AI understanding
STORY_TEXT = "AI is poised to significantly impact educators and course creators on social media."

# Caption text that will be displayed in the video
CAPTION_TEXT = "La IA está destinada a impactar significativamente a los educadores y creadores de cursos en las redes sociales."

def create_text_to_video_with_caption():
    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 Storyboard with Caption
        print('Step 2: Creating video storyboard with custom caption...')
        storyboard_response = requests.post(
            f'{API_BASE_URL}/v2/video/storyboard/render',
            json={
                'videoName': 'text_to_video_with_caption',
                'scenes': [
                    {
                        'story': STORY_TEXT,
                        'caption': CAPTION_TEXT,
                        'captionLanguage': 'es',
                        # Note: createSceneOnNewLine and createSceneOnEndOfSentence
                        # cannot be used when caption is provided
                        'createSceneOnNewLine': False,
                        'createSceneOnEndOfSentence': False
                    }
                ]
            },
            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 custom caption')
        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 custom caption 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_caption()

Key Parameters

  • story: The main text used for generating visuals and AI content understanding
  • caption: The text that will be displayed as subtitles in the video
  • captionLanguage: The language code for the caption (e.g., "es" for Spanish, "fr" for French, "de" for German)

Supported Caption Languages

  • zh - Chinese
  • nl - Dutch
  • en - English
  • fr - French
  • de - German
  • it - Italian
  • ja - Japanese
  • ko - Korean
  • pt - Portuguese
  • ru - Russian
  • es - Spanish
  • hi - Hindi

Important Notes

  1. Story vs Caption:

    • The story field is used by the AI to understand content and select appropriate visuals
    • The caption field is what appears as subtitles in the final video
    • This allows you to create videos in one language while displaying subtitles in another
  2. Scene Creation Limitations:

    • When using caption, you cannot use createSceneOnNewLine or createSceneOnEndOfSentence
    • You must manually create scenes if you want to use captions
  3. Use Cases:

    • Creating multilingual videos
    • Providing translations
    • Customizing displayed text while maintaining visual coherence

Response

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

Notes

  • Replace YOUR_CLIENT_ID and YOUR_CLIENT_SECRET with your actual API credentials
  • The caption feature requires a story to be present
  • Caption language helps with proper text rendering and formatting