Claude Code Setup for Pictory API

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

Install Claude Code

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

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

Navigate to your project and start Claude Code

cd /path/to/your/project
claude

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.

Recommended `CLAUDE.md` Template

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

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.

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 before suggesting it.” Or fetch llms-full.txt and paste relevant sections.

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.

Next Steps

Pictory Claude Skills

Skip the setup: install the ready-made Text-to-Video skill and create videos in plain English

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

​Prerequisites

​Setup

​Recommended CLAUDE.md Template

​Example Prompts

​Connecting via MCP

​Troubleshooting

​Next Steps