> ## 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.

# Get Project by ID

> Retrieve detailed information about a specific project using its unique project ID

## 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.

<Note>
  You need a valid API key to use this endpoint. Get your API key from the [API Access page](https://app.pictory.ai/api-access) in your Pictory dashboard.
</Note>

***

## API Endpoint

```http theme={null}
GET https://api.pictory.ai/pictoryapis/v2/projects/{projectid}
```

***

## Request Parameters

### Path Parameters

<ParamField path="projectid" type="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`
</ParamField>

### Headers

<ParamField header="Authorization" type="string" required>
  API key for authentication (starts with `pictai_`)

  ```
  Authorization: YOUR_API_KEY
  ```
</ParamField>

***

## 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.

<Warning>
  **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](mailto:support@pictory.ai) before making changes.
</Warning>

### 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"`):

```json theme={null}
{
  "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"`):

```json theme={null}
{
  "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"`):

```json theme={null}
{
  "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:**

```json theme={null}
{
  "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:**

```json theme={null}
{
  "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

<ResponseExample>
  ```json 200 - Success theme={null}
  {
    "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"]]
        ]
      }
    ]
  }
  ```

  ```json 401 - Unauthorized theme={null}
  {
    "message": "Unauthorized"
  }
  ```

  ```json 404 - Not Found theme={null}
  {
    "message": "Project not found"
  }
  ```
</ResponseExample>

***

## Code Examples

<Tip>
  Replace `YOUR_API_KEY` with your actual API key that starts with `pictai_`
</Tip>

<CodeGroup>
  ```bash cURL theme={null}
  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
  ```

  ```python Python theme={null}
  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')}")
  ```

  ```javascript JavaScript theme={null}
  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'}`);
  ```
</CodeGroup>

***