Windsurf Setup for Pictory API

Windsurf is an agentic IDE powered by Cascade. This page shows you how to configure it for productive work against the Pictory API: workspace rules that teach Cascade the API conventions, MCP integration for direct API calls, and example prompts.

Prerequisites

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

Setup

Open your project in Windsurf

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

Restart Windsurf after setting the variable.

Create workspace rules

Windsurf reads .windsurf/rules.md from the project root. Create the directory:

mkdir -p .windsurf

Add the Pictory rules file

Use the template in the next section to populate .windsurf/rules.md.

Recommended Windsurf Rules

Create .windsurf/rules.md:

# Pictory API workspace rules

## About this project
This project integrates with the Pictory API to create videos programmatically. Cascade should reference the rules below on every interaction touching API calls.

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

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

Connecting via MCP

Windsurf’s Cascade supports MCP servers natively. To let Cascade call the Pictory API as structured tools, connect the Pictory MCP server.

Open Windsurf settings → Cascade → Model Context Protocol.
Add the Pictory MCP server configuration (details at Pictory MCP Server).
Reload Cascade to pick up the new tools.

Once connected, Cascade can invoke Pictory endpoints directly without generating code first.

Example Prompts

“Build a Node.js worker that consumes a queue of video render requests and submits each one to Pictory. Use the OpenAPI spec at https://docs.pictory.ai/openapi.json for the request shape.”
“Add a unit test for my submitPictoryRender function that mocks the API response.”
“Trace through this 401 error. Why is my Pictory API request being rejected?”
“Generate a webhook handler that receives Pictory’s completion callback and uploads the rendered video to S3.”

Troubleshooting

Cascade Suggests Bearer Authorization

Cause: Default LLM bias toward Bearer flows.Resolution: Reinforce the rule in .windsurf/rules.md. If Cascade still suggests Bearer mid-session, correct it once and Cascade will adapt.

MCP Tools Do Not Appear in Cascade

Cause: MCP server not running or misconfigured.Resolution: Verify the MCP server URL and credentials, restart Windsurf, and check the Cascade panel for tool registration errors.

Cascade Polls Too Aggressively

Cause: Default LLM tendency to write tight polling loops.Resolution: The rules file specifies 10–30 second polling. If Cascade still generates a 1-second loop, paste the snippet back and say “follow the polling interval rule in .windsurf/rules.md.”

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

Cursor Setup

Same setup, for Cursor users

​Prerequisites

​Setup

​Recommended Windsurf Rules

​Connecting via MCP

​Example Prompts

​Troubleshooting

​Next Steps