Update Project

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

import requests

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

headers = {
    "Authorization": "<authorization>",
    "Content-Type": "<content-type>"
}

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

print(response.text)

const options = {
  method: 'PUT',
  headers: {Authorization: '<authorization>', 'Content-Type': '<content-type>'}
};

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 => "PUT",
  CURLOPT_HTTPHEADER => [
    "Authorization: <authorization>",
    "Content-Type: <content-type>"
  ],
]);

$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("PUT", url, nil)

	req.Header.Add("Authorization", "<authorization>")
	req.Header.Add("Content-Type", "<content-type>")

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

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

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.put("https://api.pictory.ai/pictoryapis/v2/projects/{projectid}")
  .header("Authorization", "<authorization>")
  .header("Content-Type", "<content-type>")
  .asString();

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::Put.new(url)
request["Authorization"] = '<authorization>'
request["Content-Type"] = '<content-type>'

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

{
  "success": true,
  "message": "Project updated successfully",
  "project": {
    "projectName": "Updated Project Name",
    "audioSpeed": 100,
    "videoVolume": 50,
    "scenes": [
      {
        "text": "Updated scene text",
        "sentence": [
          {
            "text": "Updated scene text",
            "highlight": true
          }
        ],
        "settings": {
          "hideText": false
        },
        "background": {
          "type": "image",
          "elementData": {
            "url": "https://new-media-url.com/image.jpg"
          }
        }
      }
    ]
  }
}

{
  "success": false,
  "message": "Invalid project data",
  "error": "Missing required fields"
}

{
  "message": "Unauthorized"
}

{
  "success": false,
  "message": "Project not found"
}

PUT

pictoryapis

projects

{projectid}

Update Project

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

import requests

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

headers = {
    "Authorization": "<authorization>",
    "Content-Type": "<content-type>"
}

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

print(response.text)

const options = {
  method: 'PUT',
  headers: {Authorization: '<authorization>', 'Content-Type': '<content-type>'}
};

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 => "PUT",
  CURLOPT_HTTPHEADER => [
    "Authorization: <authorization>",
    "Content-Type: <content-type>"
  ],
]);

$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("PUT", url, nil)

	req.Header.Add("Authorization", "<authorization>")
	req.Header.Add("Content-Type", "<content-type>")

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

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

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.put("https://api.pictory.ai/pictoryapis/v2/projects/{projectid}")
  .header("Authorization", "<authorization>")
  .header("Content-Type", "<content-type>")
  .asString();

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::Put.new(url)
request["Authorization"] = '<authorization>'
request["Content-Type"] = '<content-type>'

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

{
  "success": true,
  "message": "Project updated successfully",
  "project": {
    "projectName": "Updated Project Name",
    "audioSpeed": 100,
    "videoVolume": 50,
    "scenes": [
      {
        "text": "Updated scene text",
        "sentence": [
          {
            "text": "Updated scene text",
            "highlight": true
          }
        ],
        "settings": {
          "hideText": false
        },
        "background": {
          "type": "image",
          "elementData": {
            "url": "https://new-media-url.com/image.jpg"
          }
        }
      }
    ]
  }
}

{
  "success": false,
  "message": "Invalid project data",
  "error": "Missing required fields"
}

{
  "message": "Unauthorized"
}

{
  "success": false,
  "message": "Project not found"
}

Overview

Update an existing project by sending the complete updated project object. This endpoint allows you to modify scene visuals, subtitle text content, scene settings, and other project attributes. The entire project object must be included in the request; partial updates are not supported.

Complete Object Required: You must send the entire project object in the request body, even if you are only changing a few fields. Omitting fields may result in data loss or project corruption.

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

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

Request Parameters

Path Parameters

string

required

The unique identifier of the project to update. 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

string

required

Must be set to application/json

Content-Type: application/json

Request Body

The request body must contain the complete project object retrieved from the Get Project by ID endpoint. Modify only the fields you need to change while preserving all other fields.

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.

Updatable Video Elements

The following sections describe the video element fields that can be safely modified. These structures match the response from the Get Project by ID endpoint.

Project-Level Fields

These top-level fields can be safely updated:

{
  "projectName": "My Updated Video",
  "audioSpeed": 100,
  "videoVolume": 50
}

Field	Type	Description
`projectName`	string	Name of the project
`audioSpeed`	number	Audio playback speed percentage (100 = normal)
`videoVolume`	number	Background video volume level (0-100)

Scene Text (`scenes[].text` and `scenes[].sentence`)

Update the display text and narration for each scene:

