What is the Pirsonal Video API?

The Pirsonal Video API is a cloud-based JSON-RPC 2.0 API that lets developers generate personalized videos, dynamic landing pages, and interactive player experiences automatically from templates using real-time data from CRMs, web forms, and marketing platforms.

How does Pirsonal generate personalized landing pages?

Alongside raw MP4 video files, Pirsonal automatically generates responsive video landing pages (hosted at vid.pirsonal.com/v/{videoID} or custom CNAME domains) complete with custom branding, headlines, social sharing cards, and interactive player CTAs timed to specific seconds in the video.

What protocol and authentication does the Pirsonal API use?

The API uses standard JSON-RPC 2.0 over HTTPS POST. Requests are authenticated using Account ID and Account Secret credentials passed as URL query parameters over TLS (http://app.pirsonal.com/api?accountID=...&accountSecret=...).

Can I test the Pirsonal Video API without credentials or rendering costs?

Yes. The interactive documentation sandbox includes a built-in Mock Simulation Mode that simulates authentic JSON-RPC responses for all 17 API methods instantly with zero API cost and no account keys required.

How do completion webhooks work in Pirsonal?

Because personalized video rendering is asynchronous, you can supply a callback URL when queuing a video. When rendering succeeds or fails, Pirsonal dispatches an HTTP POST webhook with event 'video.rendered', the video status, output MP4 URLs, and the personalized landing page link.

Pirsonal Video API Reference

The Pirsonal API provides programmatic control over personalized video generation, dynamic audio/text/image composition, rendering pipelines, and media assets. It uses standard JSON-RPC 2.0 over HTTPS POST, allowing zero-dependency consumption via native HTTP clients (cURL, fetch, requests) or contract-driven Barrister SDKs.

🔑 Authentication & Security

All requests to http://app.pirsonal.com/api and http://app.pirsonal.com/api/upload require authentication via URL query parameters over HTTPS (TLS encryption):

1. Account Authentication (Standard)

http://app.pirsonal.com/api?accountID=YOUR_ACCOUNT_ID&accountSecret=YOUR_ACCOUNT_SECRET

Grants full access to all account templates, media assets, and video generation operations.

2. Template Key Authentication (Restricted)

http://app.pirsonal.com/api?accountID=...&templateID=...&templateSecret=...

Scoped access restricted exclusively to generating videos from a specific template without sharing your master secret.

💡 Core Concept: videoID vs pirsonalID

Understanding the distinction between a videoID and a pirsonalID is essential when working with the Pirsonal API:

videoID Personalized Video Project

The unique 24-character hexadecimal identifier assigned to an entire individual personalized video rendering job (e.g. 543210fe810c19729de860ea).

Used in queries: Video_Get(videoID), Video_Delete(videoID)
Used in public landing page URLs: https://vid.pirsonal.com/v/{videoID}
Contains metadata, CTA settings, and one or more rendered video files (outFiles).

pirsonalID Storage Asset Key

The storage identifier or cloud blob key assigned to an uploaded raw media asset or an encoded output video file in Pirsonal cloud storage.

Used in inputMedias: { inputID: "image1", type: "image", pirsonalID: "..." }
Returned by Media_Upload and Media_List
Stored in outFiles[].storage.pirsonalID representing the physical MP4 artifact.

🧪 API Test Console Interactive Playground

Mock Simulation Mode (Zero rendering credits & no credentials required)

Select any Pirsonal JSON-RPC method, inspect or modify the JSON request payload, and execute directly against the active endpoint (http://app.pirsonal.com/api) or simulate authentic responses in Mock Mode.

🧪 Mock Simulation Active: Test any method with realistic simulated JSON-RPC responses. Zero API cost and no account keys needed. Uncheck the box above to enter your credentials and run live requests against your account.

Account ID

Account Secret

Active API Endpoint

Method to Test:

Request JSON-RPC (Editable) Clean params (No form required)

Response

Ready

● Awaiting execution

Click "▶ Execute API Request" above to test the method.

API Methods

PREFERRED LANGUAGE:

📐 Templates

Programmatically construct, update, activate, and list personalized video templates. Templates establish the motion timeline, visual layouts, and dynamic media placeholders.

POST PirsonalAPI.Template_New

Template Definition

Creates a new personalized video template defining the motion timeline, visual layouts, dynamic media placeholders, audio tracks, and output video encoding profiles. Returns the newly assigned templateID.

Parameters

Parameter	Type	Description
templaterequired	TemplateNew_t	Object containing template configuration, script timeline, and placeholder definitions.

TemplateNew_t Fields

namerequired	string	Descriptive template name (max 200 characters).
videoOutputrequired	VideoOutput_t	Output configuration container, e.g. `{ "type": "pirsonal" }`.
outProfilesoptional	Array<string>	Output rendering profiles, e.g. `["MP4_H264_AAC_1280x720_24fps"]`. If custom profiles are defined on the template, you MUST specify that custom profile's explicit name here (see note below).
customProfilesoptional	Array<VideoProfile>	Custom video rendering profiles with specific bitrate, resolution, framerate, and audio settings.
descriptionoptional	string	Optional description of the template purpose (max 1000 characters).
inputScriptsoptional	Array<string>	Pirsonal Script JSON strings defining objects, layers, transitions, and timing.
inputMediasoptional	Array<Media_t>	Initial dynamic placeholder media declarations (text, image, audio, video).
webhookoptional	WebHook_t	Optional default completion webhook: { url, auth: "none"\|"basic"\|"digest" }.
GATrackingCodeoptional	string	Optional Google Analytics measurement ID for landing page viewer tracking.

⚠️ Important: Custom Profiles & Cloud Storage File Naming Rules

Using Custom Profiles in outProfiles: If you define custom rendering profiles in customProfiles, you MUST explicitly specify that custom profile's exact name in the outProfiles array (e.g. ["MyCustom720p"]). Do not pass the system default profile (MP4_H264_AAC_1280x720_24fps) if your template relies on custom profiles. The video rendering worker will generate the file using the custom profile name you declared.
Storage Output File Naming Disparity (Azure vs. Amazon S3): The resulting filename and object key differs depending on your designated storage provider:
- Pirsonal Cloud / Azure Storage (videoOutput.type: "pirsonal"): Files are stored with a single extension in the format <videoID>.<profile>.<ext> (e.g. 533155ec0fa92a6755582c8e.MyCustom720p.mp4; inside the container at <accountID>/<videoID>.<profile>.mp4).
- Amazon S3 Storage (videoOutput.type: "awsS3"): Due to background worker filename assembly, output files uploaded to S3 retain a double extension: <videoID>.<profile>.<ext>.<ext> (e.g. 533155ec0fa92a6755582c8e.MyCustom720p.mp4.mp4). S3 URLs, storage.awsS3.key in webhooks, and Video_Get_Links return this exact key. External systems and webhooks processing S3 objects must expect this double extension.

Returns

Returns a string representing the new templateID (e.g. "533155ec0fa92a6755582c8e").

cURL
Node.js
Python
PHP
Barrister RPC

curl -X POST "http://app.pirsonal.com/api?accountID=YOUR_ACCOUNT_ID&accountSecret=YOUR_ACCOUNT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": "1",
    "method": "PirsonalAPI.Template_New",
    "params": [{
      "name": "Personalized Customer Onboarding",
      "description": "Dynamic onboarding greeting with personalized name and customer logo",
      "videoOutput": { "type": "pirsonal" },
      "outProfiles": ["MP4_H264_AAC_1280x720_24fps"],
      "inputScripts": ["[{\"video\":{\"id\":\"video1\",\"play\":0,\"duration\":5000}}]"]
    }]
  }'

const accountID = "YOUR_ACCOUNT_ID";
const accountSecret = "YOUR_ACCOUNT_SECRET";

async function main() {
  const response = await fetch(`http://app.pirsonal.com/api?accountID=${accountID}&accountSecret=${accountSecret}`, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      jsonrpc: "2.0",
      id: "1",
      method: "PirsonalAPI.Template_New",
      params: [{
        name: "Personalized Customer Onboarding",
        description: "Dynamic onboarding greeting with personalized name and customer logo",
        videoOutput: { type: "pirsonal" },
        outProfiles: ["MP4_H264_AAC_1280x720_24fps"],
        inputScripts: [
          JSON.stringify([
            { video: { id: "video1", play: 0, duration: 5000 } }
          ])
        ]
      }]
    })
  });

  const data = await response.json();
  if (data.error) throw new Error(`API Error [${data.error.code}]: ${data.error.message}`);
  console.log("Created Template ID:", data.result);
}

main().catch(console.error);

import requests

account_id = "YOUR_ACCOUNT_ID"
account_secret = "YOUR_ACCOUNT_SECRET"

payload = {
    "jsonrpc": "2.0",
    "id": "1",
    "method": "PirsonalAPI.Template_New",
    "params": [{
        "name": "Personalized Customer Onboarding",
        "description": "Dynamic onboarding greeting with customer logo",
        "videoOutput": {"type": "pirsonal"},
        "outProfiles": ["MP4_H264_AAC_1280x720_24fps"],
        "inputScripts": ['[{"video":{"id":"video1","play":0,"duration":5000}}]']
    }]
}

response = requests.post(
    "http://app.pirsonal.com/api",
    params={"accountID": account_id, "accountSecret": account_secret},
    headers={"Content-Type": "application/json"},
    json=payload
)

data = response.json()
if "error" in data:
    raise Exception(f"API Error [{data['error']['code']}]: {data['error']['message']}")
print("Created Template ID:", data["result"])

<?php
$accountID = "YOUR_ACCOUNT_ID";
$accountSecret = "YOUR_ACCOUNT_SECRET";

