Get Project by ID

curl --request GET \
  --url https://api.pictory.ai/pictoryapis/v2/projects/{projectid} \
  --header 'Authorization: <authorization>'

import requests

url = "https://api.pictory.ai/pictoryapis/v2/projects/{projectid}"

headers = {"Authorization": "<authorization>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {Authorization: '<authorization>'}};

fetch('https://api.pictory.ai/pictoryapis/v2/projects/{projectid}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.pictory.ai/pictoryapis/v2/projects/{projectid}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: <authorization>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.pictory.ai/pictoryapis/v2/projects/{projectid}"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "<authorization>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.pictory.ai/pictoryapis/v2/projects/{projectid}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = '<authorization>'

response = http.request(request)
puts response.read_body

{
  "project_id": "202601180951110906f5645f5952e4211bee28ac6100ddd68",
  "projectName": "AI Video Creation Guide",
  "projectType": "1",
  "source": "script",
  "step": "STORYBOARD",
  "schemaVersion": "v3",
  "layout": "16:9",
  "scriptLanguage": "en",
  "thumbnail": "https://cdn.example.com/thumbnail.jpg",
  "videoURL": "https://cdn.example.com/video/AI_Video_Creation_Guide.mp4",
  "audioURL": "https://cdn.example.com/audio/AI_Video_Creation_Guide.mp3",
  "shareVideoURL": "https://video.pictory.ai/project-id/share-id",
  "srtFile": "https://cdn.example.com/subtitles/subtitles.srt",
  "vttFile": "https://cdn.example.com/subtitles/subtitles.vtt",
  "txtFile": "https://cdn.example.com/subtitles/subtitles.txt",
  "videoDuration": 21.98,
  "audioSpeed": 100,
  "videoVolume": 50,
  "voiceOverId": "20260119024822426ae1e237bfddc4598b72be30c0c93ec33",
  "smartTemplateId": "20250813042630669e658e159aa60455692c1dad5473adtd3",
  "brandId": "",
  "saveDate": "2026-01-19T09:23:21.131Z",
  "generatedDate": "2026-01-19T09:26:23.059Z",
  "scriptTxtSceneSettings": {
    "autoVisualSelection": true,
    "selectedValueSceneBreakChar": "Both",
    "autoHighlightKeywords": true,
    "maxLines": 2
  },
  "visualFilter": {
    "libraries": [],
    "styles": [],
    "categories": []
  },
  "scenes": [
    {
      "sceneId": "2026011809570315812dcab8bad504b84a76171a1dd620cc5",
      "projectId": "202601180951110906f5645f5952e4211bee28ac6100ddd68",
      "text": "Create Amazing AI Videos",
      "sentence": [
        { "text": "Create " },
        { "highlight": true, "text": "Amazing AI Videos" }
      ],
      "keywords": ["Amazing AI Videos"],
      "category": "TITLE",
      "sortOrder": 10001,
      "durationAuto": 5,
      "layoutId": "20250901134117bbb9d28f462ef350f3",
      "settings": {
        "hideText": true
      },
      "styleData": {
        "fontName": "Plus Jakarta Sans",
        "fontDisplayName": "Plus Jakarta Sans",
        "fontSize": "24",
        "fontColor": "rgb(255,255,255)",
        "textAlign": "center",
        "keywordColor": "rgb(245,240,162)",
        "textBackgroundColor": "rgba(0,0,0,0.35)",
        "textShadowColor": "rgba(0,0,0,1)",
        "textShadowWidthFr": 0.03,
        "maxLines": 2,
        "width": 0.7,
        "preset": "bottom-center"
      },
      "background": {
        "type": "image",
        "elementData": {
          "url": "https://images.example.com/photo.jpg",
          "preview_jpg": "https://images.example.com/photo.jpg",
          "thumb": "https://images.example.com/photo-thumb.jpg",
          "thumb_jpg": "https://images.example.com/photo-thumb.jpg",
          "library": "unsplash",
          "libraryItemId": "mR1CIDduGLc",
          "duration": 0
        },
        "styleData": {
          "kenBurns": "kb-364683-oqt0",
          "imageZoomPan": true,
          "width": 0.7,
          "aspectRatio": 1.78,
          "preset": "center-center",
          "colorOverlay": {
            "hide": false,
            "bgColor": "rgb(0,37,60)",
            "opacity": 0.5
          }
        },
        "settings": {}
      },
      "elements": [
        {
          "elementId": "2026011815294013646c92e549f6646c49f31274227faf54d",
          "type": "video",
          "isLogo": false,
          "hide": false,
          "elementData": {
            "url": "https://videos.example.com/clip.mp4",
            "preview_jpg": "https://videos.example.com/clip-preview.jpg",
            "thumb": "https://videos.example.com/clip-thumb.mp4",
            "thumb_jpg": "https://videos.example.com/clip-thumb.jpg",
            "library": "story_blocks",
            "libraryItemId": "0",
            "duration": 16
          },
          "settings": {
            "loopVideo": true,
            "muteClipAudio": true
          },
          "styleData": {
            "top": 4.89,
            "left": 3.96,
            "width": 0.9259,
            "aspectRatio": 1.8066,
            "preset": null,
            "height": null,
            "sourceDimensions": {
              "width": 0.9512,
              "aspectRatio": 1.7778,
              "relYPercent": -0.0273,
              "relXPercent": -0.0127
            },
            "colorOverlay": {
              "hide": false,
              "bgColor": "rgb(110,111,132)",
              "opacity": 0.3
            }
          }
        },
        {
          "elementId": "202601180957034073d8a97be18614182b23c87f8c7fb2382",
          "type": "text",
          "componentName": "main_title",
          "elementData": {
            "sentence": [
              {
                "text": "Create Amazing AI Videos",
                "decoration": ["decor-underline", "decor-bold"]
              }
            ]
          },
          "settings": {
            "textMode": "writeAnything"
          },
          "styleData": {
            "fontName": "Arial",
            "fontDisplayName": "Arial",
            "fontSize": "42",
            "fontColor": "rgb(255,255,255)",
            "fontWeight": 400,
            "textAlign": "left",
            "keywordColor": "rgba(248, 173, 151, 1)",
            "textBackgroundColor": "rgba(0,0,0,0)",
            "textShadowColor": "rgba(0,0,0,0)",
            "textShadowWidthFr": 0.03,
            "width": 0.9,
            "fullWidth": false,
            "preset": "bottom-left",
            "customFontId": null,
            "animation": {
              "textAnimation": [
                {
                  "name": "Typewriter",
                  "type": ["entry"],
                  "writingStyle": "character",
                  "direction": "up",
                  "speed": { "value": 1 }
                },
                {
                  "name": "None",
                  "type": ["exit"]
                }
              ],
              "textBgAnimation": []
            }
          }
        }
      ],
      "audios": [
        {
          "audio_id": "20260119024821485409b9abeb6c8b4b4cae9357ecbe637cfd67",
          "type": "voiceover",
          "voice": 3036,
          "version": "v6",
          "speed": 100,
          "loudness": 50,
          "clipUrl": "https://audios.example.com/voiceover.mp3",
          "isAudioLinked": true,
          "subScenes": {
            "duration": 1.53,
            "start": 0,
            "end": 1533,
            "word_markers": [
              [0, 300, "Create"],
              [350, 700, "Amazing"],
              [750, 950, "AI"],
              [1000, 1533, "Videos"]
            ]
          }
        }
      ]
    },
    {
      "sceneId": "202601180957031586203f72337a9493893722a4b07b5af7b",
      "text": "Transform your content with powerful AI tools",
      "sentence": [
        {
          "text": "Transform your content",
          "highlight": true,
          "decoration": ["decor-bold", "decor-underline"],
          "case": "none"
        },
        {
          "text": " with powerful ",
          "decoration": ["decor-bold", "decor-underline"],
          "case": "none"
        },
        {
          "text": "AI tools",
          "highlight": true,
          "decoration": ["decor-bold", "decor-underline"],
          "case": "none"
        }
      ],
      "keywords": ["Transform your content", "AI tools"],
      "category": "DEFAULT",
      "sortOrder": 10002,
      "settings": {
        "hideText": false
      },
      "background": {
        "type": "solid",
        "elementData": {
          "color": "rgb(69,123,113)"
        },
        "styleData": {}
      },
      "elements": []
    }
  ],
  "audios": [
    {
      "audioId": "202601180957049641f56b14fa78641359f69ccb5e03aac8c",
      "type": "background",
      "name": "Open Arms",
      "library": "melodie",
      "url": "https://tracks.example.com/background-music.mp3",
      "duration": 191,
      "loudness": 10,
      "speed": 100
    },
    {
      "audioId": "20260119024822426ae1e237bfddc4598b72be30c0c93ec33",
      "type": "voiceover",
      "name": "Abby",
      "library": "elevenlabs",
      "language": "en-US",
      "url": "https://audios.example.com/voiceover-full.mp3",
      "duration": 15.226,
      "loudness": 50,
      "speed": 100,
      "version": "v6",
      "time_markers": [1533, 3874, 8072, 9268, 10715, 12301, 13446, 15226],
      "word_markers": [
        [[0, 300, "Create"], [350, 700, "Amazing"], [750, 950, "AI"], [1000, 1533, "Videos"]],
        [[1533, 2100, "Transform"], [2150, 2400, "your"], [2450, 2900, "content"], [2950, 3200, "with"], [3250, 3600, "powerful"], [3650, 3774, "AI"], [3800, 4200, "tools"]]
      ]
    }
  ]
}

{
  "message": "Unauthorized"
}

{
  "message": "Project not found"
}

GET

pictoryapis

projects

{projectid}

Get Project by ID

curl --request GET \
  --url https://api.pictory.ai/pictoryapis/v2/projects/{projectid} \
  --header 'Authorization: <authorization>'

import requests

url = "https://api.pictory.ai/pictoryapis/v2/projects/{projectid}"

headers = {"Authorization": "<authorization>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {Authorization: '<authorization>'}};

fetch('https://api.pictory.ai/pictoryapis/v2/projects/{projectid}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.pictory.ai/pictoryapis/v2/projects/{projectid}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: <authorization>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.pictory.ai/pictoryapis/v2/projects/{projectid}"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "<authorization>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.pictory.ai/pictoryapis/v2/projects/{projectid}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = '<authorization>'

response = http.request(request)
puts response.read_body

{
  "project_id": "202601180951110906f5645f5952e4211bee28ac6100ddd68",
  "projectName": "AI Video Creation Guide",
  "projectType": "1",
  "source": "script",
  "step": "STORYBOARD",
  "schemaVersion": "v3",
  "layout": "16:9",
  "scriptLanguage": "en",
  "thumbnail": "https://cdn.example.com/thumbnail.jpg",
  "videoURL": "https://cdn.example.com/video/AI_Video_Creation_Guide.mp4",
  "audioURL": "https://cdn.example.com/audio/AI_Video_Creation_Guide.mp3",
  "shareVideoURL": "https://video.pictory.ai/project-id/share-id",
  "srtFile": "https://cdn.example.com/subtitles/subtitles.srt",
  "vttFile": "https://cdn.example.com/subtitles/subtitles.vtt",
  "txtFile": "https://cdn.example.com/subtitles/subtitles.txt",
  "videoDuration": 21.98,
  "audioSpeed": 100,
  "videoVolume": 50,
  "voiceOverId": "20260119024822426ae1e237bfddc4598b72be30c0c93ec33",
  "smartTemplateId": "20250813042630669e658e159aa60455692c1dad5473adtd3",
  "brandId": "",
  "saveDate": "2026-01-19T09:23:21.131Z",
  "generatedDate": "2026-01-19T09:26:23.059Z",
  "scriptTxtSceneSettings": {
    "autoVisualSelection": true,
    "selectedValueSceneBreakChar": "Both",
    "autoHighlightKeywords": true,
    "maxLines": 2
  },
  "visualFilter": {
    "libraries": [],
    "styles": [],
    "categories": []
  },
  "scenes": [
    {
      "sceneId": "2026011809570315812dcab8bad504b84a76171a1dd620cc5",
      "projectId": "202601180951110906f5645f5952e4211bee28ac6100ddd68",
      "text": "Create Amazing AI Videos",
      "sentence": [
        { "text": "Create " },
        { "highlight": true, "text": "Amazing AI Videos" }
      ],
      "keywords": ["Amazing AI Videos"],
      "category": "TITLE",
      "sortOrder": 10001,
      "durationAuto": 5,
      "layoutId": "20250901134117bbb9d28f462ef350f3",
      "settings": {
        "hideText": true
      },
      "styleData": {
        "fontName": "Plus Jakarta Sans",
        "fontDisplayName": "Plus Jakarta Sans",
        "fontSize": "24",
        "fontColor": "rgb(255,255,255)",
        "textAlign": "center",
        "keywordColor": "rgb(245,240,162)",
        "textBackgroundColor": "rgba(0,0,0,0.35)",
        "textShadowColor": "rgba(0,0,0,1)",
        "textShadowWidthFr": 0.03,
        "maxLines": 2,
        "width": 0.7,
        "preset": "bottom-center"
      },
      "background": {
        "type": "image",
        "elementData": {
          "url": "https://images.example.com/photo.jpg",
          "preview_jpg": "https://images.example.com/photo.jpg",
          "thumb": "https://images.example.com/photo-thumb.jpg",
          "thumb_jpg": "https://images.example.com/photo-thumb.jpg",
          "library": "unsplash",
          "libraryItemId": "mR1CIDduGLc",
          "duration": 0
        },
        "styleData": {
          "kenBurns": "kb-364683-oqt0",
          "imageZoomPan": true,
          "width": 0.7,
          "aspectRatio": 1.78,
          "preset": "center-center",
          "colorOverlay": {
            "hide": false,
            "bgColor": "rgb(0,37,60)",
            "opacity": 0.5
          }
        },
        "settings": {}
      },
      "elements": [
        {
          "elementId": "2026011815294013646c92e549f6646c49f31274227faf54d",
          "type": "video",
          "isLogo": false,
          "hide": false,
          "elementData": {
            "url": "https://videos.example.com/clip.mp4",
            "preview_jpg": "https://videos.example.com/clip-preview.jpg",
            "thumb": "https://videos.example.com/clip-thumb.mp4",
            "thumb_jpg": "https://videos.example.com/clip-thumb.jpg",
            "library": "story_blocks",
            "libraryItemId": "0",
            "duration": 16
          },
          "settings": {
            "loopVideo": true,
            "muteClipAudio": true
          },
          "styleData": {
            "top": 4.89,
            "left": 3.96,
            "width": 0.9259,
            "aspectRatio": 1.8066,
            "preset": null,
            "height": null,
            "sourceDimensions": {
              "width": 0.9512,
              "aspectRatio": 1.7778,
              "relYPercent": -0.0273,
              "relXPercent": -0.0127
            },
            "colorOverlay": {
              "hide": false,
              "bgColor": "rgb(110,111,132)",
              "opacity": 0.3
            }
          }
        },
        {
          "elementId": "202601180957034073d8a97be18614182b23c87f8c7fb2382",
          "type": "text",
          "componentName": "main_title",
          "elementData": {
            "sentence": [
              {
                "text": "Create Amazing AI Videos",
                "decoration": ["decor-underline", "decor-bold"]
              }
            ]
          },
          "settings": {
            "textMode": "writeAnything"
          },
          "styleData": {
            "fontName": "Arial",
            "fontDisplayName": "Arial",
            "fontSize": "42",
            "fontColor": "rgb(255,255,255)",
            "fontWeight": 400,
            "textAlign": "left",
            "keywordColor": "rgba(248, 173, 151, 1)",
            "textBackgroundColor": "rgba(0,0,0,0)",
            "textShadowColor": "rgba(0,0,0,0)",
            "textShadowWidthFr": 0.03,
            "width": 0.9,
            "fullWidth": false,
            "preset": "bottom-left",
            "customFontId": null,
            "animation": {
              "textAnimation": [
                {
                  "name": "Typewriter",
                  "type": ["entry"],
                  "writingStyle": "character",
                  "direction": "up",
                  "speed": { "value": 1 }
                },
                {
                  "name": "None",
                  "type": ["exit"]
                }
              ],
              "textBgAnimation": []
            }
          }
        }
      ],
      "audios": [
        {
          "audio_id": "20260119024821485409b9abeb6c8b4b4cae9357ecbe637cfd67",
          "type": "voiceover",
          "voice": 3036,
          "version": "v6",
          "speed": 100,
          "loudness": 50,
          "clipUrl": "https://audios.example.com/voiceover.mp3",
          "isAudioLinked": true,
          "subScenes": {
            "duration": 1.53,
            "start": 0,
            "end": 1533,
            "word_markers": [
              [0, 300, "Create"],
              [350, 700, "Amazing"],
              [750, 950, "AI"],
              [1000, 1533, "Videos"]
            ]
          }
        }
      ]
    },
    {
      "sceneId": "202601180957031586203f72337a9493893722a4b07b5af7b",
      "text": "Transform your content with powerful AI tools",
      "sentence": [
        {
          "text": "Transform your content",
          "highlight": true,
          "decoration": ["decor-bold", "decor-underline"],
          "case": "none"
        },
        {
          "text": " with powerful ",
          "decoration": ["decor-bold", "decor-underline"],
          "case": "none"
        },
        {
          "text": "AI tools",
          "highlight": true,
          "decoration": ["decor-bold", "decor-underline"],
          "case": "none"
        }
      ],
      "keywords": ["Transform your content", "AI tools"],
      "category": "DEFAULT",
      "sortOrder": 10002,
      "settings": {
        "hideText": false
      },
      "background": {
        "type": "solid",
        "elementData": {
          "color": "rgb(69,123,113)"
        },
        "styleData": {}
      },
      "elements": []
    }
  ],
  "audios": [
    {
      "audioId": "202601180957049641f56b14fa78641359f69ccb5e03aac8c",
      "type": "background",
      "name": "Open Arms",
      "library": "melodie",
      "url": "https://tracks.example.com/background-music.mp3",
      "duration": 191,
      "loudness": 10,
      "speed": 100
    },
    {
      "audioId": "20260119024822426ae1e237bfddc4598b72be30c0c93ec33",
      "type": "voiceover",
      "name": "Abby",
      "library": "elevenlabs",
      "language": "en-US",
      "url": "https://audios.example.com/voiceover-full.mp3",
      "duration": 15.226,
      "loudness": 50,
      "speed": 100,
      "version": "v6",
      "time_markers": [1533, 3874, 8072, 9268, 10715, 12301, 13446, 15226],
      "word_markers": [
        [[0, 300, "Create"], [350, 700, "Amazing"], [750, 950, "AI"], [1000, 1533, "Videos"]],
        [[1533, 2100, "Transform"], [2150, 2400, "your"], [2450, 2900, "content"], [2950, 3200, "with"], [3250, 3600, "powerful"], [3650, 3774, "AI"], [3800, 4200, "tools"]]
      ]
    }
  ]
}

{
  "message": "Unauthorized"
}

{
  "message": "Project not found"
}

Overview

Retrieve comprehensive details about a specific project using its unique identifier. This endpoint returns the complete project configuration, including storyboard data, video URLs, audio settings, script information, and rendering details.

You need a valid API key to use this endpoint. Get your API key from the API Access page in your Pictory dashboard.

API Endpoint

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

Request Parameters

Path Parameters

string

required

The unique identifier of the project to retrieve. Can be either a string (for v3 schema projects) or an integer (for v2 schema and earlier projects).Example: 20251222191648030d7df02f5b4054d4ca8831f1369459e25

Headers

string

required

API key for authentication (starts with pictai_)

Authorization: YOUR_API_KEY

Response

The response contains detailed project information including configuration, media URLs, metadata, and all video elements such as scenes, backgrounds, text overlays, video clips, and audio tracks.

Video Elements Structure

A Pictory project contains multiple video elements organized hierarchically. Understanding this structure is essential for working with project data.

Do not modify project fields if their usage is unclear. Incorrect modifications can cause unexpected behavior or corrupt your project. If you have questions about specific fields or their intended use, please contact our support team at support@pictory.ai before making changes.

Scenes

The scenes array contains all scenes in the project. Each scene represents a segment of the video with its own visual content, text, and audio. Scene Properties:

sceneId - Unique identifier for the scene
text - The display text/narration for the scene
sentence - Array of text segments with formatting options (highlight, decoration, case)
category - Scene type: TITLE, DEFAULT, or EMPHASIS
sortOrder - Numeric order of the scene in the video
durationAuto - Auto-calculated duration in seconds
keywords - Array of highlighted keywords from the text
layoutId - Template layout applied to the scene

Scene Text Styling (`styleData`)

Each scene has a styleData object controlling text appearance:

Field	Description
`fontName`	Font family name (e.g., `Arial`, `Plus Jakarta Sans`)
`fontDisplayName`	Display name of the font
`fontSize`	Font size in pixels
`fontColor`	Text color in RGB format (e.g., `rgb(255,255,255)`)
`fontWeight`	Font weight (e.g., `400` for normal, `700` for bold)
`textAlign`	Text alignment: `left`, `center`, or `right`
`keywordColor`	Highlight color for keywords in RGBA format
`textBackgroundColor`	Background color behind text in RGBA format
`textShadowColor`	Text shadow color in RGBA format
`textShadowWidthFr`	Text shadow width as a fraction
`maxLines`	Maximum number of text lines displayed
`width`	Text container width as a fraction (0-1)
`preset`	Text position preset: `bottom-left`, `bottom-center`, `center-center`, etc.
`customFontId`	ID reference for custom uploaded fonts
`animation`	Text animation settings (entry/exit animations)

Background Elements (`background`)

Each scene has a background object that defines the visual backdrop. The background type determines the content: Image Background (type: "image"):

{
  "type": "image",
  "elementData": {
    "url": "https://...",           // Full resolution image URL
    "preview_jpg": "https://...",   // Preview image URL
    "thumb": "https://...",         // Thumbnail URL
    "thumb_jpg": "https://...",     // Thumbnail JPG URL
    "library": "unsplash",          // Source library (unsplash, story_blocks, getty, uploads)
    "libraryItemId": "mR1CIDduGLc", // Library item identifier
    "duration": 0                   // Duration (0 for images)
  },
  "styleData": {
    "kenBurns": "kb-364683-oqt0",   // Ken Burns animation effect ID
    "imageZoomPan": true,           // Enable zoom/pan animation
    "width": 0.7,                   // Display width as fraction
    "aspectRatio": 1.78,            // Image aspect ratio
    "preset": "center-center",      // Position preset
    "colorOverlay": {               // Optional color overlay
      "hide": false,
      "bgColor": "rgb(0,37,60)",
      "opacity": 0.5
    }
  }
}

Video Background (type: "video"):

{
  "type": "video",
  "elementData": {
    "url": "https://...",           // Video URL (480p quality)
    "preview_jpg": "https://...",   // Preview thumbnail image
    "thumb": "https://...",         // Thumbnail video (180p)
    "thumb_jpg": "https://...",     // Thumbnail image
    "library": "story_blocks",      // Source: story_blocks, getty, pexels, uploads
    "libraryItemId": "120818",      // Library item identifier
    "description": "Video title",   // Video description
    "duration": 10                  // Video duration in seconds
  },
  "styleData": {
    "imageZoomPan": true            // Enable zoom/pan animation
  },
  "settings": {
    "loopVideo": true               // Loop video playback
  }
}

Solid Color Background (type: "solid"):

{
  "type": "solid",
  "elementData": {
    "color": "rgb(69,123,113)"      // Background color in RGB
  },
  "styleData": {}
}

Scene Elements (`elements`)

The elements array within each scene contains overlay elements placed on top of the background. Each element has a type that determines its content. Video Element (type: "video"): Video clips placed as overlays within a scene:

Field	Description
`elementId`	Unique identifier for the element
`type`	Element type: `video`
`isLogo`	Whether this video is used as a logo
`hide`	Whether the element is hidden
`settings.loopVideo`	Loop the video clip
`settings.muteClipAudio`	Mute the video’s audio
`elementData.url`	Video file URL (480p quality)
`elementData.preview_jpg`	Preview thumbnail image
`elementData.thumb`	Thumbnail video URL (180p)
`elementData.thumb_jpg`	Thumbnail image URL
`elementData.library`	Source library: `story_blocks`, `getty`, `pexels`, `uploads`
`elementData.libraryItemId`	Library item identifier
`elementData.duration`	Video duration in seconds
`styleData.top`	Vertical position (percentage from top)
`styleData.left`	Horizontal position (percentage from left)
`styleData.width`	Element width as fraction (0-1)
`styleData.height`	Element height (null for auto)
`styleData.aspectRatio`	Display aspect ratio
`styleData.preset`	Position preset (null for custom position)
`styleData.sourceDimensions`	Original source dimensions and offsets
`styleData.colorOverlay`	Color overlay settings (bgColor, opacity, hide)

Image Element (type: "image"): Image overlays placed within a scene. Uses the same fields as video elements, except there is no elementData.duration and no playback settings (loopVideo/muteClipAudio). The elementData.library value reflects the image source (for example unsplash, getty, or uploaded). Text Element (type: "text"): Text overlays placed within a scene:

Field	Description
`elementId`	Unique identifier for the element
`type`	Element type: `text`
`componentName`	Component role: `main_title`, `story_text`, etc.
`settings.textMode`	Mode: `useStoryText` (from scene) or `writeAnything` (custom)
`elementData.sentence`	Array of text segments with formatting

Text Sentence Structure:

{
  "sentence": [
    {
      "text": "Hello World",
      "highlight": true,              // Apply keyword highlighting
      "decoration": ["decor-bold", "decor-underline"],  // Text decorations
      "case": "none"                  // Text case transformation
    }
  ]
}

Text Element Styling (styleData):

Field	Description
`fontName`	Font family
`fontDisplayName`	Font display name
`fontSize`	Font size in pixels
`fontColor`	Text color (RGB format)
`fontWeight`	Font weight (400=normal, 700=bold)
`textAlign`	Alignment: `left`, `center`, `right`
`keywordColor`	Highlight color (RGBA)
`textBackgroundColor`	Background color (RGBA)
`textShadowColor`	Shadow color (RGBA)
`textShadowWidthFr`	Shadow width fraction
`top`	Vertical position (null for preset)
`left`	Horizontal position (null for preset)
`width`	Container width (0-1)
`maxLines`	Maximum display lines
`fullWidth`	Use full width container
`preset`	Position preset
`customFontId`	Custom font reference
`animation`	Animation configuration

Text Animation Structure:

{
  "animation": {
    "textAnimation": [
      {
        "name": "Typewriter",         // Animation name
        "type": ["entry"],            // Type: entry or exit
        "writingStyle": "character",  // Style: character, word, or line
        "direction": "up",            // Animation direction
        "speed": { "value": 1 }       // Animation speed
      },
      {
        "name": "None",
        "type": ["exit"]
      }
    ],
    "textBgAnimation": []             // Background animations
  }
}

Audio Elements

Scene-Level Audio (scene.audios): Each scene can have voiceover audio with word-level timing:

Field	Description
`audio_id`	Unique audio clip identifier
`type`	Audio type: `voiceover`
`voice`	Voice ID number
`version`	Voice version (e.g., `v6`)
`speed`	Playback speed percentage (100 = normal)
`loudness`	Volume level (0-100)
`clipUrl`	URL to the audio clip file
`subScenes.duration`	Audio duration in seconds
`subScenes.start`	Start time in milliseconds
`subScenes.end`	End time in milliseconds
`subScenes.word_markers`	Array of [start_ms, end_ms, word] for each word
`isAudioLinked`	Whether audio is linked across scenes

Project-Level Audio (audios):

Field	Description
`audioId`	Unique audio identifier
`type`	Type: `background` (music) or `voiceover`
`name`	Audio/voice name
`url`	Audio file URL
`library`	Source: `melodie`, `elevenlabs`, `polly`
`duration`	Total duration in seconds
`loudness`	Volume level (0-100)
`speed`	Playback speed percentage
`language`	Language code (for voiceover)
`word_markers`	Nested array of word timing per scene
`time_markers`	Array of scene end timestamps (ms)

Media Libraries

The library field indicates the source of visual content:

Library	Description
`unsplash`	Unsplash stock photos
`story_blocks`	Storyblocks stock video/images
`getty`	Getty Images stock content
`pexels`	Pexels stock photos/videos
`melodie`	Melodie background music
`elevenlabs`	ElevenLabs AI voices
`polly`	Amazon Polly text-to-speech
`uploads`	User-uploaded content

Response Examples

{
  "project_id": "202601180951110906f5645f5952e4211bee28ac6100ddd68",
  "projectName": "AI Video Creation Guide",
  "projectType": "1",
  "source": "script",
  "step": "STORYBOARD",
  "schemaVersion": "v3",
  "layout": "16:9",
  "scriptLanguage": "en",
  "thumbnail": "https://cdn.example.com/thumbnail.jpg",
  "videoURL": "https://cdn.example.com/video/AI_Video_Creation_Guide.mp4",
  "audioURL": "https://cdn.example.com/audio/AI_Video_Creation_Guide.mp3",
  "shareVideoURL": "https://video.pictory.ai/project-id/share-id",
  "srtFile": "https://cdn.example.com/subtitles/subtitles.srt",
  "vttFile": "https://cdn.example.com/subtitles/subtitles.vtt",
  "txtFile": "https://cdn.example.com/subtitles/subtitles.txt",
  "videoDuration": 21.98,
  "audioSpeed": 100,
  "videoVolume": 50,
  "voiceOverId": "20260119024822426ae1e237bfddc4598b72be30c0c93ec33",
  "smartTemplateId": "20250813042630669e658e159aa60455692c1dad5473adtd3",
  "brandId": "",
  "saveDate": "2026-01-19T09:23:21.131Z",
  "generatedDate": "2026-01-19T09:26:23.059Z",
  "scriptTxtSceneSettings": {
    "autoVisualSelection": true,
    "selectedValueSceneBreakChar": "Both",
    "autoHighlightKeywords": true,
    "maxLines": 2
  },
  "visualFilter": {
    "libraries": [],
    "styles": [],
    "categories": []
  },
  "scenes": [
    {
      "sceneId": "2026011809570315812dcab8bad504b84a76171a1dd620cc5",
      "projectId": "202601180951110906f5645f5952e4211bee28ac6100ddd68",
      "text": "Create Amazing AI Videos",
      "sentence": [
        { "text": "Create " },
        { "highlight": true, "text": "Amazing AI Videos" }
      ],
      "keywords": ["Amazing AI Videos"],
      "category": "TITLE",
      "sortOrder": 10001,
      "durationAuto": 5,
      "layoutId": "20250901134117bbb9d28f462ef350f3",
      "settings": {
        "hideText": true
      },
      "styleData": {
        "fontName": "Plus Jakarta Sans",
        "fontDisplayName": "Plus Jakarta Sans",
        "fontSize": "24",
        "fontColor": "rgb(255,255,255)",
        "textAlign": "center",
        "keywordColor": "rgb(245,240,162)",
        "textBackgroundColor": "rgba(0,0,0,0.35)",
        "textShadowColor": "rgba(0,0,0,1)",
        "textShadowWidthFr": 0.03,
        "maxLines": 2,
        "width": 0.7,
        "preset": "bottom-center"
      },
      "background": {
        "type": "image",
        "elementData": {
          "url": "https://images.example.com/photo.jpg",
          "preview_jpg": "https://images.example.com/photo.jpg",
          "thumb": "https://images.example.com/photo-thumb.jpg",
          "thumb_jpg": "https://images.example.com/photo-thumb.jpg",
          "library": "unsplash",
          "libraryItemId": "mR1CIDduGLc",
          "duration": 0
        },
        "styleData": {
          "kenBurns": "kb-364683-oqt0",
          "imageZoomPan": true,
          "width": 0.7,
          "aspectRatio": 1.78,
          "preset": "center-center",
          "colorOverlay": {
            "hide": false,
            "bgColor": "rgb(0,37,60)",
            "opacity": 0.5
          }
        },
        "settings": {}
      },
      "elements": [
        {
          "elementId": "2026011815294013646c92e549f6646c49f31274227faf54d",
          "type": "video",
          "isLogo": false,
          "hide": false,
          "elementData": {
            "url": "https://videos.example.com/clip.mp4",
            "preview_jpg": "https://videos.example.com/clip-preview.jpg",
            "thumb": "https://videos.example.com/clip-thumb.mp4",
            "thumb_jpg": "https://videos.example.com/clip-thumb.jpg",
            "library": "story_blocks",
            "libraryItemId": "0",
            "duration": 16
          },
          "settings": {
            "loopVideo": true,
            "muteClipAudio": true
          },
          "styleData": {
            "top": 4.89,
            "left": 3.96,
            "width": 0.9259,
            "aspectRatio": 1.8066,
            "preset": null,
            "height": null,
            "sourceDimensions": {
              "width": 0.9512,
              "aspectRatio": 1.7778,
              "relYPercent": -0.0273,
              "relXPercent": -0.0127
            },
            "colorOverlay": {
              "hide": false,
              "bgColor": "rgb(110,111,132)",
              "opacity": 0.3
            }
          }
        },
        {
          "elementId": "202601180957034073d8a97be18614182b23c87f8c7fb2382",
          "type": "text",
          "componentName": "main_title",
          "elementData": {
            "sentence": [
              {
                "text": "Create Amazing AI Videos",
                "decoration": ["decor-underline", "decor-bold"]
              }
            ]
          },
          "settings": {
            "textMode": "writeAnything"
          },
          "styleData": {
            "fontName": "Arial",
            "fontDisplayName": "Arial",
            "fontSize": "42",
            "fontColor": "rgb(255,255,255)",
            "fontWeight": 400,
            "textAlign": "left",
            "keywordColor": "rgba(248, 173, 151, 1)",
            "textBackgroundColor": "rgba(0,0,0,0)",
            "textShadowColor": "rgba(0,0,0,0)",
            "textShadowWidthFr": 0.03,
            "width": 0.9,
            "fullWidth": false,
            "preset": "bottom-left",
            "customFontId": null,
            "animation": {
              "textAnimation": [
                {
                  "name": "Typewriter",
                  "type": ["entry"],
                  "writingStyle": "character",
                  "direction": "up",
                  "speed": { "value": 1 }
                },
                {
                  "name": "None",
                  "type": ["exit"]
                }
              ],
              "textBgAnimation": []
            }
          }
        }
      ],
      "audios": [
        {
          "audio_id": "20260119024821485409b9abeb6c8b4b4cae9357ecbe637cfd67",
          "type": "voiceover",
          "voice": 3036,
          "version": "v6",
          "speed": 100,
          "loudness": 50,
          "clipUrl": "https://audios.example.com/voiceover.mp3",
          "isAudioLinked": true,
          "subScenes": {
            "duration": 1.53,
            "start": 0,
            "end": 1533,
            "word_markers": [
              [0, 300, "Create"],
              [350, 700, "Amazing"],
              [750, 950, "AI"],
              [1000, 1533, "Videos"]
            ]
          }
        }
      ]
    },
    {
      "sceneId": "202601180957031586203f72337a9493893722a4b07b5af7b",
      "text": "Transform your content with powerful AI tools",
      "sentence": [
        {
          "text": "Transform your content",
          "highlight": true,
          "decoration": ["decor-bold", "decor-underline"],
          "case": "none"
        },
        {
          "text": " with powerful ",
          "decoration": ["decor-bold", "decor-underline"],
          "case": "none"
        },
        {
          "text": "AI tools",
          "highlight": true,
          "decoration": ["decor-bold", "decor-underline"],
          "case": "none"
        }
      ],
      "keywords": ["Transform your content", "AI tools"],
      "category": "DEFAULT",
      "sortOrder": 10002,
      "settings": {
        "hideText": false
      },
      "background": {
        "type": "solid",
        "elementData": {
          "color": "rgb(69,123,113)"
        },
        "styleData": {}
      },
      "elements": []
    }
  ],
  "audios": [
    {
      "audioId": "202601180957049641f56b14fa78641359f69ccb5e03aac8c",
      "type": "background",
      "name": "Open Arms",
      "library": "melodie",
      "url": "https://tracks.example.com/background-music.mp3",
      "duration": 191,
      "loudness": 10,
      "speed": 100
    },
    {
      "audioId": "20260119024822426ae1e237bfddc4598b72be30c0c93ec33",
      "type": "voiceover",
      "name": "Abby",
      "library": "elevenlabs",
      "language": "en-US",
      "url": "https://audios.example.com/voiceover-full.mp3",
      "duration": 15.226,
      "loudness": 50,
      "speed": 100,
      "version": "v6",
      "time_markers": [1533, 3874, 8072, 9268, 10715, 12301, 13446, 15226],
      "word_markers": [
        [[0, 300, "Create"], [350, 700, "Amazing"], [750, 950, "AI"], [1000, 1533, "Videos"]],
        [[1533, 2100, "Transform"], [2150, 2400, "your"], [2450, 2900, "content"], [2950, 3200, "with"], [3250, 3600, "powerful"], [3650, 3774, "AI"], [3800, 4200, "tools"]]
      ]
    }
  ]
}

{
  "message": "Unauthorized"
}

{
  "message": "Project not found"
}

Code Examples

Replace YOUR_API_KEY with your actual API key that starts with pictai_

curl --request GET \
  --url 'https://api.pictory.ai/pictoryapis/v2/projects/YOUR_PROJECT_ID' \
  --header 'Authorization: YOUR_API_KEY' \
  --header 'accept: application/json' | python -m json.tool

import requests

project_id = "20251222191648030d7df02f5b4054d4ca8831f1369459e25"
url = f"https://api.pictory.ai/pictoryapis/v2/projects/{project_id}"
headers = {
    "Authorization": "YOUR_API_KEY",
    "accept": "application/json"
}

response = requests.get(url, headers=headers)
project = response.json()

# Print key project details
print(f"Project: {project['projectName']}")
print(f"Status: {project['step']}")
print(f"Duration: {project['videoDuration']} seconds")
print(f"Video URL: {project.get('videoURL', 'Not available')}")

const projectId = '20251222191648030d7df02f5b4054d4ca8831f1369459e25';
const response = await fetch(
  `https://api.pictory.ai/pictoryapis/v2/projects/${projectId}`,
  {
    method: 'GET',
    headers: {
      'Authorization': 'YOUR_API_KEY',
      'accept': 'application/json'
    }
  }
);

const project = await response.json();

// Print key project details
console.log(`Project: ${project.projectName}`);
console.log(`Status: ${project.step}`);
console.log(`Duration: ${project.videoDuration} seconds`);
console.log(`Video URL: ${project.videoURL || 'Not available'}`);

List Projects Update Project

⌘I

Getting started

Videos

Pictory Jobs

Video Storyboard

AI Studio

Smart Layouts

Avatars

VoiceOvers

Music Search

Media Management

Branding - Video

Pictory Projects

Video Templates

Video Summary and Transcription

Vimeo Integration

AWS Integration

Account & Usage

Get Project by ID

Overview

API Endpoint

Request Parameters

Path Parameters

Headers

Response

Video Elements Structure

Scenes

Scene Text Styling (`styleData`)

Background Elements (`background`)

Scene Elements (`elements`)

Audio Elements

Media Libraries

Response Examples

Code Examples

​Overview

​API Endpoint

​Request Parameters

​Path Parameters

​Headers

​Response

​Video Elements Structure

​Scenes

​Scene Text Styling (styleData)

​Background Elements (background)

​Scene Elements (elements)

​Audio Elements

​Media Libraries

​Response Examples

​Code Examples

Overview

API Endpoint

Request Parameters

Path Parameters

Headers

Response

Video Elements Structure

Scenes

Scene Text Styling (`styleData`)

Background Elements (`background`)

Scene Elements (`elements`)

Audio Elements

Media Libraries

Response Examples

Code Examples