{
  "scenes": [
    {
      "text": "Your new scene text here",
      "sentence": [
        {
          "text": "Your new ",
          "decoration": ["decor-bold"]
        },
        {
          "text": "scene text",
          "highlight": true,
          "decoration": ["decor-underline"]
        },
        {
          "text": " here"
        }
      ],
      "keywords": ["scene text"]
    }
  ]
}

Field	Type	Description
`text`	string	Plain text version of the scene narration
`sentence`	array	Array of text segments with formatting
`sentence[].text`	string	Text content of the segment
`sentence[].highlight`	boolean	Apply keyword highlighting
`sentence[].decoration`	array	Text decorations: `decor-bold`, `decor-underline`
`sentence[].case`	string	Text case: `none`, `uppercase`, `lowercase`
`keywords`	array	Array of highlighted keyword strings

Scene Text Styling (`scenes[].styleData`)

Modify text appearance for each scene:

{
  "scenes": [
    {
      "styleData": {
        "fontName": "Arial",
        "fontDisplayName": "Arial",
        "fontSize": "42",
        "fontColor": "rgb(255,255,255)",
        "fontWeight": 400,
        "textAlign": "left",
        "keywordColor": "rgba(141, 208, 229, 1)",
        "textBackgroundColor": "rgba(0,0,0,0.35)",
        "textShadowColor": "rgba(0,0,0,0)",
        "textShadowWidthFr": 0.03,
        "maxLines": 2,
        "width": 0.7,
        "preset": "bottom-left"
      }
    }
  ]
}

Field	Type	Description
`fontName`	string	Font family name
`fontSize`	string	Font size in pixels
`fontColor`	string	Text color (RGB format)
`fontWeight`	number	Font weight (400=normal, 700=bold)
`textAlign`	string	Alignment: `left`, `center`, `right`
`keywordColor`	string	Highlight color (RGBA format)
`textBackgroundColor`	string	Background color (RGBA format)
`maxLines`	number	Maximum display lines
`width`	number	Container width (0-1)
`preset`	string	Position: `bottom-left`, `bottom-center`, `center-center`, etc.

Scene Settings (`scenes[].settings`)

Control scene playback behavior:

{
  "scenes": [
    {
      "settings": {
        "hideText": false
      }
    }
  ]
}

Field	Type	Description
`hideText`	boolean	Hide subtitle/caption text for this scene

Background Image (`scenes[].background` with `type: "image"`)

Update the background image for a scene:

{
  "scenes": [
    {
      "background": {
        "type": "image",
        "elementData": {
          "url": "https://your-image-url.com/image.jpg",
          "preview_jpg": "https://your-image-url.com/preview.jpg",
          "thumb": "https://your-image-url.com/thumb.jpg",
          "thumb_jpg": "https://your-image-url.com/thumb.jpg",
          "library": "uploads",
          "libraryItemId": "your-item-id",
          "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
          }
        }
      }
    }
  ]
}

Field	Type	Description
`type`	string	Must be `"image"`
`elementData.url`	string	Full resolution image URL
`elementData.preview_jpg`	string	Preview image URL
`elementData.thumb`	string	Thumbnail URL
`elementData.library`	string	Source: `uploads`, `unsplash`, `story_blocks`, `getty`
`styleData.imageZoomPan`	boolean	Enable Ken Burns zoom/pan effect
`styleData.colorOverlay`	object	Color overlay settings

Background Video (`scenes[].background` with `type: "video"`)

Update the background video for a scene:

{
  "scenes": [
    {
      "background": {
        "type": "video",
        "elementData": {
          "url": "https://your-video-url.com/video.mp4",
          "preview_jpg": "https://your-video-url.com/preview.jpg",
          "thumb": "https://your-video-url.com/thumb.mp4",
          "thumb_jpg": "https://your-video-url.com/thumb.jpg",
          "library": "uploads",
          "libraryItemId": "your-item-id",
          "duration": 10,
          "description": "Video description"
        },
        "styleData": {
          "imageZoomPan": true
        },
        "settings": {
          "loopVideo": true
        }
      }
    }
  ]
}

Field	Type	Description
`type`	string	Must be `"video"`
`elementData.url`	string	Video file URL
`elementData.duration`	number	Video duration in seconds
`elementData.library`	string	Source: `uploads`, `story_blocks`, `getty`, `pexels`
`settings.loopVideo`	boolean	Loop video playback

Solid Color Background (`scenes[].background` with `type: "solid"`)

Set a solid color background:

{
  "scenes": [
    {
      "background": {
        "type": "solid",
        "elementData": {
          "color": "rgb(69,123,113)"
        },
        "styleData": {}
      }
    }
  ]
}