$payload = [
    "jsonrpc" => "2.0",
    "id" => "1",
    "method" => "PirsonalAPI.Template_New",
    "params" => [[
        "name" => "Personalized Customer Onboarding",
        "description" => "Dynamic onboarding greeting",
        "videoOutput" => ["type" => "pirsonal"],
        "outProfiles" => ["MP4_H264_AAC_1280x720_24fps"],
        "inputScripts" => [json_encode([["video" => ["id" => "video1", "play" => 0, "duration" => 5000]]])]
    ]]
];

$ch = curl_init("http://app.pirsonal.com/api?accountID={$accountID}&accountSecret={$accountSecret}");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => json_encode($payload),
    CURLOPT_HTTPHEADER => [
        "Content-Type: application/json",
    ]
]);

$response = curl_exec($ch);
curl_close($ch);

$result = json_decode($response, true);
echo "Created Template ID: " . $result["result"] . "\n";
?>

const barrister = require('barrister');

const client = barrister.httpClient("http://app.pirsonal.com/api?accountID=YOUR_ID&accountSecret=YOUR_SECRET");
client.loadContract(function(err) {
  if (err) throw err;
  const pirsonal = client.proxy("PirsonalAPI");
  pirsonal.Template_New({
    name: "Personalized Customer Onboarding",
    description: "Dynamic onboarding greeting",
    videoOutput: { type: "pirsonal" },
    outProfiles: ["MP4_H264_AAC_1280x720_24fps"],
    inputScripts: [JSON.stringify([{ video: { id: "video1", play: 0, duration: 5000 } }])]
  }, function(err, templateID) {
    if (err) console.error("RPC Error:", err);
    else console.log("Created Template ID:", templateID);
  });
});

Execute or simulate Template_New

POST PirsonalAPI.Template_Update

Template Mutation

Modifies existing template configuration such as template title, description, attached Pirsonal Script timeline, output video profiles, default placeholder inputs, or webhook endpoints.

Parameters

Parameter	Type	Description
templateIDrequired	string	Unique 24-character hexadecimal template ID to update.
updaterequired	TemplateUpdate_t	Object containing updated fields (e.g. name, description, script, webhook, outProfiles, customProfiles).

TemplateUpdate_t Fields

nameoptional	string	Updated title for the template (max 200 characters).
videoOutputoptional	VideoOutput_t	Updated output destination, e.g. `{ "type": "pirsonal" }` or `{ "type": "awsS3", "awsS3Bucket": "my-bucket" }`.
outProfilesoptional	Array<string>	Updated array of rendering profile identifiers. If using custom profiles, specify the exact custom profile name (see note below).
customProfilesoptional	Array<VideoProfile>	Updated array of custom rendering profile specifications.
inputScriptsoptional	Array<string>	Updated Pirsonal Script JSON timeline definitions.
webhookoptional	WebHook_t	Updated completion callback webhook configuration.

⚠️ Important: Custom Profiles & Storage Naming Rules

Custom Profile Matching: When defining custom profiles in customProfiles, callers MUST specify that custom profile's exact name in outProfiles. The rendering system names and encodes the output file according to that explicit profile name.
Azure vs. AWS S3 File Naming: Output videos on Pirsonal/Azure are stored as <videoID>.<profile>.mp4 (single extension). Output videos uploaded to Amazon S3 retain a double extension: <videoID>.<profile>.mp4.mp4. External services fetching S3 objects or receiving webhooks must account for this double extension.

Returns

Returns string "OK" upon successful update.

cURL
Node.js
Python
PHP
Barrister RPC

curl -X POST "http://app.pirsonal.com/api?accountID=YOUR_ACCOUNT_ID&accountSecret=YOUR_ACCOUNT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": "1",
    "method": "PirsonalAPI.Template_Update",
    "params": [
      "533155ec0fa92a6755582c8e",
      { "name": "Updated Customer Onboarding 2026" }
    ]
  }'

const accountID = "YOUR_ACCOUNT_ID";
const accountSecret = "YOUR_ACCOUNT_SECRET";
const templateID = "533155ec0fa92a6755582c8e";

async function main() {
  const response = await fetch(`http://app.pirsonal.com/api?accountID=${accountID}&accountSecret=${accountSecret}`, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      jsonrpc: "2.0",
      id: "1",
      method: "PirsonalAPI.Template_Update",
      params: [templateID, { name: "Updated Customer Onboarding 2026" }]
    })
  });

  const data = await response.json();
  console.log("Update status:", data.result); // "OK"
}

main().catch(console.error);

import requests

account_id = "YOUR_ACCOUNT_ID"
account_secret = "YOUR_ACCOUNT_SECRET"
template_id = "533155ec0fa92a6755582c8e"

payload = {
    "jsonrpc": "2.0",
    "id": "1",
    "method": "PirsonalAPI.Template_Update",
    "params": [template_id, {"name": "Updated Customer Onboarding 2026"}]
}

response = requests.post(
    "http://app.pirsonal.com/api",
    params={"accountID": account_id, "accountSecret": account_secret},
    json=payload
)
print("Update status:", response.json()["result"])

 "2.0",
    "id" => "1",
    "method" => "PirsonalAPI.Template_Update",
    "params" => ["533155ec0fa92a6755582c8e", ["name" => "Updated Customer Onboarding 2026"]]
];

$ch = curl_init("http://app.pirsonal.com/api?accountID={$accountID}&accountSecret={$accountSecret}");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => json_encode($payload),
    CURLOPT_HTTPHEADER => ["Content-Type: application/json"]
]);
$response = curl_exec($ch);
curl_close($ch);
echo json_decode($response, true)["result"] . "\n";
?>

const barrister = require('barrister');

const client = barrister.httpClient("http://app.pirsonal.com/api?accountID=YOUR_ACCOUNT_ID&accountSecret=YOUR_ACCOUNT_SECRET");
client.loadContract(function(err) {
  if (err) throw err;
  const pirsonal = client.proxy("PirsonalAPI");
  pirsonal.Template_Update("533155ec0fa92a6755582c8e", {
    name: "Updated Customer Onboarding 2026"
  }, function(err, result) {
    if (err) throw err;
    console.log("Update status:", result);
  });
});

Execute or simulate Template_Update

POST PirsonalAPI.Template_SetStatus

Lifecycle State

Sets the operational status of a template to either "active" or "inactive". When inactive, requests to generate videos will be rejected with error code 1028 (Template inactive), safeguarding against unintended rendering usage.

Parameters

Parameter	Type	Description
templateIDrequired	string	Unique 24-character hexadecimal template ID.
statusrequired	string ("active" \| "inactive")	Target lifecycle status for the template.

Returns

Returns string "OK" upon status change.

cURL
Node.js
Python
PHP
Barrister RPC

curl -X POST "http://app.pirsonal.com/api?accountID=YOUR_ACCOUNT_ID&accountSecret=YOUR_ACCOUNT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": "1",
    "method": "PirsonalAPI.Template_SetStatus",
    "params": ["533155ec0fa92a6755582c8e", "active"]
  }'

const accountID = "YOUR_ACCOUNT_ID";
const accountSecret = "YOUR_ACCOUNT_SECRET";

async function main() {
  const response = await fetch(`http://app.pirsonal.com/api?accountID=${accountID}&accountSecret=${accountSecret}`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      jsonrpc: "2.0",
      id: "1",
      method: "PirsonalAPI.Template_SetStatus",
      params: ["533155ec0fa92a6755582c8e", "active"]
    })
  });
  const data = await response.json();
  console.log("Status update:", data.result);
}

main().catch(console.error);

import requests

res = requests.post("http://app.pirsonal.com/api", params={"accountID": "YOUR_ID", "accountSecret": "YOUR_SECRET"}, json={
    "jsonrpc": "2.0", "id": "1", "method": "PirsonalAPI.Template_SetStatus", "params": ["533155ec0fa92a6755582c8e", "active"]
})
print("Result:", res.json()["result"])

 true,
    CURLOPT_POSTFIELDS => json_encode([
        "jsonrpc" => "2.0", "id" => "1", "method" => "PirsonalAPI.Template_SetStatus", "params" => ["533155ec0fa92a6755582c8e", "active"]
    ]),
    CURLOPT_HTTPHEADER => ["Content-Type: application/json"]
]);
echo json_decode(curl_exec($ch), true)["result"] . "\n";
curl_close($ch);
?>

const barrister = require('barrister');

const client = barrister.httpClient("http://app.pirsonal.com/api?accountID=YOUR_ACCOUNT_ID&accountSecret=YOUR_ACCOUNT_SECRET");
client.loadContract(function(err) {
  if (err) throw err;
  const pirsonal = client.proxy("PirsonalAPI");
  pirsonal.Template_SetStatus("533155ec0fa92a6755582c8e", "active", function(err, result) {
    if (err) console.error(err);
    else console.log("Result:", result);
  });
});

Execute or simulate Template_SetStatus

POST PirsonalAPI.Template_Delete

Permanent Removal

Permanently deletes a template from your account and marks all associated videos as deleted. Video files hosted on Pirsonal cloud storage are purged automatically. Set removeExternalFiles to true if you also want Pirsonal to delete videos published to external distribution platforms (such as connected YouTube accounts). Note that Pirsonal does not delete files from customer-owned external cloud storage.

Parameters

Parameter	Type	Description
templateIDrequired	string	Unique 24-character hexadecimal template ID to delete.
removeExternalFilesrequired	boolean	Pass `true` to also delete videos published to external platforms (such as connected YouTube channels), or `false` to keep them on external channels. Videos on Pirsonal storage are purged automatically.

Returns

Returns string "OK" upon deletion.

cURL
Node.js
Python
PHP
Barrister RPC

