Complete, runnable JSON payloads for the most common Pictory API use cases
This page collects complete, working request payloads for the most common Pictory API scenarios. Each recipe has:
A one-line description of the use case
The full request body, ready to send
The endpoint and a one-line cURL
A note on how to retrieve the rendered video
Replace YOUR_API_KEY with your pictai_ API key from the API Access page.
Every recipe uses the same authentication pattern: Authorization: YOUR_API_KEY (no Bearer prefix). After submitting a render, the response includes a jobId. Poll GET /v1/jobs/{jobid} every 10–30 seconds until status is completed, OR include a webhook URL in the request body to receive the result automatically.
Recipe 2 — Multilingual Video (Generate Narration in a Target Language)
Use case: Render the same video in French (or any of 14 supported languages) with native-language narration and voice.Endpoint:POST /v2/video/storyboard/render
{ "videoName": "Lancement Produit", "language": "fr", "aspectRatio": "16:9", "scenes": [ { "story": "Découvrez notre dernière innovation. Conçue pour les créateurs, construite pour évoluer.", "createSceneOnEndOfSentence": true }, { "story": "Lancez votre prochain projet en quelques minutes, pas en semaines.", "createSceneOnEndOfSentence": true } ], "voiceOver": { "enabled": true, "aiVoices": [{ "speaker": "Gabriel", "speed": 100, "amplificationLevel": 0 }] }}
Supported languages:zh, nl, en, fr, de, hi, it, ja, ko, mr, pt, ru, es, ta
If you do not specify a voice, use the documented default male STD voice for the target language. For languages without a documented default, the API falls back to the English voice — in that case, prefer calling GET /v1/voiceovers/tracks to pick a native voice.
language
Default voice (speaker)
en
Martin
nl
Tim
fr
Gabriel
de
Wilbur
it
Marco
pt
Aurelio
es
Hugo
hi, ru
Martin (English fallback — no native STD default)
zh, ja, ko, mr, ta
None documented — discover via GET /v1/voiceovers/tracks
Use case: Convert a PowerPoint deck into a video using the slides as visuals and the speaker notes as narration.Endpoint:POST /v2/video/storyboard/render
Set animatePPT: true inside the scene to enable AI-generated slide animations (zoom, pan, fade) for image-heavy slides. See the Animated Slides guide for details.
Recipe 4 — Avatar Video (Chef Walking Through a Recipe)
Use case: Render a how-to video where an AI avatar narrates the steps. Each step becomes its own scene; the avatar reads the scene’s story text. The avatar is configured once at the top level and applies across all scenes.
Avatar IDs are account-scoped. Before rendering, fetch the list of avatars available to your account with GET /v1/avatars and use a real avatarId from that response. The YOUR_AVATAR_ID placeholder below is not a valid identifier — replace it with an ID from your account.
Endpoint:POST /v2/video/storyboard/render
{ "videoName": "Recipe — Lemon Risotto", "language": "en", "aspectRatio": "16:9", "saveProject": true, "avatar": { "avatarId": "YOUR_AVATAR_ID", "position": "bottom-right" }, "scenes": [ { "story": "Today we are making lemon risotto. You will need arborio rice, fresh lemon, parmesan, and warm vegetable stock." }, { "story": "Step 1: Heat olive oil in a heavy pan and toast the rice for two minutes." }, { "story": "Step 2: Add warm stock one ladle at a time, stirring continuously until absorbed." }, { "story": "Step 3: Off the heat, stir in lemon zest, juice, and grated parmesan. Plate and serve." } ]}
To hide the avatar in a specific scene or reposition it per scene, use the per-scene avatar override field (e.g., "avatar": { "hide": true } or "avatar": { "position": "top-left" }). The per-scene override only accepts position and styling fields — set the avatar identity once at the top level.
Recipe 5 — Render Against an Existing Project as a Template
Use case: You built a master template in the Pictory web app and want every new video to inherit its branding, layouts, music, and transitions. Pass the template’s projectId as templateId.Endpoint:POST /v2/video/storyboard/render
{ "videoName": "Recipe — Tomato Soup", "templateId": "YOUR_TEMPLATE_PROJECT_ID", "avatar": { "avatarId": "YOUR_AVATAR_ID" }, "scenes": [ { "story": "Tomato soup, made simple. Here is what you need." }, { "story": "Step 1: Roast the tomatoes with garlic and olive oil." }, { "story": "Step 2: Blend with warm stock until smooth." }, { "story": "Step 3: Season, garnish with basil, and serve." } ]}
Use templateId when you want to reuse an existing project as a template with new content. Use saveProject: true when you want the render to create a new project in My Projects. These two options serve different purposes and can be combined.
Use case: You have an existing project saved in your Pictory dashboard and you just want to re-render it without changes (e.g., to regenerate the video file after editing branding).Endpoint:POST /v2/projects/{projectid}/render
Use case: Apply your saved brand kit (colors, fonts, logo, intro/outro) to a video. You can identify the brand by either brandId or brandName — not both.Endpoint:POST /v2/video/storyboard/render
Use case: You do not want to poll for job status. Pass a webhook URL and Pictory will POST the result to your server when the render completes.Endpoint:POST /v2/video/storyboard/render
The rendered video URL is at data.videoURL. Poll every 10–30 seconds. Typical render time is 2–10 minutes depending on video length and complexity. For full response details, see the Get Video Render Job API.
