Skip to main content
POST
https://api.pictory.ai
/
pictoryapis
/
v2
/
video
/
storyboard
/
render
Render Storyboard Video
curl --request POST \
  --url https://api.pictory.ai/pictoryapis/v2/video/storyboard/render \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: <content-type>' \
  --data '
{
  "videoName": "<string>",
  "videoWidth": 123,
  "videoHeight": 123,
  "aspectRatio": "<string>",
  "language": "<string>",
  "saveProject": true,
  "webhook": "<string>",
  "templateId": "<string>",
  "variables": {},
  "brandId": "<string>",
  "brandName": "<string>",
  "smartLayoutName": "<string>",
  "smartLayoutId": "<string>",
  "subtitleStyleId": "<string>",
  "subtitleStyleName": "<string>",
  "subtitleStyle": {},
  "awsConnectionId": "<string>",
  "vimeoConnectionId": "<string>",
  "destinations": [
    {}
  ],
  "voiceOver": {},
  "backgroundMusic": {},
  "logo": {},
  "scenes": [
    {}
  ]
}
'
{
  "success": true,
  "data": {
    "jobId": "74c0cc68-e1ed-42f3-a527-8bfc0b46bdb9"
  }
}

Overview

The Render Storyboard Video API generates the final rendered video file from your storyboard configuration. This endpoint processes all scenes, applies voice-over narration, background music, visual effects, and produces a complete video ready for distribution.
This endpoint renders the final video directly. For a preview-first workflow, use the Create Storyboard Preview API to review scenes before rendering.
Direct Render: Use this endpoint when you’re confident in your content and want to skip the preview step, or when re-rendering a previously approved storyboard.

Render Workflow Options

WorkflowAPIWhen to Use
Create PreviewCreate Storyboard PreviewGenerate preview to review scenes before rendering
Render from PreviewRender from PreviewRender preview as-is without modifications
Render with ModificationsRender VideoModify preview elements before rendering
Render Saved ProjectRender ProjectRender existing project created in App or via API
Direct RenderThis APISkip preview, render directly from input

Preview vs. Final Render

AspectStoryboard PreviewFinal Render
PurposeReview and validate contentProduce final video file
OutputScene thumbnails, metadata, project structureFull HD video file
SpeedFastSlower
CostLower resource usageFull rendering resources
EditableYes, make changes before renderVideo is final
Use CaseContent approval, iterationFinal delivery

Use Cases

Direct Video Creation

Generate final videos directly from text, articles, or presentations

Batch Rendering

Render multiple videos programmatically at scale

Automated Pipelines

Integrate into automated content creation workflows

Re-rendering

Re-render videos after making adjustments to projects

Template-based Videos

Generate videos from templates with variable content

Multi-platform Content

Create videos for different platforms with aspect ratios

API Endpoint

POST https://api.pictory.ai/pictoryapis/v2/video/storyboard/render

Request Headers

Authorization
string
required
API key for authentication
Authorization: YOUR_API_KEY
Content-Type
string
required
Must be application/json

Request Body Parameters

The request body accepts the same parameters as the Create Storyboard Preview API. All parameters for video configuration, scenes, voice-over, background music, branding, and destinations are supported.
videoName
string
required
Name for your video project (alphanumeric, spaces, underscores, and hyphens only, max 150 characters)
videoWidth
integer
Width of the generated video in pixels. Must be provided together with videoHeight.
videoHeight
integer
Height of the generated video in pixels. Must be provided together with videoWidth.
aspectRatio
string
Video aspect ratio. Options: 1:1, 16:9, 9:16
language
string
Language of the text content. Options: zh, nl, en, fr, de, it, ja, ko, pt, ru, es, hi
saveProject
boolean
Whether to save the project in your Pictory account for later editing. Default: false
webhook
string
URL where the completed video output will be sent via POST request when finished (max 500 characters)
templateId
string
ID of a template to use. Get from Get Templates API.
variables
object
Key-value object for template variables. Only applicable when templateId is provided.
brandId
string
ID of the brand to apply. Get from Get Video Brands API. Cannot be used with brandName.
brandName
string
Name of the brand to apply. Cannot be used with brandId.
smartLayoutName
string
Name of the smart layout to apply. Get available layouts from Get Smart Layouts API. Cannot be used with smartLayoutId.
smartLayoutId
string
ID of the smart layout to apply. Get from Get Smart Layouts API. Cannot be used with smartLayoutName.
subtitleStyleId
string
ID of a saved text style for subtitles. Get from Get Text Styles API. Cannot be used with subtitleStyleName.
subtitleStyleName
string
Name of a saved text style for subtitles. Cannot be used with subtitleStyleId.
subtitleStyle
object
Inline subtitle style configuration. See Create Storyboard Preview - subtitleStyle Object.
awsConnectionId
string
AWS connection ID for accessing private S3 assets. Get from Get AWS Connections API.
vimeoConnectionId
string
Vimeo connection ID for uploading videos directly to Vimeo. Get from Get Vimeo Connections API.
destinations
array
Array of destination configurations for uploading the generated video (max 5). See Create Storyboard Preview - destinations Array.
voiceOver
object
Voice-over configuration for AI narration. See Create Storyboard Preview - voiceOver Object.
backgroundMusic
object
Background music configuration for the video. See Create Storyboard Preview - backgroundMusic Object.
Logo overlay configuration. See Create Storyboard Preview - logo Object.
scenes
array
required
Array of scene objects containing the content to convert into video. Required unless using templateId. See Create Storyboard Preview - scenes Array.