curl -X POST "http://app.pirsonal.com/api?accountID=YOUR_ACCOUNT_ID&accountSecret=YOUR_ACCOUNT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": "1",
    "method": "PirsonalAPI.Template_Delete",
    "params": ["533155ec0fa92a6755582c8e", false]
  }'

const accountID = "YOUR_ACCOUNT_ID";
const accountSecret = "YOUR_ACCOUNT_SECRET";

async function main() {
  const response = await fetch(`http://app.pirsonal.com/api?accountID=${accountID}&accountSecret=${accountSecret}`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      jsonrpc: "2.0",
      id: "1",
      method: "PirsonalAPI.Template_Delete",
      params: ["533155ec0fa92a6755582c8e", false]
    })
  });
  const data = await response.json();
  console.log("Delete status:", data.result);
}

main().catch(console.error);

import requests

res = requests.post("http://app.pirsonal.com/api", params={"accountID": "YOUR_ID", "accountSecret": "YOUR_SECRET"}, json={
    "jsonrpc": "2.0", "id": "1", "method": "PirsonalAPI.Template_Delete", "params": ["533155ec0fa92a6755582c8e", False]
})
print("Result:", res.json()["result"])

 true,
    CURLOPT_POSTFIELDS => json_encode([
        "jsonrpc" => "2.0", "id" => "1", "method" => "PirsonalAPI.Template_Delete", "params" => ["533155ec0fa92a6755582c8e", false]
    ]),
    CURLOPT_HTTPHEADER => ["Content-Type: application/json"]
]);
echo json_decode(curl_exec($ch), true)["result"] . "\n";
curl_close($ch);
?>

const barrister = require('barrister');

const client = barrister.httpClient("http://app.pirsonal.com/api?accountID=YOUR_ACCOUNT_ID&accountSecret=YOUR_ACCOUNT_SECRET");
client.loadContract(function(err) {
  if (err) throw err;
  const pirsonal = client.proxy("PirsonalAPI");
  pirsonal.Template_Delete("533155ec0fa92a6755582c8e", false, function(err, result) {
    if (err) console.error(err);
    else console.log("Result:", result);
  });
});

Execute or simulate Template_Delete

POST PirsonalAPI.Template_List

Template Catalog

Retrieves an array of all personalized video templates created under your account, including their unique template IDs, names, active/inactive statuses, input placeholder declarations, and creation timestamps.

Parameters

Parameter	Type	Description
This method takes no parameters (`params: []`).

Returns

Returns an array of Template_t objects.

cURL
Node.js
Python
PHP
Barrister RPC

curl -X POST "http://app.pirsonal.com/api?accountID=YOUR_ACCOUNT_ID&accountSecret=YOUR_ACCOUNT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": "1",
    "method": "PirsonalAPI.Template_List",
    "params": []
  }'

const accountID = "YOUR_ACCOUNT_ID";
const accountSecret = "YOUR_ACCOUNT_SECRET";

async function main() {
  const response = await fetch(`http://app.pirsonal.com/api?accountID=${accountID}&accountSecret=${accountSecret}`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      jsonrpc: "2.0",
      id: "1",
      method: "PirsonalAPI.Template_List",
      params: []
    })
  });
  const data = await response.json();
  console.log("Account Templates:", data.result);
}

main().catch(console.error);

import requests

res = requests.post("http://app.pirsonal.com/api", params={"accountID": "YOUR_ID", "accountSecret": "YOUR_SECRET"}, json={
    "jsonrpc": "2.0", "id": "1", "method": "PirsonalAPI.Template_List", "params": []
})
print("Templates count:", len(res.json()["result"]))

 true,
    CURLOPT_POSTFIELDS => json_encode(["jsonrpc" => "2.0", "id" => "1", "method" => "PirsonalAPI.Template_List", "params" => []]),
    CURLOPT_HTTPHEADER => ["Content-Type: application/json"]
]);
print_r(json_decode(curl_exec($ch), true)["result"]);
curl_close($ch);
?>

const barrister = require('barrister');

const client = barrister.httpClient("http://app.pirsonal.com/api?accountID=YOUR_ACCOUNT_ID&accountSecret=YOUR_ACCOUNT_SECRET");
client.loadContract(function(err) {
  if (err) throw err;
  const pirsonal = client.proxy("PirsonalAPI");
  pirsonal.Template_List(function(err, templates) {
    if (err) console.error(err);
    else console.log("Templates:", templates);
  });
});

Execute or simulate Template_List

🎬 Video Rendering

Generate individual personalized videos asynchronously. Pirsonal produces dual deliverables for every execution: high-resolution MP4/HLS video files AND responsive Personalized Video Landing Pages (hosted at vid.pirsonal.com or custom CNAME) featuring interactive video player CTAs and conversion tracking.

POST PirsonalAPI.Template_Video_New

Asynchronous Rendering

Queues a new personalized video from an existing template by supplying dynamic text, image, audio, or video inputs. Pirsonal renders high-definition MP4/HLS video files and automatically publishes a mobile-responsive Personalized Video Landing Page with interactive player CTAs. Returns the newly queued videoID immediately.

Parameters

Parameter	Type	Description
templateIDrequired	string	The unique 24-character hexadecimal template ID to instantiate.
videorequired	Video_t (Object)	Object containing video metadata, dynamic input variables, landing info, and callback webhook.

Video_t Fields

nameoptional	string	Descriptive title for the video instance (e.g. "Welcome John Doe").
inputMediasrequired	Array	Dynamic values for media placeholders defined in the template (text, audio URL, image URL, or video URL).
playerInfooptional	PlayerInfo_t	Interactive player configuration: `{ CTAType: "text", CTABodyText: "Special Offer", CTAButtonText: "Claim Offer", CTAButtonUrl: "https://...", CTAStartTime: 5 }` (valid CTAType: "text", "html", "none").
landingInfooptional	LandingInfo_t	Personalized landing page branding: `{ logoImageUrl: "https://...", bannerImageUrl: "https://...", cname: "video.company.com" }`.
dataoptional	string	Custom tracking metadata or identifier echoed in the template completion webhook payload.
videoOutputoptional	VideoOutput_t	Optional output storage destination override for this video execution: `{ type: "pirsonal" }` or `{ type: "awsS3", awsS3Bucket: "my-bucket" }`.

ℹ️ Output Profiles & Storage File Naming

Rendered videos inherit the output profile(s) configured on the parent template. If the template uses custom profiles, it renders under that custom profile's explicit name. When outputting to Pirsonal Cloud / Azure Storage, files are saved as <videoID>.<profile>.mp4. When outputting to Amazon S3, files are stored with a double extension: <videoID>.<profile>.mp4.mp4. Webhook payloads, S3 URLs, and Video_Get_Links return this exact key.

Returns

Returns a string representing the unique videoID (e.g. "543210fe810c19729de860ea").

cURL
Node.js
Python
PHP
Barrister RPC

curl -X POST "http://app.pirsonal.com/api?accountID=YOUR_ACCOUNT_ID&accountSecret=YOUR_ACCOUNT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": "1",
    "method": "PirsonalAPI.Template_Video_New",
    "params": [
      "533155ec0fa92a6755582c8e",
      {
        "name": "Campaign - John Doe",
        "inputMedias": [
          { "inputID": "text1", "type": "text", "text": "John Doe" },
          { "inputID": "company_logo", "type": "image", "http": "https://example.com/logo.png" }
        ],
        "data": "user_id_98765"
      }
    ]
  }'

const accountID = "YOUR_ACCOUNT_ID";
const accountSecret = "YOUR_ACCOUNT_SECRET";
const templateID = "533155ec0fa92a6755582c8e";

async function main() {
  const payload = {
    jsonrpc: "2.0",
    id: "1",
    method: "PirsonalAPI.Template_Video_New",
    params: [
      templateID,
      {
        name: "Campaign - John Doe",
        inputMedias: [
          { inputID: "text1", type: "text", text: "John Doe" },
          { inputID: "company_logo", type: "image", http: "https://example.com/logo.png" }
        ],
        data: "user_id_98765"
      }
    ]
  };

  const response = await fetch(`http://app.pirsonal.com/api?accountID=${accountID}&accountSecret=${accountSecret}`, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
    },
    body: JSON.stringify(payload)
  });

  const result = await response.json();
  console.log("Queued Video ID:", result.result);
}

main().catch(console.error);

import requests

account_id = "YOUR_ACCOUNT_ID"
account_secret = "YOUR_ACCOUNT_SECRET"
template_id = "533155ec0fa92a6755582c8e"

payload = {
    "jsonrpc": "2.0",
    "id": "1",
    "method": "PirsonalAPI.Template_Video_New",
    "params": [
        template_id,
        {
            "name": "Campaign - John Doe",
            "inputMedias": [
                {"inputID": "text1", "type": "text", "text": "John Doe"},
                {"inputID": "company_logo", "type": "image", "http": "https://example.com/logo.png"}
            ],
            "data": "user_id_98765"
        }
    ]
}

response = requests.post(
    "http://app.pirsonal.com/api",
    params={"accountID": account_id, "accountSecret": account_secret},
    json=payload
)
print("Queued Video ID:", response.json()["result"])

 "2.0",
    "id" => "1",
    "method" => "PirsonalAPI.Template_Video_New",
    "params" => [
        "533155ec0fa92a6755582c8e",
        [
            "name" => "Campaign - John Doe",
            "inputMedias" => [
                ["inputID" => "text1", "type" => "text", "text" => "John Doe"],
                ["inputID" => "company_logo", "type" => "image", "http" => "https://example.com/logo.png"]
            ],
            "data" => "user_id_98765"
        ]
    ]
];

$ch = curl_init("http://app.pirsonal.com/api?accountID={$accountID}&accountSecret={$accountSecret}");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => json_encode($payload),
    CURLOPT_HTTPHEADER => ["Content-Type: application/json"]
]);
$result = json_decode(curl_exec($ch), true);
curl_close($ch);
echo "Queued Video ID: " . $result["result"] . "\n";
?>

