> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pictory.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Cursor Setup for Pictory API

> Configure Cursor to call the Pictory API with project rules, MCP integration, and proven prompts

[Cursor](https://cursor.com) 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](https://app.pictory.ai/api-access) (starts with `pictai_`)

## Setup

<Steps>
  <Step title="Open your project in Cursor">
    Open the project where you want to integrate the Pictory API.
  </Step>

  <Step title="Store your Pictory API key">
    Add the key to your shell profile (do not commit it):

    ```bash theme={null}
    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`.
  </Step>

  <Step title="Create project rules">
    Cursor reads `.cursor/rules/*.mdc` files automatically. Create the directory and rules file below.

    ```bash theme={null}
    mkdir -p .cursor/rules
    ```
  </Step>

  <Step title="Add the Pictory rules file">
    Use the template in the next section to populate `.cursor/rules/pictory-api.mdc`.
  </Step>
</Steps>

## Recommended Cursor Rules

Create `.cursor/rules/pictory-api.mdc`:

```markdown theme={null}
---
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:

```markdown theme={null}
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](https://pictory.ai/pictory-mcp-server-api).

## Example Prompts

* "Generate a TypeScript client for the Pictory storyboard render endpoint, using the OpenAPI spec at [https://docs.pictory.ai/openapi.json](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

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="`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.
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Use Pictory with an LLM" icon="sparkles" href="/guides/llm-integration/use-pictory-with-llm">
    System prompts, MCP, and example flows
  </Card>

  <Card title="End-to-End Recipes" icon="book-open" href="/guides/recipes/end-to-end-recipes">
    Ready-to-run JSON payloads
  </Card>

  <Card title="Claude Code Setup" icon="terminal" href="/ai-tools/claude-code">
    Same setup, for Claude Code users
  </Card>

  <Card title="Windsurf Setup" icon="water" href="/ai-tools/windsurf">
    Same setup, for Windsurf users
  </Card>
</CardGroup>