Video Element Overlay (`scenes[].elements[]` with `type: "video"`)

Update video clip overlays within a scene:

{
  "scenes": [
    {
      "elements": [
        {
          "elementId": "existing-element-id",
          "type": "video",
          "isLogo": false,
          "hide": false,
          "settings": {
            "loopVideo": true,
            "muteClipAudio": true
          },
          "elementData": {
            "url": "https://your-video-url.com/clip.mp4",
            "preview_jpg": "https://your-video-url.com/preview.jpg",
            "thumb": "https://your-video-url.com/thumb.mp4",
            "thumb_jpg": "https://your-video-url.com/thumb.jpg",
            "library": "uploads",
            "libraryItemId": "your-item-id",
            "duration": 16
          },
          "styleData": {
            "top": 4.89,
            "left": 3.96,
            "width": 0.92,
            "aspectRatio": 1.78,
            "preset": null,
            "colorOverlay": {
              "hide": false,
              "bgColor": "rgb(110,111,132)",
              "opacity": 0.3
            }
          }
        }
      ]
    }
  ]
}

Field	Type	Description
`elementId`	string	Unique element identifier (preserve existing)
`type`	string	Must be `"video"`
`hide`	boolean	Hide this element
`settings.loopVideo`	boolean	Loop the video clip
`settings.muteClipAudio`	boolean	Mute the video’s audio
`elementData.url`	string	Video file URL
`styleData.top`	number	Vertical position (%)
`styleData.left`	number	Horizontal position (%)
`styleData.width`	number	Element width (0-1)
`styleData.colorOverlay`	object	Color overlay settings

Text Element Overlay (`scenes[].elements[]` with `type: "text"`)

Update text overlay elements within a scene:

{
  "scenes": [
    {
      "elements": [
        {
          "elementId": "existing-element-id",
          "type": "text",
          "componentName": "main_title",
          "settings": {
            "textMode": "writeAnything"
          },
          "elementData": {
            "sentence": [
              {
                "text": "Your Custom Text",
                "decoration": ["decor-bold", "decor-underline"]
              }
            ]
          },
          "styleData": {
            "fontName": "Arial",
            "fontSize": "42",
            "fontColor": "rgb(255,255,255)",
            "textAlign": "center",
            "preset": "center-center",
            "width": 0.7,
            "animation": {
              "textAnimation": [
                {
                  "name": "Typewriter",
                  "type": ["entry"],
                  "writingStyle": "character",
                  "direction": "up",
                  "speed": { "value": 1 }
                },
                {
                  "name": "None",
                  "type": ["exit"]
                }
              ],
              "textBgAnimation": []
            }
          }
        }
      ]
    }
  ]
}

Field	Type	Description
`elementId`	string	Unique element identifier (preserve existing)
`type`	string	Must be `"text"`
`settings.textMode`	string	`useStoryText` or `writeAnything`
`elementData.sentence`	array	Text segments with formatting
`styleData.fontName`	string	Font family
`styleData.fontSize`	string	Font size in pixels
`styleData.fontColor`	string	Text color (RGB)
`styleData.animation`	object	Entry/exit animation settings

Quick Reference: Safe Updates

Scene Background Image

Field: scenes[].background (type: image)Replace background image with Ken Burns effect and color overlay.

{
  "background": {
    "type": "image",
    "elementData": {
      "url": "https://images.unsplash.com/photo-example",
      "preview_jpg": "https://images.unsplash.com/photo-example",
      "thumb": "https://images.unsplash.com/photo-example?w=200",
      "library": "unsplash",
      "libraryItemId": "mR1CIDduGLc",
      "duration": 0
    },
    "styleData": {
      "kenBurns": "kb-364683-oqt0",
      "imageZoomPan": true,
      "aspectRatio": 1.78,
      "colorOverlay": {
        "hide": false,
        "bgColor": "rgb(0,37,60)",
        "opacity": 0.5
      }
    }
  }
}

Scene Background Video

Field: scenes[].background (type: video)Replace background with a video clip.

{
  "background": {
    "type": "video",
    "elementData": {
      "url": "https://video-url.com/video.mp4",
      "preview_jpg": "https://video-url.com/preview.jpg",
      "thumb": "https://video-url.com/thumb.mp4",
      "library": "story_blocks",
      "libraryItemId": "120818",
      "duration": 10
    },
    "styleData": {
      "imageZoomPan": true
    },
    "settings": {
      "loopVideo": true
    }
  }
}

Scene Text & Keywords

Fields: scenes[].text, scenes[].sentence, scenes[].keywordsUpdate display text, formatting, and highlighted keywords.