const barrister = require('barrister');

const client = barrister.httpClient("http://app.pirsonal.com/api?accountID=YOUR_ACCOUNT_ID&accountSecret=YOUR_ACCOUNT_SECRET");
client.loadContract(function(err) {
  if (err) throw err;
  const pirsonal = client.proxy("PirsonalAPI");
  pirsonal.Template_Video_New("533155ec0fa92a6755582c8e", {
    name: "Campaign - John Doe",
    inputMedias: [
      { inputID: "text1", type: "text", text: "John Doe" },
      { inputID: "company_logo", type: "image", http: "https://example.com/logo.png" }
    ]
  }, function(err, videoID) {
    if (err) console.error(err);
    else console.log("Video ID:", videoID);
  });
});

Execute or simulate Template_Video_New

POST PirsonalAPI.Template_Video_List

Batch Query

Retrieves an array of all personalized videos generated from a specific template, including their rendering statuses (waiting, processing, done, error), percentage progress, creation dates, and rendered media URLs.

Parameters

Parameter	Type	Description
templateIDrequired	string	The unique 24-character hexadecimal template ID.

Returns

Returns an array of VideoInfo_t objects.

cURL
Node.js
Python
PHP
Barrister RPC

curl -X POST "http://app.pirsonal.com/api?accountID=YOUR_ACCOUNT_ID&accountSecret=YOUR_ACCOUNT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": "1",
    "method": "PirsonalAPI.Template_Video_List",
    "params": ["533155ec0fa92a6755582c8e"]
  }'

const accountID = "YOUR_ACCOUNT_ID";
const accountSecret = "YOUR_ACCOUNT_SECRET";

async function main() {
  const response = await fetch(`http://app.pirsonal.com/api?accountID=${accountID}&accountSecret=${accountSecret}`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      jsonrpc: "2.0",
      id: "1",
      method: "PirsonalAPI.Template_Video_List",
      params: ["533155ec0fa92a6755582c8e"]
    })
  });
  const data = await response.json();
  console.log("Rendered Videos:", data.result);
}

main().catch(console.error);

import requests

res = requests.post("http://app.pirsonal.com/api", params={"accountID": "YOUR_ID", "accountSecret": "YOUR_SECRET"}, json={
    "jsonrpc": "2.0", "id": "1", "method": "PirsonalAPI.Template_Video_List", "params": ["533155ec0fa92a6755582c8e"]
})
print("Videos count:", len(res.json()["result"]))

 true,
    CURLOPT_POSTFIELDS => json_encode(["jsonrpc" => "2.0", "id" => "1", "method" => "PirsonalAPI.Template_Video_List", "params" => ["533155ec0fa92a6755582c8e"]]),
    CURLOPT_HTTPHEADER => ["Content-Type: application/json"]
]);
print_r(json_decode(curl_exec($ch), true)["result"]);
curl_close($ch);
?>

const barrister = require('barrister');

const client = barrister.httpClient("http://app.pirsonal.com/api?accountID=YOUR_ACCOUNT_ID&accountSecret=YOUR_ACCOUNT_SECRET");
client.loadContract(function(err) {
  if (err) throw err;
  const pirsonal = client.proxy("PirsonalAPI");
  pirsonal.Template_Video_List("533155ec0fa92a6755582c8e", function(err, videos) {
    if (err) console.error(err);
    else console.log("Videos:", videos);
  });
});

Execute or simulate Template_Video_List

POST PirsonalAPI.Video_Get

Polling / State Query

Retrieves current rendering status, percentage progress, output media files (MP4, HLS, poster frames), video duration, and error details (if failed) for a specific video instance.

Parameters

Parameter	Type	Description
videoIDrequired	string	The unique 24-character hexadecimal video ID to query.

Returns

Returns a VideoInfo_t object containing status, progress percentage, duration, and output files.

cURL
Node.js
Python
PHP
Barrister RPC

curl -X POST "http://app.pirsonal.com/api?accountID=YOUR_ACCOUNT_ID&accountSecret=YOUR_ACCOUNT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": "1",
    "method": "PirsonalAPI.Video_Get",
    "params": ["543210fe810c19729de860ea"]
  }'

const accountID = "YOUR_ACCOUNT_ID";
const accountSecret = "YOUR_ACCOUNT_SECRET";

async function main() {
  const response = await fetch(`http://app.pirsonal.com/api?accountID=${accountID}&accountSecret=${accountSecret}`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      jsonrpc: "2.0",
      id: "1",
      method: "PirsonalAPI.Video_Get",
      params: ["543210fe810c19729de860ea"]
    })
  });
  const data = await response.json();
  console.log("Status:", data.result.status.code, "Files:", data.result.outFiles);
}

main().catch(console.error);

import requests

res = requests.post("http://app.pirsonal.com/api", params={"accountID": "YOUR_ID", "accountSecret": "YOUR_SECRET"}, json={
    "jsonrpc": "2.0", "id": "1", "method": "PirsonalAPI.Video_Get", "params": ["543210fe810c19729de860ea"]
})
print("Video status:", res.json()["result"]["status"])

 true,
    CURLOPT_POSTFIELDS => json_encode(["jsonrpc" => "2.0", "id" => "1", "method" => "PirsonalAPI.Video_Get", "params" => ["543210fe810c19729de860ea"]]),
    CURLOPT_HTTPHEADER => ["Content-Type: application/json"]
]);
print_r(json_decode(curl_exec($ch), true)["result"]);
curl_close($ch);
?>

const barrister = require('barrister');

const client = barrister.httpClient("http://app.pirsonal.com/api?accountID=YOUR_ACCOUNT_ID&accountSecret=YOUR_ACCOUNT_SECRET");
client.loadContract(function(err) {
  if (err) throw err;
  const pirsonal = client.proxy("PirsonalAPI");
  pirsonal.Video_Get("543210fe810c19729de860ea", function(err, info) {
    if (err) console.error(err);
    else console.log("Status:", info.status.code, "Files:", info.outFiles);
  });
});

Execute or simulate Video_Get

POST PirsonalAPI.Video_Delete

Storage Cleanup

Permanently deletes a personalized video record from your account database and purges its rendered media files from Pirsonal cloud storage. Set removeFiles to true if you also want Pirsonal to delete the video published to external distribution platforms (such as connected YouTube channels). Note that Pirsonal does not delete files from customer-owned external cloud storage.

Parameters

Parameter	Type	Description
videoIDrequired	string	The unique 24-character hexadecimal video ID.
removeFilesrequired	boolean	Pass `true` to also delete videos published to external platforms (such as connected YouTube channels), or `false` to keep them on external channels. Videos on Pirsonal storage are purged automatically.

Returns

Returns string "OK" upon deletion.

cURL
Node.js
Python
PHP
Barrister RPC

curl -X POST "http://app.pirsonal.com/api?accountID=YOUR_ACCOUNT_ID&accountSecret=YOUR_ACCOUNT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": "1",
    "method": "PirsonalAPI.Video_Delete",
    "params": ["543210fe810c19729de860ea", true]
  }'

const accountID = "YOUR_ACCOUNT_ID";
const accountSecret = "YOUR_ACCOUNT_SECRET";

async function main() {
  const response = await fetch(`http://app.pirsonal.com/api?accountID=${accountID}&accountSecret=${accountSecret}`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      jsonrpc: "2.0",
      id: "1",
      method: "PirsonalAPI.Video_Delete",
      params: ["543210fe810c19729de860ea", true]
    })
  });
  const data = await response.json();
  console.log("Delete status:", data.result);
}

main().catch(console.error);

import requests

res = requests.post("http://app.pirsonal.com/api", params={"accountID": "YOUR_ID", "accountSecret": "YOUR_SECRET"}, json={
    "jsonrpc": "2.0", "id": "1", "method": "PirsonalAPI.Video_Delete", "params": ["543210fe810c19729de860ea", True]
})
print("Result:", res.json()["result"])

 true,
    CURLOPT_POSTFIELDS => json_encode(["jsonrpc" => "2.0", "id" => "1", "method" => "PirsonalAPI.Video_Delete", "params" => ["543210fe810c19729de860ea", true]]),
    CURLOPT_HTTPHEADER => ["Content-Type: application/json"]
]);
echo json_decode(curl_exec($ch), true)["result"] . "\n";
curl_close($ch);
?>

const barrister = require('barrister');

const client = barrister.httpClient("http://app.pirsonal.com/api?accountID=YOUR_ACCOUNT_ID&accountSecret=YOUR_ACCOUNT_SECRET");
client.loadContract(function(err) {
  if (err) throw err;
  const pirsonal = client.proxy("PirsonalAPI");
  pirsonal.Video_Delete("543210fe810c19729de860ea", true, function(err, result) {
    if (err) console.error(err);
    else console.log("Result:", result);
  });
});

Execute or simulate Video_Delete

POST PirsonalAPI.Video_Pirsonal_Link

Personalized Landing Page & Player

Retrieves the canonical Personalized Video Landing Page link and responsive interactive player embed URL for a video. Pirsonal hosts responsive landing pages (vid.pirsonal.com/v/{videoID} or your custom CNAME) featuring the interactive player with timed call-to-action buttons (cta.startTime), lead capture forms, and viewer retention telemetry.

🚀 More Than Just an MP4: Pirsonal automatically deploys mobile-responsive video landing pages hosted on vid.pirsonal.com/v/{videoID} or your custom branded CNAME domain. Each page features the interactive Pirsonal Player with dynamic call-to-action (CTA) buttons timed to the video (e.g. cta.startTime), lead forms, social sharing cards, and second-by-second viewer engagement analytics.

