Get Project by ID
Pictory Projects
Get Project by ID
Retrieve detailed information about a specific project using its unique project ID
GET
Get Project by ID
Documentation Index
Fetch the complete documentation index at: https://docs.pictory.ai/llms.txt
Use this file to discover all available pages before exploring further.
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
Request Parameters
Path Parameters
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:
20251222191648030d7df02f5b4054d4ca8831f1369459e25Headers
API key for authentication (starts with
pictai_)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.Scenes
Thescenes 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 scenetext- The display text/narration for the scenesentence- Array of text segments with formatting options (highlight, decoration, case)category- Scene type:TITLE,DEFAULT, orEMPHASISsortOrder- Numeric order of the scene in the videodurationAuto- Auto-calculated duration in secondskeywords- Array of highlighted keywords from the textlayoutId- 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: "video"):
type: "solid"):
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) |
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 |
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 |
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 |
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
Thelibrary 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 |