{
  "text": "Sweeping views with year-round sunsets",
  "sentence": [
    {
      "text": "Sweeping views",
      "highlight": true,
      "decoration": ["decor-bold", "decor-underline"]
    },
    {
      "text": " with year-round "
    },
    {
      "text": "sunsets",
      "highlight": true
    }
  ],
  "keywords": ["Sweeping views", "sunsets"]
}

Scene Text Styling

Field: scenes[].styleDataUpdate text appearance, fonts, colors, and positioning.

{
  "styleData": {
    "fontName": "Arial",
    "fontDisplayName": "Arial",
    "fontSize": "42",
    "fontColor": "rgb(255,255,255)",
    "fontWeight": 400,
    "textAlign": "left",
    "keywordColor": "rgba(141, 208, 229, 1)",
    "textBackgroundColor": "rgba(0,0,0,0.35)",
    "textShadowColor": "rgba(0,0,0,0)",
    "maxLines": 2,
    "width": 0.7,
    "preset": "bottom-left"
  }
}

Scene Settings

Field: scenes[].settingsControl text visibility for the scene.

{
  "settings": {
    "hideText": false
  }
}

Video Element Overlay

Field: scenes[].elements[] (type: video)Update video clips placed as overlays within scenes.

{
  "elements": [{
    "type": "video",
    "isLogo": false,
    "hide": false,
    "elementData": {
      "url": "https://video-url.com/clip.mp4",
      "preview_jpg": "https://video-url.com/preview.jpg",
      "library": "story_blocks",
      "duration": 16
    },
    "settings": {
      "loopVideo": true,
      "muteClipAudio": true
    },
    "styleData": {
      "top": 4.89,
      "left": 3.96,
      "width": 0.92,
      "aspectRatio": 1.78,
      "colorOverlay": {
        "hide": false,
        "bgColor": "rgb(110,111,132)",
        "opacity": 0.3
      }
    }
  }]
}

Text Element Overlay

Field: scenes[].elements[] (type: text)Update text overlays and their styling/animations.

{
  "elements": [{
    "type": "text",
    "componentName": "main_title",
    "settings": {
      "textMode": "writeAnything"
    },
    "elementData": {
      "sentence": [{
        "text": "A Stunning Masterpiece",
        "decoration": ["decor-underline", "decor-bold"]
      }]
    },
    "styleData": {
      "fontName": "Arial",
      "fontSize": "42",
      "fontColor": "rgb(255,255,255)",
      "textAlign": "left",
      "preset": "bottom-left",
      "animation": {
        "textAnimation": [{
          "name": "Typewriter",
          "type": ["entry"],
          "writingStyle": "character",
          "speed": { "value": 1 }
        }]
      }
    }
  }]
}

Project Metadata

Fields: projectName, audioSpeed, videoVolumeUpdate basic project configuration.

{
  "projectName": "AI Video Creation Guide",
  "audioSpeed": 100,
  "videoVolume": 50
}

Fields to Avoid Modifying

Do Not Modify These Fields unless you fully understand their structure and dependencies:

sceneId, elementId, projectId - Unique identifiers
partitionKey, sortKey - Database keys
audio_id, voiceOverId, audioId - Audio reference IDs
assetResponseId - Asset tracking identifiers
schemaVersion - Project schema version
approximateCreationDateTime - System timestamps
createdBy, modifiedBy, cognito_id - User identifiers
audios - Audio configuration (complex dependencies)
word_markers, time_markers, subScenes - Audio timing data

Modifying these fields without proper understanding can cause project corruption or rendering failures. Contact support@pictory.ai if you need guidance.

Response

The API returns a JSON response indicating the success or failure of the update operation. Success Response Fields:

Field	Type	Description
`success`	boolean	`true` if the update was successful
`message`	string	Confirmation message
`project`	object	The updated project object with all current values

Error Response Fields:

Field	Type	Description
`success`	boolean	`false` if the update failed
`message`	string	Error description
`error`	string	Detailed error information (if available)

Response Examples

{
  "success": true,
  "message": "Project updated successfully",
  "project": {
    "projectName": "Updated Project Name",
    "audioSpeed": 100,
    "videoVolume": 50,
    "scenes": [
      {
        "text": "Updated scene text",
        "sentence": [
          {
            "text": "Updated scene text",
            "highlight": true
          }
        ],
        "settings": {
          "hideText": false
        },
        "background": {
          "type": "image",
          "elementData": {
            "url": "https://new-media-url.com/image.jpg"
          }
        }
      }
    ]
  }
}