Parameters

Parameter	Type	Description
videoIDrequired	string	The unique 24-character hexadecimal video ID.
pirsonalIDoptional	string	Optional link profile identifier. Pass "" (empty string) for the default landing page URL.

Returns

Returns a VideoLink_t object with url, profile, and id.

cURL
Node.js
Python
PHP
Barrister RPC

curl -X POST "http://app.pirsonal.com/api?accountID=YOUR_ACCOUNT_ID&accountSecret=YOUR_ACCOUNT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": "1",
    "method": "PirsonalAPI.Video_Pirsonal_Link",
    "params": ["543210fe810c19729de860ea", ""]
  }'

const accountID = "YOUR_ACCOUNT_ID";
const accountSecret = "YOUR_ACCOUNT_SECRET";

async function main() {
  const response = await fetch(`http://app.pirsonal.com/api?accountID=${accountID}&accountSecret=${accountSecret}`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      jsonrpc: "2.0",
      id: "1",
      method: "PirsonalAPI.Video_Pirsonal_Link",
      params: ["543210fe810c19729de860ea", ""]
    })
  });
  const linkData = await response.json();
  console.log("Personalized Landing Page URL:", linkData.result.url);
}

main().catch(console.error);

import requests

res = requests.post("http://app.pirsonal.com/api", params={"accountID": "YOUR_ID", "accountSecret": "YOUR_SECRET"}, json={
    "jsonrpc": "2.0", "id": "1", "method": "PirsonalAPI.Video_Pirsonal_Link", "params": ["543210fe810c19729de860ea", ""]
})
print("Landing Page URL:", res.json()["result"]["url"])

 true,
    CURLOPT_POSTFIELDS => json_encode(["jsonrpc" => "2.0", "id" => "1", "method" => "PirsonalAPI.Video_Pirsonal_Link", "params" => ["543210fe810c19729de860ea", ""]]),
    CURLOPT_HTTPHEADER => ["Content-Type: application/json"]
]);
echo "Landing URL: " . json_decode(curl_exec($ch), true)["result"]["url"] . "\n";
curl_close($ch);
?>

const barrister = require('barrister');

const client = barrister.httpClient("http://app.pirsonal.com/api?accountID=YOUR_ACCOUNT_ID&accountSecret=YOUR_ACCOUNT_SECRET");
client.loadContract(function(err) {
  if (err) throw err;
  const pirsonal = client.proxy("PirsonalAPI");
  pirsonal.Video_Pirsonal_Link("543210fe810c19729de860ea", "", function(err, link) {
    if (err) console.error(err);
    else console.log("Landing Page URL:", link.url);
  });
});

Execute or simulate Video_Pirsonal_Link

POST PirsonalAPI.Video_Get_Links

Direct Media & Streaming Links

Returns an array containing all download and streaming URLs associated with the video (e.g. raw MP4 downloads, HLS adaptive bitrate streams, personalized landing pages, and interactive player embeds).

Parameters

Parameter	Type	Description
videoIDrequired	string	The unique 24-character hexadecimal video ID.

Returns

Returns an array of VideoLink_t objects representing MP4, HLS, player, and landing page URLs.

cURL
Node.js
Python
PHP
Barrister RPC

curl -X POST "http://app.pirsonal.com/api?accountID=YOUR_ACCOUNT_ID&accountSecret=YOUR_ACCOUNT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": "1",
    "method": "PirsonalAPI.Video_Get_Links",
    "params": ["543210fe810c19729de860ea"]
  }'

const accountID = "YOUR_ACCOUNT_ID";
const accountSecret = "YOUR_ACCOUNT_SECRET";

async function main() {
  const response = await fetch(`http://app.pirsonal.com/api?accountID=${accountID}&accountSecret=${accountSecret}`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      jsonrpc: "2.0",
      id: "1",
      method: "PirsonalAPI.Video_Get_Links",
      params: ["543210fe810c19729de860ea"]
    })
  });
  const data = await response.json();
  console.log("Download & Stream Links:", data.result);
}

main().catch(console.error);

import requests

res = requests.post("http://app.pirsonal.com/api", params={"accountID": "YOUR_ID", "accountSecret": "YOUR_SECRET"}, json={
    "jsonrpc": "2.0", "id": "1", "method": "PirsonalAPI.Video_Get_Links", "params": ["543210fe810c19729de860ea"]
})
print("Links:", res.json()["result"])

 true,
    CURLOPT_POSTFIELDS => json_encode(["jsonrpc" => "2.0", "id" => "1", "method" => "PirsonalAPI.Video_Get_Links", "params" => ["543210fe810c19729de860ea"]]),
    CURLOPT_HTTPHEADER => ["Content-Type: application/json"]
]);
print_r(json_decode(curl_exec($ch), true)["result"]);
curl_close($ch);
?>

const barrister = require('barrister');

const client = barrister.httpClient("http://app.pirsonal.com/api?accountID=YOUR_ACCOUNT_ID&accountSecret=YOUR_ACCOUNT_SECRET");
client.loadContract(function(err) {
  if (err) throw err;
  const pirsonal = client.proxy("PirsonalAPI");
  pirsonal.Video_Get_Links("543210fe810c19729de860ea", function(err, links) {
    if (err) console.error(err);
    else console.log("Links:", links);
  });
});

Execute or simulate Video_Get_Links

POST PirsonalAPI.Video_Update_Metadata

Basic Metadata (Legacy)

Updates lightweight video metadata including title, description, keywords, custom tracking data, and YouTube synchronization settings. Note: VideoMetaData_t does not accept landing page branding or interactive player fields (unexpected fields will cause Barrister validation error -32602). To configure landing pages, CNAMEs, or interactive player CTAs, use PirsonalAPI.Video_Update.

Parameters

Parameter	Type	Description
videoIDrequired	string	The unique 24-character hexadecimal video ID.
metaDatarequired	VideoMetaData_t	Metadata object containing title, description, keywords, custom tracking data, and YouTube settings.

VideoMetaData_t Fields

nameoptional	string	Display title of the video.
descriptionoptional	string	Body copy shown below the personalized player on the landing page.
keywordsoptional	string	Comma-separated search and discovery keywords.
dataoptional	string	Custom external tracking identifier or payload.
youtubeoptional	YoutubeMetaData_t	Optional YouTube synchronization metadata: { title, description, category, tags }.

Returns

Returns string "OK" upon metadata update.

cURL
Node.js
Python
PHP
Barrister RPC

curl -X POST "http://app.pirsonal.com/api?accountID=YOUR_ACCOUNT_ID&accountSecret=YOUR_ACCOUNT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": "1",
    "method": "PirsonalAPI.Video_Update_Metadata",
    "params": [
      "543210fe810c19729de860ea",
      {
        "name": "Personalized Welcome for John",
        "description": "Exclusive proposal prepared for Acme Corp.",
        "keywords": "proposal, acme, 2026",
        "data": "crm_opp_4451"
      }
    ]
  }'

const accountID = "YOUR_ACCOUNT_ID";
const accountSecret = "YOUR_ACCOUNT_SECRET";

async function main() {
  const response = await fetch(`http://app.pirsonal.com/api?accountID=${accountID}&accountSecret=${accountSecret}`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      jsonrpc: "2.0",
      id: "1",
      method: "PirsonalAPI.Video_Update_Metadata",
      params: [
        "543210fe810c19729de860ea",
        {
          name: "Personalized Welcome for John",
          keywords: "proposal, acme, 2026",
          data: "crm_opp_4451"
        }
      ]
    })
  });
  const data = await response.json();
  console.log("Metadata updated:", data.result);
}

main().catch(console.error);

import requests

res = requests.post("http://app.pirsonal.com/api", params={"accountID": "YOUR_ID", "accountSecret": "YOUR_SECRET"}, json={
    "jsonrpc": "2.0", "id": "1", "method": "PirsonalAPI.Video_Update_Metadata", "params": [
        "543210fe810c19729de860ea",
        {"name": "Personalized Welcome for John", "keywords": "proposal, acme, 2026", "data": "crm_opp_4451"}
    ]
})
print("Result:", res.json()["result"])

 true,
    CURLOPT_POSTFIELDS => json_encode([
        "jsonrpc" => "2.0", "id" => "1", "method" => "PirsonalAPI.Video_Update_Metadata",
        "params" => ["543210fe810c19729de860ea", ["name" => "Personalized Welcome for John", "keywords" => "proposal, acme, 2026"]]
    ]),
    CURLOPT_HTTPHEADER => ["Content-Type: application/json"]
]);
echo json_decode(curl_exec($ch), true)["result"] . "\n";
curl_close($ch);
?>

const barrister = require('barrister');

const client = barrister.httpClient("http://app.pirsonal.com/api?accountID=YOUR_ACCOUNT_ID&accountSecret=YOUR_ACCOUNT_SECRET");
client.loadContract(function(err) {
  if (err) throw err;
  const pirsonal = client.proxy("PirsonalAPI");
  pirsonal.Video_Update_Metadata("543210fe810c19729de860ea", {
    name: "Personalized Welcome for John",
    keywords: "proposal, acme, 2026",
    data: "crm_opp_4451"
  }, function(err, result) {
    if (err) console.error(err);
    else console.log("Result:", result);
  });
});

Execute or simulate Video_Update_Metadata

POST PirsonalAPI.Video_Update

Video, Landing & Player Configuration

Comprehensive update method for video record metadata, recipient identity (firstName, lastName), custom tracking payload (data), personalized landing page branding (landingInfo), and interactive video player controls (playerInfo). Note: Video_Update updates metadata and player configuration; it does not replace input media files or re-queue rendering.

Parameters

