# TBeni

> Give this file to an AI, or connect the MCP server at https://tbeni.com/mcp

TBeni on this site is a film pipeline: Idea -> Story -> Concept -> Storyboard -> Timeline, plus standalone image, video, and audio generation.

People can read the connection steps at https://tbeni.com/mcp/connect.


## Connect

Preferred: MCP Streamable HTTP

- MCP endpoint: https://tbeni.com/mcp
- Server card: https://tbeni.com/.well-known/mcp.json
- Full docs: https://tbeni.com/llms-full.txt
- OpenAPI: https://tbeni.com/openapi.json

ChatGPT / Claude / Cursor: add a remote MCP server using https://tbeni.com/mcp. The server speaks the Model Context Protocol and OAuth 2.1.

REST fallback for agents that cannot speak MCP:

1. POST https://tbeni.com/api/login with `{"email","password"}`
2. Call the same capabilities under https://tbeni.com/api/* with `Authorization: Bearer <token>`

## Auth

MCP clients should use OAuth:

- https://tbeni.com/.well-known/oauth-protected-resource
- https://tbeni.com/.well-known/oauth-authorization-server

Existing studio JWTs also work as `Authorization: Bearer <token>` on /mcp.

## Public tools

- `get_studio_overview`: Describe TBeni, the film pipeline, auth, and how to use the tools. Call this first.
- `get_workflow_guide`: Return the recommended step-by-step film-making workflow and which tools to call at each stage.
- `list_models`: List enabled AI models the user can pick for text, image, video, or audio generation.
- `list_styles`: List visual styles available for concept, storyboard, and timeline generation, including the authenticated user's personal styles.
- `list_plans`: List subscription plans and credit bundles.

## Authenticated tools

- `whoami`: Return the authenticated user profile, credits, plan, and unlimited windows.
- `update_account`: Update the authenticated user profile. Password changes require current_password.
- `subscribe_plan`: Start or change the user subscription plan.
- `list_projects`: List the authenticated user studio projects (not standalone AI Generate workspaces).
- `get_project`: Load a project with idea, story, concept assets, storyboard shots, and timeline.
- `create_project`: Create a new studio project. Then generate ideas and convert one into a story.
- `get_ai_generate_workspace`: Get or create the standalone AI Generate workspace used by /ai-Generate pages.
- `save_timeline`: Save the visual timeline JSON for a project. Pass the timeline object produced by the studio editor or a previous get_project call.
- `generate_ideas`: Generate film idea cards from a brief. Pass count when the user asked for N ideas. Call once. If they only wanted cards, stop after this.
- `edit_idea`: Rewrite an existing idea from a user instruction.
- `idea_to_story`: Turn a selected idea into a screenplay and optionally save it onto a project.
- `edit_story`: Rewrite a screenplay from a user instruction.
- `extract_assets`: Parse a screenplay into characters, locations, and props and save them on the project. Stage 3. Images are generated later with generate_concept_images.
- `generate_concept_images`: Queue stills for extracted concept cards. Poll get_job_status with kind=concept afterwards.
- `select_card_image`: Mark an image as the selected still for a concept asset or storyboard shot.
- `delete_assets`: Delete concept assets from a project.
- `generate_shots`: Break a screenplay into storyboard shots and save them. Defaults to V2 key shots. Requires concept assets to already exist.
- `make_multishot`: Stage 4 V2: pack consecutive shots in each sequence into multi-shot clips until the duration cap. No AI. Call after generate_shots when method is v2.
- `generate_storyboard_images`: Queue stills for storyboard shots. Poll get_job_status with kind=storyboard afterwards.
- `generate_camera_angle`: Re-angle an existing still from the camera widget. Returns a pending image record_id.
- `generate_image`: Queue a still. Omit project_id, or set target=standalone, to make one image in the AI Generate workspace. Pass project_id with target=concept or timeline to add a still inside a film. Poll get_job_status with kind=image.
- `retry_image`: Retry a failed or stuck image generation record. Pass model to switch models.
- `write_video_prompt`: Write an image-to-video prompt from a storyboard still, shot description, and style.
- `generate_video`: Queue a video. Omit project_id to make one clip in the AI Generate workspace. Pass project_id to render storyboard or timeline clips; omit shot_id to generate every current timeline clip. Poll get_job_status with kind=video.
- `generate_audio`: Queue music or SFX. Omit project_id to make one clip in the AI Generate workspace. Pass project_id to place it on a film timeline. Poll get_job_status with kind=audio.
- `get_job_status`: Poll a queued generation. Media jobs are async; call this until is_complete/is_ready is true.
- `list_gallery`: List generated images, videos, and audio in a project gallery.
- `list_gallery_projects`: List projects that have gallery media, for the timeline gallery browser.
- `like_gallery_asset`: Toggle like on a generated gallery asset.
- `delete_gallery_asset`: Delete a generated gallery asset and its stored file.

## Workflow

# TBeni workflow

Use this order unless the user only wants a standalone image/video/audio.

1. **Auth** - MCP clients complete OAuth. Then call `whoami` to see credits.
2. **Catalog** - `list_styles` and `list_models` before generating media.
3. **Project** - `create_project` (Movie / Series / Short / Music Video / Ad).
4. **Idea** - `generate_ideas` then optionally `edit_idea`.
5. **Story** - `idea_to_story` with the chosen idea and `project_id`. Optionally `edit_story`.
6. **Concept** - `extract_assets` with the screenplay + a style name, then `generate_concept_images`, then `get_job_status` kind=concept until complete. Use `select_card_image` if several stills exist.
7. **Storyboard** - `generate_shots` (V2 key shots by default), then `make_multishot`. Do not `generate_storyboard_images` on V2. Classic v1 still uses `generate_storyboard_images`.
8. **Motion** - `write_video_prompt` then `generate_video` target=storyboard. Poll kind=video.
9. **Timeline / sound** - `generate_image` target=timeline, `generate_audio`, `save_timeline`.
10. **Gallery** - `list_gallery` to collect finished URLs.

Standalone image, video, or audio, with no film project:
- `generate_image` with a prompt. project_id is optional.
- `generate_video` with a prompt. project_id is optional.
- `generate_audio` with a prompt. project_id is optional.
The AI Generate workspace is opened automatically. Poll `get_job_status`.

Important:
- Image, video, and audio jobs are queued. Never assume they finished in the first response. Poll `get_job_status`.
- Return media as URLs. Do not download binaries into chat.
- Generation spends credits. If a tool reports insufficient credits, tell the user and use `list_plans`.
- Admin APIs are not exposed here.


## Rules for models

- Do not skip polling after image/video/audio generation.
- Return media URLs, not files.
- Use style names from list_styles and model names from list_models.
- Do not call admin APIs.