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 axiosComplete 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 requestsComplete 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- Chinesenl- Dutchen- Englishfr- Frenchde- Germanit- Italianja- Japaneseko- Koreanpt- Portugueseru- Russianes- Spanishhi- Hindi
Important Notes
-
Story vs Caption:
- The
storyfield is used by the AI to understand content and select appropriate visuals - The
captionfield is what appears as subtitles in the final video - This allows you to create videos in one language while displaying subtitles in another
- The
-
Scene Creation Limitations:
- When using
caption, you cannot usecreateSceneOnNewLineorcreateSceneOnEndOfSentence - You must manually create scenes if you want to use captions
- When using
-
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_IDandYOUR_CLIENT_SECRETwith your actual API credentials - The caption feature requires a story to be present
- Caption language helps with proper text rendering and formatting
Updated 12 days ago
