> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pictory.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# End-to-End Recipes

> 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](https://app.pictory.ai/api-access).

<Note>
  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.
</Note>

***

## Recipe 1 — Text-to-Video with AI Voice-Over

**Use case:** Turn a short script into a narrated video with auto-selected stock visuals.

**Endpoint:** `POST /v2/video/storyboard/render`

```json theme={null}
{
  "videoName": "Product Launch Teaser",
  "language": "en",
  "aspectRatio": "16:9",
  "saveProject": true,
  "scenes": [
    {
      "story": "Introducing our latest innovation. Designed for creators, built for scale.",
      "createSceneOnEndOfSentence": true
    },
    {
      "story": "Launch your next project in minutes, not weeks.",
      "createSceneOnEndOfSentence": true
    },
    {
      "story": "Available today. Visit our website to learn more.",
      "createSceneOnEndOfSentence": true
    }
  ],
  "voiceOver": {
    "enabled": true,
    "aiVoices": [{ "speaker": "Martin", "speed": 100, "amplificationLevel": 0 }]
  },
  "backgroundMusic": {
    "enabled": true,
    "autoMusic": true,
    "volume": 0.1
  }
}
```

```bash theme={null}
curl --request POST \
  --url 'https://api.pictory.ai/pictoryapis/v2/video/storyboard/render' \
  --header 'Authorization: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data @payload.json
```

***

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

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

### Default Male STD Voice by Language

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` |

***

## Recipe 3 — PowerPoint to Video with Speaker Notes

**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`

```json theme={null}
{
  "videoName": "Quarterly Training",
  "language": "en",
  "scenes": [
    {
      "pptUrl": "https://example.com/training-deck.pptx",
      "useSpeakerNotes": true
    }
  ],
  "voiceOver": {
    "enabled": true,
    "aiVoices": [{ "speaker": "Martin", "speed": 100, "amplificationLevel": 0 }]
  }
}
```

<Tip>
  Set `animatePPT: true` inside the scene to enable AI-generated slide animations (zoom, pan, fade) for image-heavy slides. See the [Animated Slides guide](/guides/presentation-to-video/powerpoint-animated-slides) for details.
</Tip>

***

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

<Warning>
  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.
</Warning>

**Endpoint:** `POST /v2/video/storyboard/render`

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

Fetch available avatar IDs via [`GET /v1/avatars`](/api-reference/avatars/get-avatars).

<Tip>
  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.
</Tip>

***

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

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

<Note>
  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.
</Note>

***

## Recipe 6 — Re-render a Saved Project As-Is

**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`

```bash theme={null}
curl --request POST \
  --url 'https://api.pictory.ai/pictoryapis/v2/projects/YOUR_PROJECT_ID/render' \
  --header 'Authorization: YOUR_API_KEY' \
  --header 'Content-Type: application/json'
```

No request body is needed — the project's saved configuration is used as-is.

***

## Recipe 7 — Brand Kit Applied via brandName

**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`

```json theme={null}
{
  "videoName": "Branded Promo",
  "language": "en",
  "brandName": "Acme Corp Brand",
  "scenes": [
    { "story": "Acme. Built for tomorrow.", "createSceneOnEndOfSentence": true },
    { "story": "Discover what's new this quarter.", "createSceneOnEndOfSentence": true }
  ],
  "voiceOver": {
    "enabled": true,
    "aiVoices": [{ "speaker": "Martin", "speed": 100, "amplificationLevel": 0 }]
  }
}
```

To list available brand kits and their IDs, call [`GET /v1/brands/video`](/api-reference/branding/get-video-brands).

<Warning>
  Do not provide both `brandId` and `brandName` in the same request. The API will reject the request with a validation error.
</Warning>

***

## Recipe 8 — Webhook-Driven Async Workflow

**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`

```json theme={null}
{
  "videoName": "Async Render",
  "scenes": [
    { "story": "Async render demonstration video.", "createSceneOnEndOfSentence": true }
  ],
  "voiceOver": {
    "enabled": true,
    "aiVoices": [{ "speaker": "Martin", "speed": 100, "amplificationLevel": 0 }]
  },
  "webhook": "https://your-domain.com/pictory-webhook",
  "webhookInput": {
    "internalId": "abc-123",
    "source": "campaign-builder"
  }
}
```

**Webhook requirements:**

* Publicly reachable HTTPS URL
* Accepts `POST` with `Content-Type: application/json`
* Responds with a `2xx` status within 30 seconds
* The `webhookInput` object you pass is echoed back in the callback payload — use it for correlation

***

## Recipe 9 — Create a Storyboard Preview Before Rendering

**Use case:** Generate scene thumbnails and a project structure for review before committing to a full render.

**Endpoint:** `POST /v2/video/storyboard`

```json theme={null}
{
  "videoName": "Preview First",
  "scenes": [
    { "story": "First scene narration text.", "createSceneOnEndOfSentence": true },
    { "story": "Second scene narration text.", "createSceneOnEndOfSentence": true }
  ],
  "voiceOver": {
    "enabled": true,
    "aiVoices": [{ "speaker": "Martin", "speed": 100, "amplificationLevel": 0 }]
  }
}
```

After the preview job completes, you can:

1. Review the scenes via [`GET /v1/jobs/{jobid}`](/api-reference/jobs/get-storyboard-preview-job-by-id)
2. Edit scenes via [`PUT /v2/video/storyboard/elements`](/api-reference/video-storyboard/update-storyboard-elements)
3. Render with [`PUT /v2/video/render/{storyboardjobid}`](/api-reference/videos/render-from-preview), passing the preview job ID in the path

***

## Recipe 10 — Poll Job Status

**Use case:** You submitted a render and need to check whether it is done.

**Endpoint:** `GET /v1/jobs/{jobid}`

```bash theme={null}
curl --request GET \
  --url 'https://api.pictory.ai/pictoryapis/v1/jobs/YOUR_JOB_ID' \
  --header 'Authorization: YOUR_API_KEY'
```

**Response shape (when complete):**

```json theme={null}
{
  "job_id": "9b1c4d2e-7f8a-4321-b2c3-d456e789f012",
  "success": true,
  "data": {
    "status": "completed",
    "progress": 100,
    "videoURL": "https://d3uryq9bhgb5qr.cloudfront.net/.../video.mp4",
    "videoShareURL": "https://video.pictory.ai/.../...",
    "videoEmbedURL": "https://video.pictory.ai/embed/.../...",
    "thumbnail": "https://d3uryq9bhgb5qr.cloudfront.net/.../thumbnail.jpg",
    "videoDuration": 65.6,
    "aiCreditsUsed": 48
  }
}
```

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](/api-reference/jobs/get-video-render-job-by-id).

***

## How to Choose the Right Recipe

| Your Goal                         | Use Recipe |
| --------------------------------- | ---------- |
| Quick text-to-video               | 1          |
| Localize for non-English audience | 2          |
| Convert PPT deck                  | 3          |
| Avatar-narrated walk-through      | 4          |
| Reuse a master template           | 5          |
| Re-render a saved project         | 6          |
| Apply brand kit                   | 7          |
| Avoid polling                     | 8          |
| Review before committing render   | 9          |
| Check job status                  | 10         |

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Use Pictory with an LLM" icon="sparkles" href="/guides/llm-integration/use-pictory-with-llm">
    Hand these recipes to an LLM for natural-language video generation
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference">
    Full endpoint-level documentation
  </Card>

  <Card title="OpenAPI Spec" icon="file-code" href="/openapi.json">
    Machine-readable spec for codegen and tooling
  </Card>

  <Card title="Webhook Setup" icon="webhook" href="/guides/advanced-features/save-project">
    Async result delivery via webhook
  </Card>
</CardGroup>