{
  "success": false,
  "message": "Invalid project data",
  "error": "Missing required fields"
}

{
  "message": "Unauthorized"
}

{
  "success": false,
  "message": "Project not found"
}

Code Examples

Replace YOUR_API_KEY with your actual API key that starts with pictai_

# First, get the current project
PROJECT_DATA=$(curl --request GET \
  --url 'https://api.pictory.ai/pictoryapis/v2/projects/YOUR_PROJECT_ID' \
  --header 'Authorization: YOUR_API_KEY' \
  --header 'accept: application/json')

# Modify the project data (using jq)
UPDATED_DATA=$(echo $PROJECT_DATA | jq '.projectName = "Updated Name"')

# Send the update
curl --request PUT \
  --url 'https://api.pictory.ai/pictoryapis/v2/projects/YOUR_PROJECT_ID' \
  --header 'Authorization: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data "$UPDATED_DATA"

import requests

project_id = "20251222191648030d7df02f5b4054d4ca8831f1369459e25"
api_key = "YOUR_API_KEY"
headers = {
    "Authorization": api_key,
    "Content-Type": "application/json"
}

# Step 1: Get the current project
get_url = f"https://api.pictory.ai/pictoryapis/v2/projects/{project_id}"
response = requests.get(get_url, headers=headers)
project = response.json()

# Step 2: Modify the project
project['projectName'] = "Updated Project Name"
project['audioSpeed'] = 110

# Step 3: Send the update
put_url = f"https://api.pictory.ai/pictoryapis/v2/projects/{project_id}"
update_response = requests.put(put_url, json=project, headers=headers)
result = update_response.json()

if result.get('success'):
    print("Project updated successfully")
else:
    print(f"Update failed: {result.get('message')}")

const projectId = '20251222191648030d7df02f5b4054d4ca8831f1369459e25';
const apiKey = 'YOUR_API_KEY';
const headers = {
  'Authorization': `${apiKey}`,
  'Content-Type': 'application/json'
};

// Step 1: Get the current project
const getResponse = await fetch(
  `https://api.pictory.ai/pictoryapis/v2/projects/${projectId}`,
  { headers: { ...headers, 'accept': 'application/json' } }
);
const project = await getResponse.json();

// Step 2: Modify the project
project.projectName = 'Updated Project Name';
project.audioSpeed = 110;

// Step 3: Send the update
const updateResponse = await fetch(
  `https://api.pictory.ai/pictoryapis/v2/projects/${projectId}`,
  {
    method: 'PUT',
    headers,
    body: JSON.stringify(project)
  }
);

const result = await updateResponse.json();

if (result.success) {
  console.log('Project updated successfully');
} else {
  console.log(`Update failed: ${result.message}`);
}

Usage Notes

Always Retrieve Before Update: Always fetch the current project state using the GET endpoint before making modifications. This ensures you have the complete object with all required fields.

Complete Object Required: Even if you only want to change one field, you must send the entire project object. Omitting fields will cause them to be removed from the project.

Render After Update: Updating a project only saves the changes to the project data. To generate a new video with your updates, you must call the Render Project endpoint after the update is complete.

Test Changes First: When making significant updates, consider testing on a copy of the project first to ensure your modifications do not cause rendering issues.

Common Use Cases

1. Update Scene Background Visual

Replace the background media for a specific scene:

import requests

def update_scene_background(project_id, scene_index, new_media_url, media_type, api_key):
    """
    Update the background visual for a specific scene

    media_type: "image" or "video"
    """
    headers = {"Authorization": api_key, "Content-Type": "application/json"}

    # Get current project
    get_url = f"https://api.pictory.ai/pictoryapis/v2/projects/{project_id}"
    response = requests.get(get_url, headers=headers)
    project = response.json()

    # Update the scene background
    if scene_index < len(project.get('scenes', [])):
        background = project['scenes'][scene_index].get('background', {})
        background['type'] = media_type
        background['elementData'] = background.get('elementData', {})
        background['elementData']['url'] = new_media_url
        background['elementData']['preview_jpg'] = new_media_url
        background['elementData']['library'] = 'uploads'

        if media_type == 'video':
            background['settings'] = {'loopVideo': True}

        project['scenes'][scene_index]['background'] = background
        print(f"Updated scene {scene_index} background to: {new_media_url}")

        # Send update
        put_url = f"https://api.pictory.ai/pictoryapis/v2/projects/{project_id}"
        update_response = requests.put(put_url, json=project, headers=headers)
        result = update_response.json()

        if result.get('success'):
            print("Project updated successfully")
            return result
        else:
            print(f"Update failed: {result.get('message')}")
            return None
    else:
        print(f"Scene index {scene_index} out of range")
        return None

