# Reel Studio

> Reel Studio is an AI-centric filmmaking workspace for story, shots, cast, references, review, timeline assembly, and export.

Reel Studio is split into two phases:

- **Editor** -- pre-production + production: films, scenes, shots, cast, locations, generated frames/video, review.
- **Timeline** -- post-production: cut order, voiceover, SFX, score, mix, export.

For the full MCP reference, see **[`/llms-full.txt`](/llms-full.txt)**.

## Access

If the human user does not have access yet, send them to **[`/challenge`](/challenge)**.

`/challenge` is Agent Gate: a short invite-only access flow where a human or their agent explains who they are and what they want to make in Reel Studio. Strong, specific answers may receive an invite with starter credits. Normal good-faith answers may receive a plain invite.

The invite must still be accepted by a human through normal signup, including bot protection and OTP. After registration, onboarding helps the user create a personal access token and MCP config for their agent.

Agents can participate in Agent Gate without MCP by using the public HTTP API:

```http
POST /api/agent-gate/sessions
Content-Type: application/json

{
  "email": "user@example.com",
  "name": "Emir",
  "role": "Commercial filmmaker",
  "useCase": "A coffee commercial with consistent cast, shot review, and timeline assembly."
}
```

Then reply to the gate:

```http
POST /api/agent-gate/sessions/<sessionId>/messages
Content-Type: application/json

{ "message": "I use Nano Banana and Kling, manually review takes today, and want Reel Studio to organize references and faster review." }
```

If accepted, the response includes `session.inviteUrl`. Show that link to the human user. Do not try to use `/api/mcp` before the user registers and creates a token.

## MCP

Reel Studio hosts a Model Context Protocol endpoint at **`/api/mcp`**, served over Streamable HTTP.

Claude, Cursor, Cline, Continue, and other MCP-speaking agents can connect by URL. No local Node install is required for remote MCP clients.

To connect:

1. The human signs into Reel Studio.
2. They create a personal access token in **Settings -> Personal access tokens**.
3. They paste the MCP config from **Settings -> Connect AI agents** into their agent client.

Config shape:

```json
{
  "mcpServers": {
    "reelstudio": {
      "url": "https://<host>/api/mcp",
      "headers": {
        "Authorization": "Bearer rs_pat_...",
        "x-workspace-id": "<workspace-id>"
      }
    }
  }
}
```

The MCP endpoint is **POST-only**. Do not fetch `/api/mcp` as a human-readable docs page.

Useful MCP context:

- Resource `reelstudio://agent-guide` gives a compact production loop.
- Prompt `short_film_workflow` starts an agent on the recommended short-film workflow.

## Core Tools

- `list_films`, `get_film`, `create_film`
- `get_workspace_status`
- `list_scenes`, `create_scene`, `update_scene`
- `list_shots`, `create_shot`, `update_shot`
- `list_cast`, `create_cast`, `update_cast`
- `list_locations`, `create_location`, `update_location`
- `list_assets`, `create_asset_upload`, `confirm_asset_upload`, `upload_asset`
- `list_models`
- `generate`
- `get_job`, `list_jobs`
- `review_takes`, `promote_take`, `generate_fix_prompt`
- `get_timeline`, `assemble_timeline`, timeline clip/audio/mix tools
- `start_export`, `get_export`

See **[`/llms-full.txt`](/llms-full.txt)** for exact inputs, target behavior, duration validation, and timeline/export details.

## Recommended Loop

1. `get_workspace_status` to confirm user, workspace, and credits.
2. `list_films` or `create_film`.
3. Upload any local reference media as assets: call `create_asset_upload`, PUT the local file bytes directly to the returned R2 `uploadUrl`, then call `confirm_asset_upload`.
4. Create cast and location references.
5. Generate cast portraits/sheets and location images/sheets.
6. Create scenes and shots.
7. In shot descriptions, bind references with `@{Cast Name}` and `#{Location Name}`.
8. Use `list_assets` to reuse uploaded image/video/audio URLs in generation params.
9. Use `list_models` before generation to check model costs, aspect ratios, durations, and resolutions.
10. Use `generate` for frames/video/audio.
11. Poll `get_job` until jobs finish.
12. Use `review_takes` and promote only good takes with `promote_take`.
13. Use `generate_fix_prompt` and retry/edit when consistency fails.
14. Assemble the timeline, mix audio, then export.

## Important Rules

- All generations cost credits.
- For retry-safe generation, pass `generate.idempotencyKey` and reuse it only when retrying the same intended request.
- Jobs are async. `generate` returns queued job ids; poll with `get_job`.
- Use `@{Cast Name}` and `#{Location Name}` for identity/location consistency. Plain-text names drift.
- Generate cast/location reference assets before writing identity-critical shots.
- For local media, never pass a local filesystem path to hosted MCP. Use `create_asset_upload` -> direct R2 PUT -> `confirm_asset_upload`; the confirmed asset appears in the site.
- `upload_asset` is for importing an existing HTTP(S) media URL into the asset library.
- Use 2-4 takes for hero shots, close-ups, and shots with bound cast refs.
- Use 1 take for routine B-roll or final image-to-video animation from a promoted frame.
- Do not overwrite existing timeline work or export a final render without a human checkpoint.
- Ask a short clarification question only when ambiguity materially changes the film, spends significant credits, or touches core references/timeline/export.

## Links

- [Agent Gate](/challenge): invite-only access flow for humans and their agents.
- [AI Video Prompt Doctor](/tools/ai-video-prompt-doctor): public prompt checker and rewrite tool for AI video generation.
- [Pricing](/pricing): credits and plans.
- [Partners](/partners): creator partner program.
- [Terms](/terms)
- [Privacy](/privacy)
- [Full agent reference](/llms-full.txt)