Cursor Setup for Pictory API

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

Cursor installed
A Pictory API key from app.pictory.ai/api-access (starts with pictai_)

Setup

Open your project in Cursor

Open the project where you want to integrate the Pictory API.

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.

Create project rules

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

mkdir -p .cursor/rules

Add the Pictory rules file

Use the template in the next section to populate .cursor/rules/pictory-api.mdc.

Recommended Cursor Rules

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

Cursor Suggests Bearer Authorization

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.

Generated Code Returns 400 Validation Errors

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.

`PICTORY_API_KEY` is Undefined at Runtime

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

​Prerequisites

​Setup

​Recommended Cursor Rules

​OpenAPI as a Tool Schema

​Connecting via MCP

​Example Prompts

​Troubleshooting

​Next Steps