Parameter	Type	Description
videoIDrequired	string	The unique 24-character hexadecimal video ID.
videoUpdaterequired	VideoUpdate_t	Video, landing page, and interactive player configuration payload.

VideoUpdate_t Fields

nameoptional	string	Display title of the video.
descriptionoptional	string	Description text displayed on the video landing page.
firstNameoptional	string	Recipient's first name.
lastNameoptional	string	Recipient's last name.
keywordsoptional	string	Comma-separated search and categorization keywords.
dataoptional	string	Custom tracking ID, CRM reference, or JSON metadata string.
landingInfooptional	LandingInfo_t	Landing page branding: `logoImageUrl`, `bannerImageUrl`, `embedIframeUrl`, `subdomain`, `cname`.
playerInfooptional	PlayerInfo_t	Player interactive CTA overlay: `CTAType` ("text", "html", "none"), `CTABodyText`, `CTAButtonText`, `CTAButtonUrl`, `CTAStartTime`, `CTAEndTime`, `thumbnail`, `CTAForm`.
youtubeoptional	YoutubeMetaData_t	Optional YouTube syndication options.

Returns

Returns string "OK" upon update.

cURL
Node.js
Python
PHP
Barrister RPC

curl -X POST "http://app.pirsonal.com/api?accountID=YOUR_ACCOUNT_ID&accountSecret=YOUR_ACCOUNT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": "1",
    "method": "PirsonalAPI.Video_Update",
    "params": [
      "543210fe810c19729de860ea",
      {
        "name": "Personalized Proposal - Jane Doe",
        "firstName": "Jane",
        "lastName": "Doe",
        "data": "crm_lead_8841",
        "landingInfo": {
          "logoImageUrl": "https://example.com/logo.png",
          "cname": "video.company.com"
        },
        "playerInfo": {
        "CTAType": "text",
        "CTABodyText": "Special Offer",
        "CTAButtonText": "Schedule Strategy Call",
          "CTAButtonUrl": "https://calendly.com/company/strategy",
          "CTAStartTime": 12
        }
      }
    ]
  }'

const accountID = "YOUR_ACCOUNT_ID";
const accountSecret = "YOUR_ACCOUNT_SECRET";

async function main() {
  const response = await fetch(`http://app.pirsonal.com/api?accountID=${accountID}&accountSecret=${accountSecret}`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      jsonrpc: "2.0",
      id: "1",
      method: "PirsonalAPI.Video_Update",
      params: [
        "543210fe810c19729de860ea",
        {
          name: "Personalized Proposal - Jane Doe",
          firstName: "Jane",
          lastName: "Doe",
          data: "crm_lead_8841",
          landingInfo: {
            logoImageUrl: "https://example.com/logo.png",
            cname: "video.company.com"
          },
          playerInfo: {
            CTAType: "text",
            CTABodyText: "Special Offer",
            CTAButtonText: "Schedule Strategy Call",
            CTAButtonUrl: "https://calendly.com/company/strategy",
            CTAStartTime: 12
          }
        }
      ]
    })
  });
  const data = await response.json();
  console.log("Update status:", data.result);
}

main().catch(console.error);

import requests

res = requests.post("http://app.pirsonal.com/api", params={"accountID": "YOUR_ID", "accountSecret": "YOUR_SECRET"}, json={
    "jsonrpc": "2.0",
    "id": "1",
    "method": "PirsonalAPI.Video_Update",
    "params": [
        "543210fe810c19729de860ea",
        {
            "name": "Personalized Proposal - Jane Doe",
            "firstName": "Jane",
            "lastName": "Doe",
            "data": "crm_lead_8841",
            "landingInfo": {
                "logoImageUrl": "https://example.com/logo.png",
                "cname": "video.company.com"
            },
            "playerInfo": {
        "CTAType": "text",
        "CTABodyText": "Special Offer",
        "CTAButtonText": "Schedule Strategy Call",
                "CTAButtonUrl": "https://calendly.com/company/strategy",
                "CTAStartTime": 12
            }
        }
    ]
})
print("Result:", res.json()["result"])

<?php
$ch = curl_init("http://app.pirsonal.com/api?accountID=YOUR_ID&accountSecret=YOUR_SECRET");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POSTFIELDS => json_encode([
        "jsonrpc" => "2.0",
        "id" => "1",
        "method" => "PirsonalAPI.Video_Update",
        "params" => [
            "543210fe810c19729de860ea",
            [
                "name" => "Personalized Proposal - Jane Doe",
                "firstName" => "Jane",
                "lastName" => "Doe",
                "data" => "crm_lead_8841",
                "landingInfo" => [
                    "logoImageUrl" => "https://example.com/logo.png",
                    "cname" => "video.company.com"
                ],
                "playerInfo" => [
                    "CTAType" => "button",
                    "CTAButtonText" => "Schedule Strategy Call",
                    "CTAButtonUrl" => "https://calendly.com/company/strategy",
                    "CTAStartTime" => 12
                ]
            ]
        ]
    ]),
    CURLOPT_HTTPHEADER => ["Content-Type: application/json"]
]);
echo json_decode(curl_exec($ch), true)["result"] . "\n";
curl_close($ch);
?>

const barrister = require('barrister');

const client = barrister.httpClient("http://app.pirsonal.com/api?accountID=YOUR_ACCOUNT_ID&accountSecret=YOUR_ACCOUNT_SECRET");
client.loadContract(function(err) {
  if (err) throw err;
  const pirsonal = client.proxy("PirsonalAPI");
  pirsonal.Video_Update("543210fe810c19729de860ea", {
    name: "Personalized Proposal - Jane Doe",
    firstName: "Jane",
    lastName: "Doe",
    data: "crm_lead_8841",
    landingInfo: {
      logoImageUrl: "https://example.com/logo.png",
      cname: "video.company.com"
    },
    playerInfo: {
            CTAType: "text",
            CTABodyText: "Special Offer",
            CTAButtonText: "Schedule Strategy Call",
      CTAButtonUrl: "https://calendly.com/company/strategy",
      CTAStartTime: 12
    }
  }, function(err, result) {
    if (err) console.error(err);
    else console.log("Result:", result);
  });
});

Execute or simulate Video_Update

📁 Media Storage & Upload

Upload and manage reusable visual assets (images, audio soundtracks, intro/outro clips) directly into your secure cloud storage library.

POST POST /api/upload

Direct Binary Streaming

Upload binary image, audio, or video files directly to high-speed cloud storage (supports payloads up to 500 MB). Returns an assigned pirsonalID for media assignment across templates.

Note on Custom Fonts: TrueType (.ttf) brand fonts cannot be uploaded via the public API. Upload and manage custom fonts directly in the Pirsonal Studio UI or by contacting us at help@pirsonal.com.

Important: Media assets currently associated with an active template cannot be deleted until unlinked or until the template is removed (Error Code 1008).

Parameters

Parameter	Type	Description
Content-Typerequired	Header (string)	MIME type: video/mp4, image/jpeg, image/png, audio/mpeg.
X-SZN-FILENAMEoptional	Header (string)	Original filename with extension (e.g. customer_intro.mp4).
X-SZN-DESCRIPTIONoptional	Header (string)	Optional descriptive note for the uploaded asset.

Returns

Returns an envelope object: { media: PirsonalMedia_t } containing assigned media _id, name, size, type, and storage metadata.

cURL
Node.js
Python
PHP
Barrister RPC

curl -X POST "http://app.pirsonal.com/api/upload?accountID=YOUR_ACCOUNT_ID&accountSecret=YOUR_ACCOUNT_SECRET" \
  -H "Content-Type: video/mp4" \
  -H "X-SZN-FILENAME: customer_intro.mp4" \
  --data-binary "@./customer_intro.mp4"

const fs = require('fs');

const accountID = "YOUR_ACCOUNT_ID";
const accountSecret = "YOUR_ACCOUNT_SECRET";

async function main() {
  const fileBuffer = fs.readFileSync("./customer_intro.mp4");

  const response = await fetch(`http://app.pirsonal.com/api/upload?accountID=${accountID}&accountSecret=${accountSecret}`, {
    method: "POST",
    headers: {
      "Content-Type": "video/mp4",
      "X-SZN-FILENAME": "customer_intro.mp4",
    },
    body: fileBuffer
  });

  const uploadedMedia = await response.json();
  if (uploadedMedia.error) throw new Error(`Upload Error: ${uploadedMedia.error.message || JSON.stringify(uploadedMedia.error)}`);
  console.log("Assigned Pirsonal Media ID:", uploadedMedia.media.id);
}

main().catch(console.error);

import requests

account_id = "YOUR_ACCOUNT_ID"
account_secret = "YOUR_ACCOUNT_SECRET"

with open("customer_intro.mp4", "rb") as f:
    response = requests.post(
        "http://app.pirsonal.com/api/upload",
        params={"accountID": account_id, "accountSecret": account_secret},
        headers={
            "Content-Type": "video/mp4",
            "X-SZN-FILENAME": "customer_intro.mp4"
        },
        data=f
    )
data = response.json()
print("Uploaded Media ID:", data["media"]["id"])

 true,
    CURLOPT_POSTFIELDS => file_get_contents($filePath),
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        "Content-Type: video/mp4",
        "X-SZN-FILENAME: customer_intro.mp4",
    ]
]);

$response = curl_exec($ch);
fclose($fileHandle);
curl_close($ch);

$data = json_decode($response, true);
echo "Uploaded Media ID: " . $data["media"]["id"] . "\n";
?>

// Note: Binary media uploads use the high-performance HTTP streaming endpoint (/api/upload).
// Once uploaded, you reference the resulting pirsonalID in Barrister RPC methods like Template_Video_New.

Execute or simulate Media_Upload

POST PirsonalAPI.Media_List

Asset Inventory

