Skip to main content
Cursor is an AI-first code editor. This page shows you how to configure it for productive work against the Pictory API: project-level rules that teach Cursor the API conventions, MCP integration for direct API calls, and example prompts.

​
Prerequisites

​
Setup

1

Open your project in Cursor

Open the project where you want to integrate the Pictory API.
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
Cursor inherits environment variables from the shell you launched it from. On Windows, use a .env file at the project root and add .env to .gitignore.
3

Create project rules

Cursor reads .cursor/rules/*.mdc files automatically. Create the directory and rules file below.
mkdir -p .cursor/rules
4

Add the Pictory rules file

Use the template in the next section to populate .cursor/rules/pictory-api.mdc.
Create .cursor/rules/pictory-api.mdc: 
---
description: "Pictory API conventions and rules"
alwaysApply: true
---

# 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

## Coding conventions for this project

- Read `PICTORY_API_KEY` from environment variables — never inline.
- Polling intervals must be 10–30 seconds.
- Always check `data.status` before reading `data.videoURL`.

​
OpenAPI as a Tool Schema

Cursor’s Agent mode can ingest an OpenAPI spec as a structured tool. Add this to your rules: 
When the user asks for API integration code, always reference the OpenAPI spec at https://docs.pictory.ai/openapi.json for accurate field names, types, and required parameters.

​
Connecting via MCP

To let Cursor’s Agent mode call the Pictory API as a tool (instead of generating code), connect the Pictory MCP server. Setup at Pictory MCP Server.

​
Example Prompts

  • “Generate a TypeScript client for the Pictory storyboard render endpoint, using the OpenAPI spec at https://docs.pictory.ai/openapi.json.”
  • “Build a React component that lets a user paste a script, choose a language and voice, and submit it to the Pictory render API.”
  • “Add error handling for 400 responses to this Pictory integration — surface the validation message to the user.”
  • “Refactor my polling loop to use 15-second intervals and exponential backoff capped at 60 seconds.”

​
Troubleshooting

Cause: Default LLM bias toward Bearer flows.Resolution: Reinforce the rule in .cursor/rules/pictory-api.mdc. If Cursor still suggests Bearer in a session, correct it once and the agent will adapt.
Cause: Common causes: missing videoName, both brandId and brandName included, or invalid language code.Resolution: Paste the API error response back into Cursor — it will adjust. Also confirm your rules file lists the field constraints.
Cause: Cursor was launched before the env var was exported in your shell.Resolution: Restart Cursor after sourcing your .zshrc / .bashrc. On Windows, restart Cursor after setting the env var via System Properties.

​
Next Steps

Use Pictory with an LLM

System prompts, MCP, and example flows

End-to-End Recipes

Ready-to-run JSON payloads

Claude Code Setup

Same setup, for Claude Code users

Windsurf Setup

Same setup, for Windsurf users