# Example usage
update_scene_background(
    "YOUR_PROJECT_ID",
    0,  # First scene
    "https://your-media-url.com/new-image.jpg",
    "image",
    "YOUR_API_KEY"
)

2. Update Scene Text

Modify the text and sentence for one or more scenes:

async function updateSceneText(projectId, sceneUpdates, apiKey) {
  const headers = {
    'Authorization': `${apiKey}`,
    'Content-Type': 'application/json'
  };

  // Get current project
  const getResponse = await fetch(
    `https://api.pictory.ai/pictoryapis/v2/projects/${projectId}`,
    { headers }
  );
  const project = await getResponse.json();

  // Update scene text
  sceneUpdates.forEach(({ sceneIndex, newText, keywords }) => {
    if (sceneIndex < project.scenes.length) {
      // Update the text field
      project.scenes[sceneIndex].text = newText;

      // Update sentence array with formatting
      project.scenes[sceneIndex].sentence = [
        {
          text: newText,
          highlight: false,
          decoration: ['decor-bold']
        }
      ];

      // Update keywords if provided
      if (keywords) {
        project.scenes[sceneIndex].keywords = keywords;
      }

      console.log(`Updated scene ${sceneIndex} text`);
    }
  });

  // Send update
  const updateResponse = await fetch(
    `https://api.pictory.ai/pictoryapis/v2/projects/${projectId}`,
    {
      method: 'PUT',
      headers,
      body: JSON.stringify(project)
    }
  );

  const result = await updateResponse.json();
  return result;
}

// Example usage
const updates = [
  { sceneIndex: 0, newText: 'A Stunning Masterpiece', keywords: ['Stunning Masterpiece'] },
  { sceneIndex: 1, newText: 'Sweeping views with year-round sunsets', keywords: ['Sweeping views', 'sunsets'] }
];

const result = await updateSceneText('YOUR_PROJECT_ID', updates, 'YOUR_API_KEY');
console.log('Update result:', result);

3. Update Scene Settings and Element Settings

Apply settings changes to scenes and their elements:

def update_scene_settings(project_id, settings_updates, api_key):
    """
    Apply settings to multiple scenes

    settings_updates: dict with scene indices as keys and settings as values
    Note:
      - scenes[].settings only supports: hideText
      - scenes[].elements[].settings supports: loopVideo, muteClipAudio
      - scenes[].background.settings supports: loopVideo (for video backgrounds)
      - scenes[].background.styleData supports: imageZoomPan

    Example: {
        0: {"hideText": True},
        2: {"hideText": False}
    }
    """
    headers = {"Authorization": api_key, "Content-Type": "application/json"}

    # Get current project
    get_url = f"https://api.pictory.ai/pictoryapis/v2/projects/{project_id}"
    response = requests.get(get_url, headers=headers)
    project = response.json()

    # Update scene settings (only hideText is supported at scene level)
    for scene_index, new_settings in settings_updates.items():
        if scene_index < len(project.get('scenes', [])):
            current_settings = project['scenes'][scene_index].get('settings', {})
            # Only update hideText at scene level
            if 'hideText' in new_settings:
                current_settings['hideText'] = new_settings['hideText']
            project['scenes'][scene_index]['settings'] = current_settings
            print(f"Updated settings for scene {scene_index}")

    # Send update
    put_url = f"https://api.pictory.ai/pictoryapis/v2/projects/{project_id}"
    update_response = requests.put(put_url, json=project, headers=headers)

    return update_response.json()


def update_element_settings(project_id, scene_index, element_index, element_settings, api_key):
    """
    Update settings for a specific video element overlay

    element_settings supports: loopVideo, muteClipAudio
    """
    headers = {"Authorization": api_key, "Content-Type": "application/json"}

    # Get current project
    get_url = f"https://api.pictory.ai/pictoryapis/v2/projects/{project_id}"
    response = requests.get(get_url, headers=headers)
    project = response.json()

    scenes = project.get('scenes', [])
    if scene_index < len(scenes):
        elements = scenes[scene_index].get('elements', [])
        if element_index < len(elements):
            current_settings = elements[element_index].get('settings', {})
            current_settings.update(element_settings)
            project['scenes'][scene_index]['elements'][element_index]['settings'] = current_settings
            print(f"Updated element {element_index} settings in scene {scene_index}")

    # Send update
    put_url = f"https://api.pictory.ai/pictoryapis/v2/projects/{project_id}"
    update_response = requests.put(put_url, json=project, headers=headers)

    return update_response.json()