Retrieves an inventory of all media files stored in your account library, including their unique pirsonalID, original filename, byte size, media type (video, image, audio, font), and secure hosted URL.

Parameters

Parameter	Type	Description
This method takes no parameters (`params: []`).

Returns

Returns an array of PirsonalMedia_t objects.

cURL
Node.js
Python
PHP
Barrister RPC

curl -X POST "http://app.pirsonal.com/api?accountID=YOUR_ACCOUNT_ID&accountSecret=YOUR_ACCOUNT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": "1",
    "method": "PirsonalAPI.Media_List",
    "params": []
  }'

const accountID = "YOUR_ACCOUNT_ID";
const accountSecret = "YOUR_ACCOUNT_SECRET";

async function main() {
  const response = await fetch(`http://app.pirsonal.com/api?accountID=${accountID}&accountSecret=${accountSecret}`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      jsonrpc: "2.0",
      id: "1",
      method: "PirsonalAPI.Media_List",
      params: []
    })
  });
  const data = await response.json();
  console.log("Media Assets:", data.result);
}

main().catch(console.error);

import requests

res = requests.post("http://app.pirsonal.com/api", params={"accountID": "YOUR_ID", "accountSecret": "YOUR_SECRET"}, json={
    "jsonrpc": "2.0", "id": "1", "method": "PirsonalAPI.Media_List", "params": []
})
print("Media items count:", len(res.json()["result"]))

 true,
    CURLOPT_POSTFIELDS => json_encode(["jsonrpc" => "2.0", "id" => "1", "method" => "PirsonalAPI.Media_List", "params" => []]),
    CURLOPT_HTTPHEADER => ["Content-Type: application/json"]
]);
print_r(json_decode(curl_exec($ch), true)["result"]);
curl_close($ch);
?>

const barrister = require('barrister');

const client = barrister.httpClient("http://app.pirsonal.com/api?accountID=YOUR_ACCOUNT_ID&accountSecret=YOUR_ACCOUNT_SECRET");
client.loadContract(function(err) {
  if (err) throw err;
  const pirsonal = client.proxy("PirsonalAPI");
  pirsonal.Media_List(function(err, medias) {
    if (err) console.error(err);
    else console.log("Media Assets:", medias);
  });
});

Execute or simulate Media_List

POST PirsonalAPI.Media_Delete

Asset Deletion

Permanently removes a media asset from your account library and deletes the binary file from cloud storage. Media assets currently referenced by active templates cannot be deleted until unlinked (error 1008).

Parameters

Parameter	Type	Description
mediaIDrequired	string	The unique pirsonalID of the media asset to delete.

Returns

Returns string "OK" upon deletion.

cURL
Node.js
Python
PHP
Barrister RPC

curl -X POST "http://app.pirsonal.com/api?accountID=YOUR_ACCOUNT_ID&accountSecret=YOUR_ACCOUNT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": "1",
    "method": "PirsonalAPI.Media_Delete",
    "params": ["543210fe810c19729de860ea"]
  }'

const accountID = "YOUR_ACCOUNT_ID";
const accountSecret = "YOUR_ACCOUNT_SECRET";

async function main() {
  const response = await fetch(`http://app.pirsonal.com/api?accountID=${accountID}&accountSecret=${accountSecret}`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      jsonrpc: "2.0",
      id: "1",
      method: "PirsonalAPI.Media_Delete",
      params: ["543210fe810c19729de860ea"]
    })
  });
  const data = await response.json();
  console.log("Delete result:", data.result);
}

main().catch(console.error);

import requests

res = requests.post("http://app.pirsonal.com/api", params={"accountID": "YOUR_ID", "accountSecret": "YOUR_SECRET"}, json={
    "jsonrpc": "2.0", "id": "1", "method": "PirsonalAPI.Media_Delete", "params": ["543210fe810c19729de860ea"]
})
print("Result:", res.json()["result"])

 true,
    CURLOPT_POSTFIELDS => json_encode(["jsonrpc" => "2.0", "id" => "1", "method" => "PirsonalAPI.Media_Delete", "params" => ["543210fe810c19729de860ea"]]),
    CURLOPT_HTTPHEADER => ["Content-Type: application/json"]
]);
echo json_decode(curl_exec($ch), true)["result"] . "\n";
curl_close($ch);
?>

const barrister = require('barrister');

const client = barrister.httpClient("http://app.pirsonal.com/api?accountID=YOUR_ACCOUNT_ID&accountSecret=YOUR_ACCOUNT_SECRET");
client.loadContract(function(err) {
  if (err) throw err;
  const pirsonal = client.proxy("PirsonalAPI");
  pirsonal.Media_Delete("543210fe810c19729de860ea", function(err, result) {
    if (err) console.error(err);
    else console.log("Result:", result);
  });
});

Execute or simulate Media_Delete

POST PirsonalAPI.Media_Apply_Pattern

Engine Transformation

Applies programmatic transformations (e.g. dynamic color tinting, cropping, audio level normalization, or alpha filters) to a stored media asset directly via the media rendering engine.

Parameters

Parameter	Type	Description
mediaIDrequired	string	The unique pirsonalID of the media asset.
patterrequired	Pattern_type_t	Pattern type enum: "audiolevel".
actionrequired	Pattern_action_t	Pattern action enum: "info", "one", or "multi".
parametersrequired	string	Additional transformation parameter string (or empty string).

Returns

Returns string "OK" upon transformation.

cURL
Node.js
Python
PHP
Barrister RPC

curl -X POST "http://app.pirsonal.com/api?accountID=YOUR_ACCOUNT_ID&accountSecret=YOUR_ACCOUNT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": "1",
    "method": "PirsonalAPI.Media_Apply_Pattern",
    "params": ["543210fe810c19729de860ea", "audiolevel", "info", ""]
  }'

const accountID = "YOUR_ACCOUNT_ID";
const accountSecret = "YOUR_ACCOUNT_SECRET";

async function main() {
  const response = await fetch(`http://app.pirsonal.com/api?accountID=${accountID}&accountSecret=${accountSecret}`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      jsonrpc: "2.0",
      id: "1",
      method: "PirsonalAPI.Media_Apply_Pattern",
      params: ["543210fe810c19729de860ea", "audiolevel", "info", ""]
    })
  });
  const data = await response.json();
  console.log("Pattern result:", data.result);
}

main().catch(console.error);

import requests

res = requests.post("http://app.pirsonal.com/api", params={"accountID": "YOUR_ID", "accountSecret": "YOUR_SECRET"}, json={
    "jsonrpc": "2.0", "id": "1", "method": "PirsonalAPI.Media_Apply_Pattern", "params": ["543210fe810c19729de860ea", "audiolevel", "info", ""]
})
print("Result:", res.json()["result"])

 true,
    CURLOPT_POSTFIELDS => json_encode([
        "jsonrpc" => "2.0", "id" => "1", "method" => "PirsonalAPI.Media_Apply_Pattern",
        "params" => ["543210fe810c19729de860ea", "audiolevel", "info", ""]
    ]),
    CURLOPT_HTTPHEADER => ["Content-Type: application/json"]
]);
echo json_decode(curl_exec($ch), true)["result"] . "\n";
curl_close($ch);
?>

const barrister = require('barrister');

const client = barrister.httpClient("http://app.pirsonal.com/api?accountID=YOUR_ACCOUNT_ID&accountSecret=YOUR_ACCOUNT_SECRET");
client.loadContract(function(err) {
  if (err) throw err;
  const pirsonal = client.proxy("PirsonalAPI");
  pirsonal.Media_Apply_Pattern("543210fe810c19729de860ea", "audiolevel", "info", "", function(err, result) {
    if (err) console.error(err);
    else console.log("Result:", result);
  });
});

Execute or simulate Media_Apply_Pattern

⚡ Webhooks & Completion Callbacks

Personalized video generation is asynchronous. When video rendering completes (or encounters a fatal error), Pirsonal dispatches an HTTP POST webhook request to the URL configured on your template (template.webhook.url) with User-Agent: Pirsonal and the complete VideoInfo_t JSON payload.

AUTHENTIC WEBHOOK PAYLOAD (Event: Video Completion)

{
  "id": "543210fe810c19729de860ea",
  "templateID": "533155ec0fa92a6755582c8e",
  "name": "Campaign - John Doe",
  "status": {
    "code": "done"
  },
  "duration": 15000,
  "outFiles": [
    {
      "name": "543210fe810c19729de860ea.MP4_H264_AAC_1280x720_24fps.mp4",
      "profile": "MP4_H264_AAC_1280x720_24fps",
      "size": 4521980,
      "storage": {
        "pirsonalID": "543210fe810c19729de860ea.MP4_H264_AAC_1280x720_24fps.mp4"
      },
      "deleted": false
    }
  ],
  "data": "user_id_98765",
  "landingInfo": {
    "logoImageUrl": "https://example.com/logo.png",
    "cname": "video.company.com"
  },
  "playerInfo": {
        "CTAType": "text",
        "CTABodyText": "Special Offer",
        "CTAButtonText": "Claim Offer",
    "CTAButtonUrl": "https://example.com/offer"
  },
  "date": "2026-10-16T12:00:00.000Z"
}

🔒 Webhook Authentication

Pirsonal supports HTTP Basic and HTTP Digest authentication directly in the template webhook configuration. Deliveries are dispatched as a single HTTP POST request per completion event. Webhook endpoints should require HTTP Basic authentication (configured via template.webhook.user and template.webhook.pass) and handle deliveries idempotently.

🔁 Idempotency & Tracking

Echo your custom internal system identifier in the data parameter when creating the video. When the webhook arrives, match your internal job record by checking data and key your completion idempotently on the video id.

