Skip to main content
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 (starts with pictai_)

​
Setup

1

Install Claude Code

npm install -g @anthropic-ai/claude-code
2

Store your Pictory API key

Add the key to your shell profile (do not commit it):
echo 'export PICTORY_API_KEY="pictai_your_key_here"' >> ~/.zshrc
source ~/.zshrc
3

Navigate to your project and start Claude Code

cd /path/to/your/project
claude
4

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.
Drop this into your project root. Claude Code will load it automatically every session. 
# 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.

​
Troubleshooting

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.
Cause: Insufficient context loaded.Resolution: Add this line to your prompt: “Verify the endpoint exists by referencing https://docs.pictory.ai/openapi.json before suggesting it.” Or fetch llms-full.txt and paste relevant sections.
Cause: Code is missing saveProject: true or templateId.Resolution: Update CLAUDE.md to require one of these on all render calls.

​
Next Steps

Use Pictory with an LLM

System prompts, MCP, and example flows

End-to-End Recipes

Ready-to-run JSON payloads

Cursor Setup

Same setup, for Cursor users

Windsurf Setup

Same setup, for Windsurf users