# Example usage - Update scene settings (hideText only)
scene_settings = {
    0: {"hideText": True},
    2: {"hideText": False}
}
result = update_scene_settings("YOUR_PROJECT_ID", scene_settings, "YOUR_API_KEY")
print(f"Scene settings update successful: {result.get('success')}")

# Example usage - Update video element settings (loopVideo, muteClipAudio)
result = update_element_settings(
    "YOUR_PROJECT_ID",
    scene_index=0,
    element_index=0,
    element_settings={"loopVideo": True, "muteClipAudio": True},
    api_key="YOUR_API_KEY"
)
print(f"Element settings update successful: {result.get('success')}")

4. Update Project Metadata

Change project name and playback settings:

async function updateProjectMetadata(projectId, metadata, apiKey) {
  const headers = {
    'Authorization': `${apiKey}`,
    'Content-Type': 'application/json'
  };

  // Get current project
  const getResponse = await fetch(
    `https://api.pictory.ai/pictoryapis/v2/projects/${projectId}`,
    { headers }
  );
  const project = await getResponse.json();

  // Update metadata
  if (metadata.name) project.projectName = metadata.name;
  if (metadata.audioSpeed) project.audioSpeed = metadata.audioSpeed;
  if (metadata.videoVolume !== undefined) project.videoVolume = metadata.videoVolume;

  console.log('Updated project metadata:', metadata);

  // Send update
  const updateResponse = await fetch(
    `https://api.pictory.ai/pictoryapis/v2/projects/${projectId}`,
    {
      method: 'PUT',
      headers,
      body: JSON.stringify(project)
    }
  );

  return await updateResponse.json();
}

// Example usage
const metadata = {
  name: 'My Updated Project',
  audioSpeed: 105,
  videoVolume: 80
};

const result = await updateProjectMetadata('YOUR_PROJECT_ID', metadata, 'YOUR_API_KEY');
console.log('Result:', result);

5. Replace All Scene Backgrounds

Replace backgrounds for all scenes at once:

def replace_all_backgrounds(project_id, media_items, api_key):
    """
    Replace background media for all scenes

    media_items: list of dicts with 'url' and 'type' keys
    Example: [
        {"url": "https://example.com/image1.jpg", "type": "image"},
        {"url": "https://example.com/video1.mp4", "type": "video"},
    ]
    """
    headers = {"Authorization": api_key, "Content-Type": "application/json"}

    # Get current project
    get_url = f"https://api.pictory.ai/pictoryapis/v2/projects/{project_id}"
    response = requests.get(get_url, headers=headers)
    project = response.json()

    scenes = project.get('scenes', [])

    if len(media_items) != len(scenes):
        print(f"Warning: {len(media_items)} items provided for {len(scenes)} scenes")
        return None

    # Update all scene backgrounds
    for i, media in enumerate(media_items):
        background = scenes[i].get('background', {})
        background['type'] = media['type']
        background['elementData'] = background.get('elementData', {})
        background['elementData']['url'] = media['url']
        background['elementData']['preview_jpg'] = media['url']
        background['elementData']['library'] = 'uploads'

        if media['type'] == 'video':
            background['settings'] = {'loopVideo': True}
            background['elementData']['duration'] = media.get('duration', 10)

        scenes[i]['background'] = background
        print(f"Scene {i}: {media['url']} ({media['type']})")

    project['scenes'] = scenes

    # Send update
    put_url = f"https://api.pictory.ai/pictoryapis/v2/projects/{project_id}"
    update_response = requests.put(put_url, json=project, headers=headers)

    return update_response.json()

# Example usage
new_backgrounds = [
    {"url": "https://media-url.com/scene1.jpg", "type": "image"},
    {"url": "https://media-url.com/scene2.mp4", "type": "video", "duration": 15},
    {"url": "https://media-url.com/scene3.jpg", "type": "image"}
]

result = replace_all_backgrounds("YOUR_PROJECT_ID", new_backgrounds, "YOUR_API_KEY")
if result and result.get('success'):
    print("All backgrounds updated successfully")

6. Safe Update with Validation

Implement validation before updating:

import copy