Enterprise Best Practice: For high-volume video generation, Pirsonal recommends using client-side job queues with bounded concurrency (5–10 concurrent requests) to pace requests. If webhooks are blocked by corporate firewalls, your integration can poll PirsonalAPI.Video_Get(videoID) using progressive backoff (5s, 15s, 30s) until status.code === "done". Note: To retrieve template configurations, query PirsonalAPI.Template_List (the API does not provide a separate Template_Get endpoint).

☁️ Video Cloud Storage & Output File Naming Rules

When video rendering is finalized, output video files are uploaded to your designated cloud storage provider configured in videoOutput. Understanding file key formatting is critical for downstream automated pipelines, S3 event notifications, and storage webhooks.

Pirsonal Cloud / Azure Blob Storage

Configured via videoOutput: { "type": "pirsonal" }. Files are hosted in Pirsonal-managed resilient storage containers.

Blob Path: <accountID>/<videoID>.<profile>.mp4
Filename / ID: <videoID>.<profile>.mp4
Single extension format.

Amazon Web Services (AWS S3)

Configured via videoOutput: { "type": "awsS3", "awsS3Bucket": "my-bucket" }. Worker directly streams rendered media into your AWS S3 bucket.

S3 Object Key: <videoID>.<profile>.mp4.mp4
S3 Object URL: https://<bucket>.s3.amazonaws.com/<videoID>.<profile>.mp4.mp4
Note: Worker preserves double extension (.mp4.mp4).

Custom Rendering Profiles (customProfiles): When a template declares custom rendering profiles, you MUST specify that custom profile's exact name in outProfiles (e.g. ["MyCustom720p"]). Do not pass default profile names. The rendering engine will assign the output file using your specified custom profile name (e.g., Azure: <videoID>.MyCustom720p.mp4; S3: <videoID>.MyCustom720p.mp4.mp4).

🛠️ Barrister RPC SDK Packages

If your architecture prefers contract-driven RPC over direct HTTP POST, you can install the Barrister client bindings:

Node.js / JavaScript

npm install barrister

Loads the contract via client.loadContract(cb) and provides strict client-side validation.

Python

pip install barrister

Python client proxy with typed exceptions.

Error Resolution Matrix

Comprehensive directory of all standard JSON-RPC (-32xxx) protocol errors and Pirsonal application error codes (1xxx, 2xxx, 5xxx) with root causes and actionable resolutions.

Error Code	Status / Message	Root Cause	Actionable Resolution
-32700	Parse error	Server received malformed or unparseable JSON payload in request body.	Verify that your request payload is valid JSON without trailing commas or unescaped control characters.
-32600	Invalid Request	Payload does not follow JSON-RPC 2.0 specification (missing `jsonrpc`, `method`, or `id`).	Ensure payload contains `"jsonrpc": "2.0"`, a valid `"method"` name, and an `"id"`.
-32601	Method not found	Requested RPC method does not exist or has a typographical error.	Confirm method name spelling against the sidebar reference (e.g. `PirsonalAPI.Template_Video_New`).
-32602	Invalid params	Parameter name, type mismatch, or unexpected property violates `pir_api_v3.json`.	Check parameters against the IDL documentation. In Barrister RPC, unexpected additional fields are strictly rejected.
-32603	Internal JSON-RPC error	Internal serialization or protocol dispatch error on the API server.	Ensure the request body is UTF-8 encoded and check server logs. Contact support if persistent.
-32001	Invalid response contract	Server returned fields not declared in the Barrister IDL return type.	Indicates an API contract synchronization issue. Contact developer support or review `pir_api_v3.idl`.
1000	Template not found	The specified `templateID` does not exist or does not belong to your account.	Call `Template_List` to verify your valid template IDs and confirm your active account credentials.
1003	Inputs not allowed	Supplied dynamic inputs to a static template that has no declared input placeholders.	Verify that the template has dynamic input placeholders declared or check that you targeted the right template.
1004	Inputs mismatch	The `inputID`s supplied in `inputMedias` do not match placeholders declared in the script.	Ensure every `inputID` in your request payload matches an exact placeholder defined in the template script.
1005	Bad script	Pirsonal Script JSON contains a syntax error or cyclic dependency in its timeline graph.	Validate the script using the Script Linter on the Pirsonal Script page to detect cycles.
1009	No scripts	The targeted template has no Pirsonal Script timeline attached.	Attach a valid Pirsonal Script to the template before triggering video generation.
1028	Template inactive	The template has been marked as inactive and cannot render new videos.	Call `Template_SetStatus` with `"active"` to reactivate the template.
2003	Too much free objects	Template exceeds the allowed number of dynamic freeform objects for your plan.	Optimize your template layers or upgrade your subscription tier in the Pirsonal dashboard.
2005	Variables mismatch / Limit	Missing dynamic variables or maximum allowed templates reached for account.	Ensure all `$variable` placeholders are defined or upgrade account template quota.
1001	Media not found	The specified `mediaID` does not exist in your account library.	Call `Media_List` to view your valid media asset IDs or upload the asset via `/api/upload`.
1002	MediaID not found in scripts	A media ID referenced in template inputs was not found in the timeline script.	Verify that the script references the correct media placeholder ID.
1008	Media in use in templates	Cannot delete media asset because it is currently linked in active templates.	Unlink the asset from active templates before calling `Media_Delete`.
1011	Error downloading medias	Rendering engine failed to download an external media URL (404, DNS, timeout, or SSL).	Ensure all external media URLs in `inputMedias` are publicly accessible via HTTPS and respond with HTTP 200.
1019	No size specified	Binary media upload is missing the mandatory `Content-Length` header.	Ensure your client supplies the `Content-Length` header during binary upload to `/api/upload`.
1020	Invalid Content-Type	MIME type of uploaded binary asset is unsupported.	Supported MIME types: `video/mp4`, `image/jpeg`, `image/png`, `audio/mpeg`, `font/ttf`.
1029	Bad input media	An item in `inputMedias` has invalid structure or an unsupported media source.	Verify that each `inputMedia` object contains valid `inputID`, `type`, and `text` or `http`.
2001	Media storage limit reached	Your account has exhausted its allotted media asset storage capacity.	Delete obsolete assets with `Media_Delete` or upgrade your subscription tier.
1006	Video file not found	Rendered video file was purged or could not be retrieved from cloud storage.	Video may have expired under retention policy. Re-render via `Template_Video_New`.
1007	Video not found	The specified `videoID` does not exist in your account.	Verify the 24-character hexadecimal video ID returned when the video was created.
1012	Error processing video	The video rendering engine encountered an internal composition or codec failure.	Inspect input media dimensions and codecs; check that audio bitrates and video framerates are standard.
1030	Error deleting video files	Storage cluster failed to remove output video files.	Retry deletion request or contact Pirsonal technical support.
2000	Video storage limit reached	Your account has reached its total video storage capacity.	Purge older videos via `Video_Delete` or upgrade your storage tier in the dashboard.
2002	Video profile not allowed	The requested output profile/resolution is not permitted under your current subscription tier.	Check your plan features (e.g. 1080p, 4K rendering profiles).
2004	No credit / Plan upgrade required	Your account has exhausted video generation rendering credits.	Refill credits in your Pirsonal dashboard or upgrade your billing tier.
2006	Invalid CTA start time	Interactive player CTA start time cannot be empty or negative.	Specify a valid non-negative integer for `playerInfo.cta.startTime` in seconds.
2007	Invalid CTA form fields / Conflicting time	Interactive CTA form has zero fields or multiple elements share identical start/end times.	Ensure at least one field is defined and eliminate overlapping element start/end timestamps.
1010	Account not found	The supplied Account ID does not exist.	Verify the Account ID in your Pirsonal dashboard under Settings > API Keys.
1015	Authentication error	Missing or invalid Account ID or Secret Key.	Check `accountID` and `accountSecret` URL query parameters.
1016	Email already used	The specified email address is already registered to an account.	Use a different email address or log in to the existing account.
1017	Bad password	Authentication failed due to incorrect password credentials.	Reset your password via the account recovery portal.
1018	Bad secret	The provided Account Secret does not match the Account ID.	Copy the active Secret Key from your dashboard or rotate keys via automated CLI tooling.
1021	Account not active	Your account has been paused, suspended, or has an unpaid invoice.	Check billing status in the dashboard or reach out to billing support.
1025	Account type not found	Account tier configuration is unmapped or corrupted.	Contact support@pirsonal.com to re-synchronize account profile.
1026	Payment client error	Payment gateway rejected subscription transaction.	Update credit card payment details in billing settings.
1027	Payment mismatch	Transaction amount mismatch between checkout session and subscription tier.	Refresh the billing checkout page and retry.
1032	Custom profiles not allowed	Account does not permit custom encoding profiles or duplicated profile name.	Upgrade subscription tier or choose unique profile names.
1033	Account locked (wrong attempts)	Account locked after repeated failed login attempts.	Wait 15 minutes before retrying or use password recovery.
1034	Account deactivated (inactivity)	Free tier account was paused due to extended inactivity (6+ months).	Log in to the Pirsonal web dashboard to automatically reactivate or contact help@pirsonal.com.
1060	Font not found	Referenced font name does not exist in the font library.	Check the Font Library for valid public font family names.
1061	Invalid font format	Uploaded font file is not TrueType (.ttf) format.	Only TrueType (.ttf) font files are supported. Convert .otf or .woff before uploading.
1062	Font in use in templates	Cannot delete font because it is referenced in active templates.	Remove font references from templates prior to deletion.
1070	AI Voiceover synthesis error	Text-to-Speech (TTS) synthesis provider returned a failure.	Verify TTS voice code, speed rate, and text length; ensure input text does not contain unsupported characters.
5000	Internal Error	Unexpected server exception during request processing.	Verify request structure and retry; if error persists, contact support@pirsonal.com with your request ID.