Skip to main content
POST
https://api.pictory.ai
/
pictoryapis
/
v2
/
projects
/
{projectid}
/
render
Render Project
curl --request POST \
  --url https://api.pictory.ai/pictoryapis/v2/projects/{projectid}/render \
  --header 'Authorization: <authorization>'
{
  "success": true,
  "data": {
    "jobId": "24f6571f-e06c-45d1-a27b-253aab768ba2"
  }
}

​
Overview

Initiate the rendering process for an existing Pictory project to generate the final video output. This endpoint creates a render job that processes your project’s scenes, audio, subtitles, and visual effects into a complete video file. The rendering happens asynchronously, and you can track progress using the job ID returned in the response.
This endpoint renders existing Pictory projects. Projects can be created via the Create Storyboard Preview API with saveProject: true, or directly in the Pictory App.
Automation Workflow: Create or edit projects in the Pictory App, then use this API to trigger rendering programmatically as part of your automation pipeline.

​
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 ProjectThis APIRender existing project created in App or via API
Direct RenderRender Storyboard VideoSkip preview, render directly from input

​
When to Use This Endpoint

App-Created Projects

Render projects created and edited in the Pictory web application

Saved API Projects

Render projects saved via Storyboard API with saveProject: true

Automation Pipelines

Integrate project rendering into automated workflows

Re-rendering

Re-render projects after manual edits in the App

​
API Endpoint

POST https://api.pictory.ai/pictoryapis/v2/projects/{projectid}/render

​
Request Parameters

​
Path Parameters

​
projectid
string
required
The unique identifier of the project to render. Get from Get Projects API.

​
Headers

​
Authorization
string
required
API key for authentication (starts with pictai_)
Authorization: YOUR_API_KEY

​
Response

​
success
boolean
Indicates whether the render job was successfully initiated
​
data
object
Contains information about the render job

​
Response Examples

{
  "success": true,
  "data": {
    "jobId": "24f6571f-e06c-45d1-a27b-253aab768ba2"
  }
}

​
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 that starts with pictai_
curl --request POST \
  --url 'https://api.pictory.ai/pictoryapis/v2/projects/YOUR_PROJECT_ID/render' \
  --header 'Authorization: YOUR_API_KEY' \
  --header 'accept: application/json' | python -m json.tool

​
Usage Notes

Asynchronous Processing: Rendering happens asynchronously. The API returns immediately with a job ID. Use the Get Job API to poll and track rendering progress.
Rendering Time: Rendering time varies based on project complexity, video length, number of scenes, and applied effects. Simple projects may render in minutes, while complex projects can take longer.
Job Status Polling: Poll the Get Job API periodically (recommended: every 5-10 seconds) to determine when the video is ready. The completed job response includes the videoURL.

​
Rendering Behavior

​
What Happens During Rendering

  1. Job Creation: A render job is created and queued in the rendering system
  2. Processing: The system processes all project elements:
    • Compiles all scene visuals (images/videos)
    • Generates and synchronizes voice-over audio
    • Applies text overlays and subtitle formatting
    • Processes transitions and effects
    • Combines all elements into the final video
  3. Encoding: The final video is encoded in the specified format and quality
  4. Completion: The job status changes to complete, and video URLs become available

​
Code Examples: 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 projectId = 'your-project-id';
const response = await fetch(
  `https://api.pictory.ai/pictoryapis/v2/projects/${projectId}/render`,
  {
    method: 'POST',
    headers: { 'Authorization': 'YOUR_API_KEY' }
  }
);
const result = await response.json();
const videoResult = await waitForVideo(result.data.jobId, 'YOUR_API_KEY');

​
Best Practices

​
Polling Strategy

  1. Start Interval: Begin with 10-second intervals for the first minute
  2. Increase Gradually: Increase to 15-30 seconds for longer renders
  3. Maximum Attempts: Set a reasonable timeout (e.g., 20-30 minutes)
  4. Exponential Backoff: Use increasing intervals to reduce API calls

​
Error Handling

  • Retry Logic: Implement automatic retry for transient failures
  • Timeout Handling: Set appropriate timeouts based on project complexity
  • Status Validation: Always check the response status before proceeding
  • Fallback Strategy: Have a plan for handling permanent failures

Get Job Status

Monitor rendering progress

Get Projects

List projects to get project IDs

Get Project By Id

Get project details and video URL

Create Storyboard Preview

Create new video projects via API