def safe_update_project(project_id, update_function, api_key):
    """
    Safely update project with validation

    update_function: function that takes project dict and modifies it
    """
    headers = {"Authorization": api_key, "Content-Type": "application/json"}

    # Get current project
    get_url = f"https://api.pictory.ai/pictoryapis/v2/projects/{project_id}"
    response = requests.get(get_url, headers=headers)

    if response.status_code != 200:
        print("Failed to fetch project")
        return None

    original_project = response.json()
    updated_project = copy.deepcopy(original_project)

    # Apply updates
    try:
        update_function(updated_project)
    except Exception as e:
        print(f"Error applying updates: {e}")
        return None

    # Validate critical fields are present
    required_fields = ['projectName', 'scenes', 'schemaVersion']
    for field in required_fields:
        if field not in updated_project:
            print(f"Critical field '{field}' missing after update")
            return None

    # Send update
    put_url = f"https://api.pictory.ai/pictoryapis/v2/projects/{project_id}"
    update_response = requests.put(put_url, json=updated_project, headers=headers)

    result = update_response.json()

    if result.get('success'):
        print("Project updated successfully")
    else:
        print(f"Update failed: {result.get('message')}")

    return result

# Example usage
def my_updates(project):
    """Define your updates here"""
    project['projectName'] = 'New Name'
    project['audioSpeed'] = 95

    # Hide text for first scene (scenes[].settings.hideText)
    if project['scenes']:
        if 'settings' not in project['scenes'][0]:
            project['scenes'][0]['settings'] = {}
        project['scenes'][0]['settings']['hideText'] = True

    # Mute audio for first video element (elements[].settings.muteClipAudio)
    if project['scenes'] and project['scenes'][0].get('elements'):
        element = project['scenes'][0]['elements'][0]
        if element.get('type') == 'video':
            if 'settings' not in element:
                element['settings'] = {}
            element['settings']['muteClipAudio'] = True

result = safe_update_project("YOUR_PROJECT_ID", my_updates, "YOUR_API_KEY")

Best Practices

Safety Guidelines

Always Fetch First: Get the current project state before making any modifications
Preserve All Fields: Include all fields in the update request, even if unchanged
Test on Copies: Test significant changes on duplicate projects first
Validate Before Sending: Ensure all required fields are present before updating
Keep Backups: Save the original project state before applying updates

Common Pitfalls to Avoid

❌ Partial Updates: Sending only modified fields will delete other fields
❌ Missing Required Fields: Omitting critical fields causes project corruption
❌ Invalid Values: Using incorrect data types or formats for fields
❌ Modifying System Fields: Changing internal IDs or metadata
❌ No Validation: Updating without checking the project state first

Performance Tips

Batch multiple changes in a single update request
Minimize the frequency of updates during active editing
Cache the project object locally during editing sessions
Only fetch/update when necessary to reduce API calls

Get Project by ID Delete Project

⌘I

​Overview

​API Endpoint

​Request Parameters

​Path Parameters

​Headers

​Request Body

​Updatable Video Elements

​Project-Level Fields

​Scene Text (scenes[].text and scenes[].sentence)

​Scene Text Styling (scenes[].styleData)

​Scene Settings (scenes[].settings)

​Background Image (scenes[].background with type: "image")

​Background Video (scenes[].background with type: "video")

​Solid Color Background (scenes[].background with type: "solid")

​Video Element Overlay (scenes[].elements[] with type: "video")

​Text Element Overlay (scenes[].elements[] with type: "text")

​Quick Reference: Safe Updates

​Fields to Avoid Modifying

​Response

​Response Examples

​Code Examples

​Usage Notes

​Common Use Cases

​1. Update Scene Background Visual

​2. Update Scene Text

​3. Update Scene Settings and Element Settings

​4. Update Project Metadata

​5. Replace All Scene Backgrounds

​6. Safe Update with Validation

​Best Practices

​Safety Guidelines

​Common Pitfalls to Avoid

​Performance Tips

Overview

API Endpoint

Request Parameters

Path Parameters

Headers

Request Body

Updatable Video Elements

Project-Level Fields

Scene Text (`scenes[].text` and `scenes[].sentence`)

Scene Text Styling (`scenes[].styleData`)

Scene Settings (`scenes[].settings`)

Background Image (`scenes[].background` with `type: "image"`)

Background Video (`scenes[].background` with `type: "video"`)

Solid Color Background (`scenes[].background` with `type: "solid"`)

Video Element Overlay (`scenes[].elements[]` with `type: "video"`)

Text Element Overlay (`scenes[].elements[]` with `type: "text"`)

Quick Reference: Safe Updates

Fields to Avoid Modifying

Response

Response Examples

Code Examples

Usage Notes

Common Use Cases

1. Update Scene Background Visual

2. Update Scene Text

3. Update Scene Settings and Element Settings

4. Update Project Metadata

5. Replace All Scene Backgrounds

6. Safe Update with Validation

Best Practices

Safety Guidelines

Common Pitfalls to Avoid

Performance Tips