Response

The API returns a job ID that you can use to track the video rendering progress. Once complete, the job status will include the final video URL.

What the Render Produces

When the render job completes, you’ll receive:
  • Video URL - Direct link to download the rendered video file
  • Video Duration - Total length of the generated video
  • Resolution - Video dimensions based on your configuration
  • Destination Uploads - Confirmation of uploads to configured destinations (Vimeo, S3)
{
  "success": true,
  "data": {
    "jobId": "74c0cc68-e1ed-42f3-a527-8bfc0b46bdb9"
  }
}

Monitoring Render Progress

After receiving the job ID, use the Get Job API to monitor rendering progress:
GET https://api.pictory.ai/pictoryapis/v1/jobs/{jobId}
The job will transition through these statuses:
  • pending - Job is queued
  • in-progress - Video is being rendered
  • completed - Video is ready with videoURL in the response
  • failed - Rendering failed with error details

Code Examples

Replace YOUR_API_KEY with your actual API key

Basic Text to Video Render

curl --request POST \
  --url https://api.pictory.ai/pictoryapis/v2/video/storyboard/render \
  --header 'Authorization: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "videoName": "my_rendered_video",
    "aspectRatio": "16:9",
    "voiceOver": {
      "enabled": true,
      "aiVoices": [{"speaker": "Brian", "speed": 100}]
    },
    "scenes": [
      {
        "story": "Welcome to our company. We create innovative solutions for modern businesses.",
        "createSceneOnEndOfSentence": true
      }
    ]
  }' | python -m json.tool

Render with Full Configuration

const response = await fetch('https://api.pictory.ai/pictoryapis/v2/video/storyboard/render', {
  method: 'POST',
  headers: {
    'Authorization': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    videoName: 'complete_video_render',
    aspectRatio: '16:9',
    saveProject: true,
    webhook: 'https://your-server.com/webhook',

    // Branding
    brandName: 'My Brand',

    // Voice-over
    voiceOver: {
      enabled: true,
      aiVoices: [{
        speaker: 'Emma',
        speed: 100,
        amplificationLevel: 0
      }]
    },

    // Background music
    backgroundMusic: {
      enabled: true,
      autoMusic: true,
      volume: 0.3
    },

    // Logo
    logo: {
      url: 'https://example.com/logo.png',
      position: 'top-right',
      width: '15%'
    },

    // Subtitle styling
    subtitleStyle: {
      fontFamily: 'Montserrat',
      fontSize: 48,
      color: 'rgba(255, 255, 255, 1)',
      position: 'bottom-center'
    },

    // Scenes
    scenes: [{
      story: 'Welcome to our company. We create innovative solutions. Join us on this journey.',
      createSceneOnEndOfSentence: true,
      highlightKeywords: true,
      sceneTransition: 'fade'
    }]
  })
});

const data = await response.json();
console.log('Job ID:', data.data.jobId);

Poll for Completion

async function waitForVideo(jobId, apiKey) {
  const maxAttempts = 60;
  const pollInterval = 10000; // 10 seconds

  for (let attempt = 0; attempt < maxAttempts; attempt++) {
    const response = await fetch(
      `https://api.pictory.ai/pictoryapis/v1/jobs/${jobId}`,
      { headers: { 'Authorization': apiKey } }
    );

    const data = await response.json();
    const status = data.data.status;

    console.log(`Attempt ${attempt + 1}: Status = ${status}`);

    if (status === 'completed') {
      console.log('Video URL:', data.data.videoURL);
      return data.data;
    }

    if (status === 'failed') {
      throw new Error('Video rendering failed: ' + JSON.stringify(data));
    }

    await new Promise(resolve => setTimeout(resolve, pollInterval));
  }

  throw new Error('Timeout waiting for video to render');
}

// Usage
const jobId = 'your-job-id';
const result = await waitForVideo(jobId, 'YOUR_API_KEY');