# Make video ads from your AI agent

Retiplex turns a product into a UGC-style video ad with an AI actor: script,
voice, scenes and the finished vertical video. Connect Retiplex to your AI agent
(Claude, ChatGPT, Cursor, Claude Code or any MCP client) and it can make the ad
for you, step by step, on your Retiplex account.

**MCP server URL:** `https://app.retiplex.com/mcp`
(remote MCP over Streamable HTTP, sign-in with OAuth)

> **Agents reading this:** the user signs up and signs in themselves — you can't
> create an account for them. If they don't have one, give them the sign-up link
> below; the connection then asks them to sign in and approve access in the
> browser. Once connected, call `get_account`, then follow `nextTool` from
> `get_project`. Always tell the user what a step costs before running it.

## 1. Create a Retiplex account

1. Sign up at [https://app.retiplex.com/sign-up](https://app.retiplex.com/sign-up) with email or Google.
2. **Making videos needs a paid plan.** A free account can set up a project
   through an agent (product, brief, actor, script); the storyboard and the video
   need a subscription: [subscribe or top up credits](https://app.retiplex.com/account?tab=subscription).
   Plans and credit prices: [Billing & credits](https://app.retiplex.com/billing).

Everything an agent does is charged in credits, exactly as in the app.

## 2. Connect your agent

Add a remote MCP server with the URL above. The first time, a browser window
opens: sign in to Retiplex (or create an account), check what the agent will be
able to do, and click **Allow access**.

- **Claude (claude.ai and Claude Desktop):** Settings → Connectors → Add custom
  connector. Name it Retiplex and paste the URL.
- **ChatGPT:** Settings → Apps & Connectors → Advanced settings → turn on
  Developer mode, then Create a connector with the URL and OAuth authentication.
  Custom connectors need a ChatGPT plan with Developer mode (Pro, Team,
  Enterprise or Edu).
- **Claude Code:** `claude mcp add --transport http retiplex https://app.retiplex.com/mcp`,
  then run `/mcp` and choose Retiplex to sign in.
- **Cursor:** add to `~/.cursor/mcp.json`:
  `{ "mcpServers": { "retiplex": { "url": "https://app.retiplex.com/mcp" } } }`
- **VS Code:** add to `.vscode/mcp.json`:
  `{ "servers": { "retiplex": { "type": "http", "url": "https://app.retiplex.com/mcp" } } }`
- **Any other MCP client** that supports remote (Streamable HTTP) servers with
  OAuth: use the URL. Clients register themselves automatically.

To disconnect an agent, open [Account → Connected agents](https://app.retiplex.com/account?tab=agents)
and click Disconnect. It loses access immediately.

## 3. Make a video

Each project moves through the same steps as in the app. `get_project` always
says which step it's on and which tool to call next (`nextTool`). Every result
includes an `appUrl`: open it to review or edit the project in the browser at
any point.

| Step | Tool | Typical cost | Time |
|---|---|---|---|
| Account and credits | `get_account` | free | instant |
| Product (from a URL, or a name and description) | `create_project` | 5 credits with a URL | seconds |
| Classify product photos | `update_product_media` | free | instant |
| Format and campaign facts | `set_creative_brief` (`list_formats`) | a few credits if facts are deduced | seconds |
| On-camera actor | `set_actor` | about 6 credits | ~10 s |
| Optional: cast and required moments | `add_subject`, `add_moment` | free; a generated subject image ~13 | ~1 min per image |
| Voiceover script | `generate_script` | about 6 credits (free if you pass your own) | ~10 s |
| Storyboard | `generate_storyboard` | about 10 credits + ~5 per scene | 1–3 min |
| Video | `start_video_generation` | shown before starting (`estimatedVideoCredits`) | 10–30 min |
| Result | `get_video_status` | free | — |

- **Confirm the cost.** Before `start_video_generation`, show the user
  `estimatedVideoCredits` from `get_project` and pass it as `max_credits`. The
  tool refuses to spend more than that.
- **Review checkpoints.** The script and the storyboard's scenes are returned for
  the user to review. Changing the script after the storyboard means generating
  the storyboard again.
- **Waiting.** Poll `get_project` every 20–30 seconds while a storyboard
  generates, and `get_video_status` every couple of minutes while the video
  renders. The user also gets an email when the video is ready. At most three
  videos can generate at once per account.
- **Failures.** If `get_video_status` reports a failure, it says what to do
  next: `resume_video_generation`, or finishing in the app via `appUrl`.
  Credits for failed steps are refunded automatically.

## 4. Product photos and videos

Media requirements:
- Photos: JPEG, PNG or WebP; at least 480×480 px; at most 15 MB. Clear, well-lit shots of the real product, one product per photo, no collages or heavy text overlays.
- Videos: MP4 or MOV (H.264 recommended); 1–60 seconds; at most 50 MB; vertical 9:16 recommended. Clips play muted. A video only appears in the ad through a custom-footage moment (add_moment, type custom-footage): uploading it alone does nothing.
- Physical products: tag every photo with the view it shows (front, left, rear, a 3/4 view…, `detail` for a close-up, `size-reference` for a scale shot). A front photo is strongly recommended.
- `detail` photos, and every photo of a digital product or service, need a description (≤240 characters) of what they show.
- At most 8 files per call.

- **By URL:** pass `media` to `create_project` or `set_product`.
- **From the user's computer** (agents that can run commands, like Claude Code
  or Cursor): `create_media_upload` returns a one-time upload URL and a ready
  `curl` command; then call `finalize_media_upload`.
- Photos found on a product page arrive unclassified a minute after
  `create_project`: `get_project` lists each one with what it `needs`. Look at
  them and tag them with `update_product_media` — the storyboard waits for it.

## 5. Optional: cast and required moments

Both are optional. Without them the script and storyboard decide everything,
and that's usually the best start.

- **Subjects** (`add_subject`) add people, pets or objects beyond the actor and
  the product, with a photo you provide or a generated image. Scenes feature them
  by tagging `@[Name]`.
- **Moments** (`add_moment`) are scenes the ad must contain: a product shot, a
  close-up, b-roll, the product in motion, a line the actor says, or a slice of
  an uploaded video. The script is written around them.
- **Uploaded videos only appear in the ad through a custom-footage moment.**
  Uploading a video alone does nothing: add a `custom-footage` moment with its
  `media_id` and the range to play.
- Add subjects and moments **before** `generate_script`. Adding them later means
  regenerating the script and the storyboard.

## 6. Troubleshooting

- **The connection fails or asks to sign in again:** remove the connector and add
  it again. Access tokens refresh automatically; a disconnected agent must
  reconnect.
- **"Video generation is not available on the free trial":** the account needs a
  paid plan — [subscribe](https://app.retiplex.com/account?tab=subscription).
- **"Not enough credits":** top up on the same page, then retry.
- **"Video generation is running on this project":** projects can't be edited
  while a video generates; wait for `get_video_status`.
- **A tool refuses with a step message:** call `get_project` and follow
  `nextTool`.
- Anything else: [support@retiplex.com](mailto:support@retiplex.com).

## 7. Tool reference

### `get_account` — Get account

The signed-in user's Retiplex account: credit balance, plan, whether it can generate videos, and the longest script it allows. Call this first, and before anything that spends credits.

_No parameters._

### `list_formats` — List ad formats

The ad formats (narrative templates) a project can use, for set_creative_brief. `custom` has no fixed structure: describe the ad as an idea instead.

_No parameters._

### `list_projects` — List projects

The user's 20 most recent video projects.

_No parameters._

### `get_project` — Get project

A project's state: product and its media (each with what it still `needs`), the cast (the `@[Name]` tags scenes can use), moments, brief, actor, script, storyboard (with its scenes once generated) and the current step, plus `nextTool` to call. Poll this while a storyboard or a subject image generates.

- `project_id` (string, required) — The project's id.

### `create_project` — Create project

Starts a new video ad for a product. Give product_url to import it, or product_name and product_description; add photos and videos by URL with `media`. Returns the project and the next step.

- `name` (string, optional) — Defaults to the product name.
- `product_url` (string, optional) — The product page. Its name, description, campaign facts and up to 3 photos are imported (5 credits).
- `product_name` (string, optional)
- `product_description` (string, optional) — What the product is and does, factually, in 2–3 sentences.
- `product_type` (`physical` \| `digital` \| `service`, optional)
- `media` (list of object, optional) — Product photos and videos to add by URL (in addition to any found on product_url). For local files use create_media_upload. Media requirements:
- Photos: JPEG, PNG or WebP; at least 480×480 px; at most 15 MB. Clear, well-lit shots of the real product, one product per photo, no collages or heavy text overlays.
- Videos: MP4 or MOV (H.264 recommended); 1–60 seconds; at most 50 MB; vertical 9:16 recommended. Clips play muted. A video only appears in the ad through a custom-footage moment (add_moment, type custom-footage): uploading it alone does nothing.
- Physical products: tag every photo with the view it shows (front, left, rear, a 3/4 view…, `detail` for a close-up, `size-reference` for a scale shot). A front photo is strongly recommended.
- `detail` photos, and every photo of a digital product or service, need a description (≤240 characters) of what they show.
- At most 8 files per call.
  - `url` (string, required) — A public photo or video URL.
  - `angle` (`detail` \| `size-reference` \| `front` \| `right` \| `top` \| `rear` \| `left` \| `bottom` \| `front-left-top` \| `front-left-bottom` \| `front-right-top` \| `front-right-bottom` \| `rear-left-top` \| `rear-left-bottom` \| `rear-right-top` \| `rear-right-bottom`, optional) — Photos only: which view of the product it shows. Tag every photo of a physical product; the storyboard picks shots by it. `detail` is a close-up (needs a description), `size-reference` shows its size (in a hand, on a desk).
  - `description` (string, optional) — What it shows, in a sentence. Needed for `detail` photos, every photo of a digital product or service, and videos. Used in prompts as-is.

### `set_product` — Set product

Changes a project's product, or adds photos and videos to it by URL. Same inputs as create_project.

- `project_id` (string, required) — The project's id.
- `product_url` (string, optional) — The product page. Its name, description, campaign facts and up to 3 photos are imported (5 credits).
- `product_name` (string, optional)
- `product_description` (string, optional) — What the product is and does, factually, in 2–3 sentences.
- `product_type` (`physical` \| `digital` \| `service`, optional)
- `media` (list of object, optional) — Product photos and videos to add by URL (in addition to any found on product_url). For local files use create_media_upload. Media requirements:
- Photos: JPEG, PNG or WebP; at least 480×480 px; at most 15 MB. Clear, well-lit shots of the real product, one product per photo, no collages or heavy text overlays.
- Videos: MP4 or MOV (H.264 recommended); 1–60 seconds; at most 50 MB; vertical 9:16 recommended. Clips play muted. A video only appears in the ad through a custom-footage moment (add_moment, type custom-footage): uploading it alone does nothing.
- Physical products: tag every photo with the view it shows (front, left, rear, a 3/4 view…, `detail` for a close-up, `size-reference` for a scale shot). A front photo is strongly recommended.
- `detail` photos, and every photo of a digital product or service, need a description (≤240 characters) of what they show.
- At most 8 files per call.
  - `url` (string, required) — A public photo or video URL.
  - `angle` (`detail` \| `size-reference` \| `front` \| `right` \| `top` \| `rear` \| `left` \| `bottom` \| `front-left-top` \| `front-left-bottom` \| `front-right-top` \| `front-right-bottom` \| `rear-left-top` \| `rear-left-bottom` \| `rear-right-top` \| `rear-right-bottom`, optional) — Photos only: which view of the product it shows. Tag every photo of a physical product; the storyboard picks shots by it. `detail` is a close-up (needs a description), `size-reference` shows its size (in a hand, on a desk).
  - `description` (string, optional) — What it shows, in a sentence. Needed for `detail` photos, every photo of a digital product or service, and videos. Used in prompts as-is.

### `update_product_media` — Update product media

Classifies a product photo or video (its view `angle`, its `description`) or removes it. Look at each photo get_project lists with `needs`, and tag it. Media requirements:
- Photos: JPEG, PNG or WebP; at least 480×480 px; at most 15 MB. Clear, well-lit shots of the real product, one product per photo, no collages or heavy text overlays.
- Videos: MP4 or MOV (H.264 recommended); 1–60 seconds; at most 50 MB; vertical 9:16 recommended. Clips play muted. A video only appears in the ad through a custom-footage moment (add_moment, type custom-footage): uploading it alone does nothing.
- Physical products: tag every photo with the view it shows (front, left, rear, a 3/4 view…, `detail` for a close-up, `size-reference` for a scale shot). A front photo is strongly recommended.
- `detail` photos, and every photo of a digital product or service, need a description (≤240 characters) of what they show.
- At most 8 files per call.

- `project_id` (string, required) — The project's id.
- `media_id` (string, required) — From get_project's `media`.
- `angle` (`detail` \| `size-reference` \| `front` \| `right` \| `top` \| `rear` \| `left` \| `bottom` \| `front-left-top` \| `front-left-bottom` \| `front-right-top` \| `front-right-bottom` \| `rear-left-top` \| `rear-left-bottom` \| `rear-right-top` \| `rear-right-bottom`, optional)
- `description` (string, optional) — What it shows, in a sentence. Needed for `detail` photos, every photo of a digital product or service, and videos. Used in prompts as-is.
- `remove` (boolean, optional) — Delete it from the project.

### `create_media_upload` — Create media upload

For a photo or video file on the user's machine (needs an agent that can run curl or make HTTP requests). Returns a one-time upload_url: PUT the file's bytes there with its Content-Type header (the returned `curl` does exactly that), then call finalize_media_upload. Media requirements:
- Photos: JPEG, PNG or WebP; at least 480×480 px; at most 15 MB. Clear, well-lit shots of the real product, one product per photo, no collages or heavy text overlays.
- Videos: MP4 or MOV (H.264 recommended); 1–60 seconds; at most 50 MB; vertical 9:16 recommended. Clips play muted. A video only appears in the ad through a custom-footage moment (add_moment, type custom-footage): uploading it alone does nothing.
- Physical products: tag every photo with the view it shows (front, left, rear, a 3/4 view…, `detail` for a close-up, `size-reference` for a scale shot). A front photo is strongly recommended.
- `detail` photos, and every photo of a digital product or service, need a description (≤240 characters) of what they show.
- At most 8 files per call.

- `project_id` (string, required) — The project's id.
- `content_type` (`image/jpeg` \| `image/png` \| `image/webp` \| `video/mp4` \| `video/quicktime`, required)

### `finalize_media_upload` — Finalize media upload

Checks a file PUT to an upload_url against the requirements and adds it to the project's media. A file that fails is deleted and the reason returned.

- `project_id` (string, required) — The project's id.
- `upload_id` (string, required) — From create_media_upload.
- `angle` (`detail` \| `size-reference` \| `front` \| `right` \| `top` \| `rear` \| `left` \| `bottom` \| `front-left-top` \| `front-left-bottom` \| `front-right-top` \| `front-right-bottom` \| `rear-left-top` \| `rear-left-bottom` \| `rear-right-top` \| `rear-right-bottom`, optional) — Photos only: which view of the product it shows. Tag every photo of a physical product; the storyboard picks shots by it. `detail` is a close-up (needs a description), `size-reference` shows its size (in a hand, on a desk).
- `description` (string, optional) — What it shows, in a sentence. Needed for `detail` photos, every photo of a digital product or service, and videos. Used in prompts as-is.

### `add_subject` — Add subject

Optional. Adds someone or something to the cast beyond the narrator and the product — a side character (kind person), a pet, or an object — so moments can feature them by tagging @[Name]. Skip it unless the ad needs them. The image is either yours (`image_url`, or `upload_id` from create_media_upload; a photo meeting the requirements, ≥480×480 px) or generated (`generate: true`, a few credits, ready in about a minute: a person is drawn from `archetype`, the actor form's fields; a pet or object from `description`). Add subjects before the moments that tag them, and both before generate_script.

- `project_id` (string, required) — The project's id.
- `name` (string, required) — Short and unique; scenes tag it as @[name].
- `kind` (`person` \| `pet` \| `object`, required)
- `description` (string, required) — Who or what it is, in a sentence or two. Used in prompts.
- `image_url` (string, optional)
- `upload_id` (string, optional)
- `generate` (boolean, optional)
- `archetype` (object, optional) — generate + kind person only: their look.
  - `sex` (`male` \| `female` \| `androgynous`, required)
  - `age` (integer, required)
  - `skinColor` (`very light/pale` \| `light/fair` \| `light-medium-brown/olive` \| `medium-brown/tanned` \| `medium-dark/brown` \| `dark/deep brown` \| `very dark/ebony` \| `black`, required)
  - `ethnicity` (string, required)
  - `bodyType` (`slim/lean` \| `athletic/fit` \| `average` \| `curvy` \| `stocky/broad` \| `plus-size`, required)
  - `hairstyle` (string, required)
  - `facialFeatures` (string, optional)
  - `clothing` (string, required)

### `remove_subject` — Remove subject

Removes a subject (or a pending/failed subject image) that no moment tags.

- `project_id` (string, required) — The project's id.
- `subject_id` (string, required) — From get_project's `cast` or `pendingSubjects`.

### `add_moment` — Add required moment

Optional — except for uploaded videos. Adds a required moment: a scene the ad must contain; the script is written around it and the storyboard places it where it fits. Without moments the script and storyboard decide everything, which is fine. BUT an uploaded video only appears in the ad through a `custom-footage` moment — uploading it alone does nothing; give `footage` (its media_id and the range to play, muted). Types: product-shot (someone holds/uses the product, face in frame), product-shot-faceless (close look at the product, no face), b-roll (supporting footage: a place, object, mood), product-action (the product in motion, from its photos), talking-person (the narrator says `dialogue` to camera), custom-footage. Tag who's in frame in the description with @[Name] from get_project's `cast` (e.g. "@[Main Character] pours @[Glow Serum] into her palm"). Add moments before generate_script; the total must fit the script's length.

- `project_id` (string, required) — The project's id.
- `type` (`product-shot` \| `product-shot-faceless` \| `b-roll` \| `product-action` \| `talking-person` \| `custom-footage`, required)
- `description` (string, required) — What happens, with @[Name] tags for who/what is in frame.
- `dialogue` (string, optional) — talking-person only: the exact words the narrator says.
- `text_overlay` (string, optional) — On-screen text for this moment.
- `product_media_ids` (list of string, optional) — Product photos the shot must feature (from get_project's `media`).
- `footage` (object, optional) — custom-footage only: which clip and which part of it plays.
  - `media_id` (string, required) — A video from get_project's `media`.
  - `start_seconds` (number, required)
  - `duration_seconds` (number, required)

### `remove_moment` — Remove moment

Removes a required moment (from get_project's `moments`) from the ad.

- `project_id` (string, required) — The project's id.
- `moment_id` (string, required) — From get_project's `moments`.

### `set_creative_brief` — Set creative brief

Sets the ad's format and campaign facts (who it's for, the benefit to sell, the action to drive). Facts you leave out are deduced from the product (a few credits). For the `custom` format pass `idea` — the ad you have in mind, in your own words — and a full brief is written from it.

- `project_id` (string, required) — The project's id.
- `format` (`problem-solution` \| `testimonial-review` \| `before-after-transformation` \| `reaction-video` \| `storytime` \| `custom`, optional) — From list_formats. Required the first time.
- `target_audience` (string, optional)
- `benefit_to_highlight` (string, optional)
- `primary_ad_goal` (string, optional) — The action viewers should take, e.g. "Buy now", "Download the app".
- `funnel_stage` (`top-of-funnel` \| `mid-funnel` \| `bottom-funnel`, optional)
- `idea` (string, optional) — custom format only: the ad you want, described freely.

### `set_actor` — Set actor

Casts the on-camera narrator and renders their portrait, which every scene is generated from — the app's actor form. Leave `archetype` out to cast someone fitting the audience automatically. Pass `archetype` to design them: for a project with an actor, only the fields you give change (e.g. just `clothing`); a first actor needs every field except facialFeatures. Each call renders a new portrait (1 credit); show the user previewUrl.

- `project_id` (string, required) — The project's id.
- `archetype` (object, optional)
  - `sex` (`male` \| `female` \| `androgynous`, optional)
  - `age` (integer, optional)
  - `skinColor` (`very light/pale` \| `light/fair` \| `light-medium-brown/olive` \| `medium-brown/tanned` \| `medium-dark/brown` \| `dark/deep brown` \| `very dark/ebony` \| `black`, optional)
  - `ethnicity` (string, optional) — e.g. "Eastern European"
  - `bodyType` (`slim/lean` \| `athletic/fit` \| `average` \| `curvy` \| `stocky/broad` \| `plus-size`, optional)
  - `hairstyle` (string, optional) — e.g. "long blonde straight hair"
  - `facialFeatures` (string, optional) — e.g. "freckles, green eyes"; null clears it.
  - `clothing` (string, optional) — Upper-body clothing only, e.g. "casual white t-shirt".

### `generate_script` — Generate script

Writes the voiceover script from the brief (calling it again writes a different variation), or saves `script` if you pass one. target_seconds sets the length (10–120s; trial accounts less). Changing the script after a storyboard means regenerating the storyboard.

- `project_id` (string, required) — The project's id.
- `target_seconds` (integer, optional)
- `script` (string, optional) — Your own script, spoken text only. Skips generation (free).

### `generate_storyboard` — Generate storyboard

Plans the scenes from the script, actor and product photos. Runs in the background for 1–3 minutes: poll get_project until storyboard.scenes > 0, then review the scenes with the user. Needs a paid plan. Regenerating replaces the scenes.

- `project_id` (string, required) — The project's id.

### `start_video_generation` — Start video generation

Generates the video from the storyboard: hook, voice, every scene, then the final render. Takes 10–30 minutes and spends the estimate get_project returns (estimatedVideoCredits). Confirm that with the user and pass it as max_credits. Poll get_video_status.

- `project_id` (string, required) — The project's id.
- `max_credits` (integer, required) — The most this run may cost; it refuses above it.

### `get_video_status` — Get video status

Progress of a project's video generation, and the finished video's URL once it's rendered. Poll every couple of minutes, not faster.

- `project_id` (string, required) — The project's id.

### `resume_video_generation` — Resume video generation

Retries a failed or stalled video generation from where it stopped, when get_video_status suggests it.

- `project_id` (string, required) — The project's id.

---

This guide: https://app.retiplex.com/help/agents (Markdown: https://app.retiplex.com/help/agents.md). Connected agents
can also read it as the MCP resource `retiplex://guide`.