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

# Claude Code Setup for Pictory API

> Configure Claude Code to call the Pictory API from your terminal — set up auth, project context, and proven prompts

[Claude Code](https://claude.com/claude-code) is Anthropic's official CLI for Claude. This page shows you how to configure it to work productively with the Pictory API: making API calls, building integration code, debugging payloads, and operating as a Pictory-aware coding assistant.

## Prerequisites

* Claude Code installed (`npm install -g @anthropic-ai/claude-code`)
* A Claude subscription (Pro, Max, or API access)
* A Pictory API key from [app.pictory.ai/api-access](https://app.pictory.ai/api-access) (starts with `pictai_`)

## Setup

<Steps>
  <Step title="Install Claude Code">
    ```bash theme={null}
    npm install -g @anthropic-ai/claude-code
    ```
  </Step>

  <Step title="Store your Pictory API key">
    Add the key to your shell profile (do not commit it):

    ```bash theme={null}
    echo 'export PICTORY_API_KEY="pictai_your_key_here"' >> ~/.zshrc
    source ~/.zshrc
    ```
  </Step>

  <Step title="Navigate to your project and start Claude Code">
    ```bash theme={null}
    cd /path/to/your/project
    claude
    ```
  </Step>

  <Step title="Add a CLAUDE.md file with Pictory context">
    Create a `CLAUDE.md` at your project root using the template in the next section. This teaches Claude Code the Pictory API conventions before you ask any questions.
  </Step>
</Steps>

## Recommended `CLAUDE.md` Template

Drop this into your project root. Claude Code will load it automatically every session.

```markdown theme={null}
# Pictory API project rules

## About this project
This project integrates with the Pictory API to create videos programmatically.

## API conventions

- **Base URL:** `https://api.pictory.ai/pictoryapis`
- **Authentication:** `Authorization: $PICTORY_API_KEY` header. **The key value is raw — do NOT use a Bearer prefix.**
- **API key format:** Always starts with `pictai_`. Get it from https://app.pictory.ai/api-access.
- **Content-Type:** All POST requests use `application/json`.

## Primary endpoints

| Endpoint | Purpose |
|---|---|
| `POST /v2/video/storyboard` | Create a storyboard preview |
| `POST /v2/video/storyboard/render` | Render final video directly |
| `POST /v2/projects/{projectid}/render` | Re-render an existing project |
| `GET /v1/jobs/{jobid}` | Fetch job status and output |
| `GET /v1/brands/video` | List video brand kits |
| `GET /v1/avatars` | List AI avatars |

## Field rules

- `videoName` is required on all render endpoints.
- `brandId` and `brandName` are **mutually exclusive** — never include both.
- `smartLayoutId` and `smartLayoutName` are mutually exclusive.
- `subtitleStyleId` and `subtitleStyleName` are mutually exclusive.
- API-rendered jobs do NOT appear in My Projects unless `saveProject: true` is set, OR an existing `projectId` is passed as `templateId`.
- Supported `language` values: `zh, nl, en, fr, de, hi, it, ja, ko, mr, pt, ru, es, ta`.

## Job lifecycle

1. Submit a render → receive `jobId`.
2. Either poll `GET /v1/jobs/{jobid}` every 10–30 seconds, OR pass a `webhook` URL in the request body.
3. When `status === "completed"`, the video URL is in `data.videoURL`.

## Reference documentation

- Full docs: https://docs.pictory.ai/llms-full.txt
- OpenAPI spec: https://docs.pictory.ai/openapi.json
- API reference: https://docs.pictory.ai/api-reference

## Coding conventions for this project

- Always read the `PICTORY_API_KEY` from `process.env` (Node) or `os.environ` (Python). Never inline.
- Always handle the polling loop with exponential backoff or a fixed 10–30s interval — never tighter.
- Always check `data.status` before reading `data.videoURL` — the field is absent until completion.
```

## Example Prompts

After Claude Code loads `CLAUDE.md`, you can prompt it naturally:

* "Write a Python script that takes a recipe (list of steps as strings) and submits each step as a scene to the storyboard render endpoint. Use my chef avatar (`chef_07`)."
* "Debug this payload — I am getting a 400. Here is the JSON: \[paste]"
* "Add webhook support to my existing `submit_render.js` so I do not have to poll."
* "Write a Make.com HTTP module configuration that calls the Pictory render API with a template ID and dynamic recipe scenes from the previous module."

## Connecting via MCP

If you want Claude Code to call the Pictory API as a structured tool (rather than generating cURL/code), connect the Pictory MCP server. Setup details at [Pictory MCP Server](https://pictory.ai/pictory-mcp-server-api).

## Troubleshooting

<AccordionGroup>
  <Accordion title="Claude Suggests `Bearer YOUR_API_KEY`">
    **Cause:** Training-data bias toward OAuth/Bearer flows.

    **Resolution:** Reinforce the rule in `CLAUDE.md`: "Authorization header value is the raw key with no prefix." If it still happens mid-session, correct it once — Claude Code will pick up the correction.
  </Accordion>

  <Accordion title="Claude Invents an Endpoint That Does Not Exist">
    **Cause:** Insufficient context loaded.

    **Resolution:** Add this line to your prompt: "Verify the endpoint exists by referencing [https://docs.pictory.ai/openapi.json](https://docs.pictory.ai/openapi.json) before suggesting it." Or fetch `llms-full.txt` and paste relevant sections.
  </Accordion>

  <Accordion title="Videos Submitted via Claude-Generated Code Do Not Appear in My Projects">
    **Cause:** Code is missing `saveProject: true` or `templateId`.

    **Resolution:** Update `CLAUDE.md` to require one of these on all render calls.
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Use Pictory with an LLM" icon="sparkles" href="/guides/llm-integration/use-pictory-with-llm">
    System prompts, MCP, and example flows
  </Card>

  <Card title="End-to-End Recipes" icon="book-open" href="/guides/recipes/end-to-end-recipes">
    Ready-to-run JSON payloads
  </Card>

  <Card title="Cursor Setup" icon="arrow-pointer" href="/ai-tools/cursor">
    Same setup, for Cursor users
  </Card>

  <Card title="Windsurf Setup" icon="water" href="/ai-tools/windsurf">
    Same setup, for Windsurf users
  </Card>
</CardGroup>