Skip to main content
PUT
https://api.pictory.ai
/
pictoryapis
/
v2
/
video
/
render
/
{storyboardjobid}
Render Video from Preview
curl --request PUT \
  --url https://api.pictory.ai/pictoryapis/v2/video/render/{storyboardjobid} \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: <content-type>' \
  --data '
{
  "webhook": "<string>"
}
'
{
  "success": true,
  "data": {
    "jobId": "84d1dd79-f2fe-53g4-b638-9cgd1c57ceb0"
  }
}

Overview

The Render from Preview API generates the final video file from an existing storyboard preview. This endpoint is part of the recommended two-step workflow: first create a preview to review and validate content, then render the final video once approved.
This endpoint requires a completed storyboard preview job ID. First use the Create Storyboard Preview API to generate a preview, then use this endpoint to render the final video.
Recommended Workflow: Create Preview → Review Scenes → Make Adjustments (optional) → Render Final Video

Render Workflow Options

WorkflowAPIWhen to Use
Create PreviewCreate Storyboard PreviewGenerate preview to review scenes before rendering
Render from PreviewThis APIRender 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 RenderRender Storyboard VideoSkip preview, render directly from input

Benefits of Two-Step Workflow

Content Validation

Review scenes, visuals, and timing before committing to render

Cost Optimization

Only render videos that have been reviewed and approved

Iterative Refinement

Make adjustments to the preview before final render

Quality Assurance

Ensure content meets requirements before production

API Endpoint

PUT https://api.pictory.ai/pictoryapis/v2/video/render/{storyboardjobid}

Request Parameters

Path Parameters

storyboardjobid
string
required
The job ID returned from a completed Create Storyboard Preview request. This ID identifies the storyboard configuration to render.

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 allows you to override or add settings from the original storyboard preview. All parameters are optional - if not provided, the original preview settings are used.
webhook
string
URL where the completed video output will be sent via POST request when finished (max 500 characters). Overrides the webhook from the preview.

Response

The API returns a job ID that you can use to track the video rendering progress.
{
  "success": true,
  "data": {
    "jobId": "84d1dd79-f2fe-53g4-b638-9cgd1c57ceb0"
  }
}

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 and STORYBOARD_JOB_ID with the job ID from your preview request.

Basic Render from Preview

curl --request PUT \
  --url https://api.pictory.ai/pictoryapis/v2/video/render/74c0cc68-e1ed-42f3-a527-8bfc0b46bdb9 \
  --header 'Authorization: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{}' | python -m json.tool

Render with Webhook Notification

const storyboardJobId = '74c0cc68-e1ed-42f3-a527-8bfc0b46bdb9';

const response = await fetch(
  `https://api.pictory.ai/pictoryapis/v2/video/render/${storyboardJobId}`,
  {
    method: 'PUT',
    headers: {
      'Authorization': 'YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      webhook: 'https://your-server.com/video-complete'
    })
  }
);

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

Complete Two-Step Workflow

const API_KEY = 'YOUR_API_KEY';
const API_BASE = 'https://api.pictory.ai/pictoryapis';

// Step 1: Create storyboard preview
async function createPreview() {
  const response = await fetch(`${API_BASE}/v2/video/storyboard`, {
    method: 'POST',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      videoName: 'my_video',
      voiceOver: {
        enabled: true,
        aiVoices: [{ speaker: 'Brian', speed: 100 }]
      },
      scenes: [{
        story: 'Welcome to our product demo. We will show you amazing features.',
        createSceneOnEndOfSentence: true
      }]
    })
  });

  const data = await response.json();
  return data.data.jobId;
}

// Step 2: Wait for preview to complete
async function waitForJob(jobId) {
  while (true) {
    const response = await fetch(`${API_BASE}/v1/jobs/${jobId}`, {
      headers: { 'Authorization': API_KEY }
    });

    const data = await response.json();

    if (data.data.status === 'completed') {
      console.log('Preview ready!');
      return data.data;
    }

    if (data.data.status === 'failed') {
      throw new Error('Job failed');
    }

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

// Step 3: Render final video from preview
async function renderFromPreview(storyboardJobId) {
  const response = await fetch(`${API_BASE}/v2/video/render/${storyboardJobId}`, {
    method: 'PUT',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      webhook: 'https://your-server.com/video-complete'
    })
  });

  const data = await response.json();
  return data.data.jobId;
}

// Execute workflow
async function main() {
  // Create preview
  const previewJobId = await createPreview();
  console.log('Preview Job ID:', previewJobId);

  // Wait for preview
  await waitForJob(previewJobId);

  // Render final video
  const renderJobId = await renderFromPreview(previewJobId);
  console.log('Render Job ID:', renderJobId);

  // Wait for render
  const result = await waitForJob(renderJobId);
  console.log('Video URL:', result.videoURL);
}

main();

Error Handling

{
  "success": false,
  "error": {
    "code": "INVALID_REQUEST",
    "message": "Invalid storyboard job ID format"
  }
}
Solution: Ensure you’re using the correct job ID format (UUID) from a storyboard preview request.
{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Storyboard job not found"
  }
}
Solution: Verify the storyboard job ID exists and belongs to your account. The preview job must be completed before rendering.
{
  "success": false,
  "error": {
    "message": "Storyboard preview is not yet completed"
  }
}
Solution: Wait for the storyboard preview job to complete before calling this endpoint. Use the Get Job API to check status.
{
  "message": "Unauthorized"
}
Solution: Check your API key is valid and correctly formatted in the Authorization header.