For agents: the raw Markdown is at /help/agents.md.
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 follownextToolfromget_project. Always tell the user what a step costs before running it.
1. Create a Retiplex account
- Sign up at https://app.retiplex.com/sign-up with email or Google.
- 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. Plans and credit prices: Billing & credits.
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/mcpand 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 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; pass language for an ad not in English) |
create_project |
7 credits with a URL | seconds |
| Classify product photos | view_images, then update_product_media |
free | instant |
| Format and campaign facts | set_creative_brief (list_formats) |
a few credits if facts are deduced | seconds |
Spoken language and accent, if not set on create_project |
set_narrator_voice |
free | instant |
| On-camera actor | set_actor |
about 14 credits (17 on Premium: the portrait is cast on Seedream) | ~15 s |
| Optional: cast and required moments | add_subject, add_moment |
free; a generated subject image ~10 | ~1 min per image |
| Voiceover script | generate_script |
about 8 credits (free if you pass your own) | ~10 s |
Storyboard (pick video_quality: standard, or premium — English only for now) |
generate_storyboard |
about 13 credits + ~7 per scene | 1–3 min |
| Video | start_video_generation |
shown before starting (estimatedVideoCredits); Premium costs about 29 credits per second of video |
10–30 min |
| Result | get_video_status |
free | — |
- Images come from Retiplex. The actor's portrait (
previewUrl), subject images and the scenes are what the video is made from. Agents show the user those URLs and never generate an image of their own;view_imageslets an agent look at the project's photos and portrait. - The project card. In apps that display MCP Apps (Claude, ChatGPT), the
agent can show a live card of the project: progress, the actor, the product
photos, the storyboard's scenes and the finished video to watch. It opens with
show_project,set_actor,generate_storyboardandstart_video_generation, and updates itself while generating. - Confirm the cost. Before
start_video_generation, show the userestimatedVideoCreditsfromget_projectand pass it asmax_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_projectevery 20–30 seconds while a storyboard generates, andget_video_statusevery 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_statusreports a failure, it says what to do next:resume_video_generation, or finishing in the app viaappUrl. 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…,
detailfor a close-up,size-referencefor a scale shot). A front photo is strongly recommended.detailphotos, 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
mediatocreate_projectorset_product.From the user's computer (agents that can run commands, like Claude Code or Cursor):
create_media_uploadreturns a one-time upload URL and a readycurlcommand; then callfinalize_media_upload.Photos found on a product page arrive unclassified a minute after
create_project:get_projectlists each one with what itneeds.Classifying:
view_imagesshows the agent every photo that still needs it, captioned with itsmedia_id; the agent tags each withupdate_product_media(its view, or a description). 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, or a slice of an uploaded video. The script is written around them. A line the actor says to camera can't be a moment: the script and storyboard place those. - Uploaded videos only appear in the ad through a custom-footage moment.
Uploading a video alone does nothing: add a
custom-footagemoment with itsmedia_idand 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.
- "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_projectand follownextTool. - Anything else: support@retiplex.com.
7. Tool reference
show_project — Show project
Shows the user a live card of the project: its progress, the actor's portrait, the product photos, the storyboard's scenes and, once rendered, the video to watch. It updates itself while a storyboard or video generates. Use it whenever the user wants to see the project or the result; in clients that can't display it, share the URLs from get_project instead.
project_id(string, required) — The project's id.
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 (previewUrl: their portrait), 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. To see the photos and the portrait, call view_images.
project_id(string, required) — The project's id.
view_images — View images
Shows you the project's images so you can look at them: by default the actor's portrait and every product photo that still needs classifying (all photos once none do), each captioned with its media_id. Use it before update_product_media to see which view each photo shows. These are the images Retiplex uses; show the user their URLs, never an image of your own.
project_id(string, required) — The project's id.media_ids(list of string, optional) — Specific product photos to show (from get_project'smedia).actor(boolean, optional) — Include the actor's portrait. Default: only when media_ids is not given.
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.video_quality(standard|premium, optional) — Ask the user first. standard (default, affordable) or premium (Seedance 2.5, most realistic; English only for now, so not with a non-English language). It also decides how set_actor casts the actor: premium casts them on Seedream 5.0, the only faces Seedance films.language(en|cs|nl|de|it|pl|sk|es, optional) — Ask the user which language the ad is spoken in unless it is obvious (a Spanish market means "es"). Default en. One of: en (English), cs (Czech), nl (Dutch), de (German), it (Italian), pl (Polish), sk (Slovak), es (Spanish). Set it BEFORE the creative brief and script (create_project or set_narrator_voice): they are written in it.language_accent(string, optional) — Optional regional accent, e.g. "Castilian Spanish" or "Mexican Spanish". Defaults to a native accent of the language; changing the language clears it.product_url(string, optional) — The product page. Its name, description, campaign facts and up to 3 photos are imported (7 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…,
detailfor a close-up,size-referencefor a scale shot). A front photo is strongly recommended. detailphotos, 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.detailis a close-up (needs a description),size-referenceshows its size (in a hand, on a desk).description(string, optional) — What it shows, in a sentence. Needed fordetailphotos, 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. 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 (7 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…,
detailfor a close-up,size-referencefor a scale shot). A front photo is strongly recommended. detailphotos, 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.detailis a close-up (needs a description),size-referenceshows its size (in a hand, on a desk).description(string, optional) — What it shows, in a sentence. Needed fordetailphotos, 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 (view_images shows them, captioned with their media_id), and tag it with what you see. 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…,
detailfor a close-up,size-referencefor a scale shot). A front photo is strongly recommended.detailphotos, 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'smedia.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 fordetailphotos, 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…,
detailfor a close-up,size-referencefor a scale shot). A front photo is strongly recommended.detailphotos, 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. If file inspection, classification, or saving fails, the uploaded file is deleted from Retiplex storage and the error is returned. A deleted upload must be uploaded again before retrying.
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.detailis a close-up (needs a description),size-referenceshows its size (in a hand, on a desk).description(string, optional) — What it shows, in a sentence. Needed fordetailphotos, 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'scastorpendingSubjects.
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 (the product in frame, held or used by whoever you tag — their face shows), product-shot-faceless (the same, but the narrator shows only their hands — 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|custom-footage, required)description(string, required) — What happens, with @[Name] tags for who/what is in frame.text_overlay(string, optional) — On-screen text for this moment, in the project's spoken language.product_media_ids(list of string, optional) — Product photos the shot must feature (from get_project'smedia).footage(object, optional) — custom-footage only: which clip and which part of it plays.media_id(string, required) — A video from get_project'smedia.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'smoments.
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. Also sets the narrator's spoken language and accent (language, language_accent) when given; to change only those, use set_narrator_voice, which doesn't recast. Each call renders a new portrait (7 credits, 10 on Premium). Show the user previewUrl: it is the actor Retiplex uses; never generate or substitute a picture of them yourself.
project_id(string, required) — The project's id.language(en|cs|nl|de|it|pl|sk|es, optional) — Ask the user which language the ad is spoken in unless it is obvious (a Spanish market means "es"). Default en. One of: en (English), cs (Czech), nl (Dutch), de (German), it (Italian), pl (Polish), sk (Slovak), es (Spanish). Set it BEFORE the creative brief and script (create_project or set_narrator_voice): they are written in it.language_accent(string, optional) — Optional regional accent, e.g. "Castilian Spanish" or "Mexican Spanish". Defaults to a native accent of the language; changing the language clears it.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".
set_narrator_voice — Set narrator voice
Sets the narrator's spoken language and accent (the app's "Narrator's voice") without touching the actor. Free. The script, every talking scene, the voice and the captions follow it. A script written in the old language must be regenerated (generate_script) or rewritten and passed as script; get_project says so in scriptWarning. An existing storyboard goes stale.
project_id(string, required) — The project's id.language(en|cs|nl|de|it|pl|sk|es, optional) — Ask the user which language the ad is spoken in unless it is obvious (a Spanish market means "es"). Default en. One of: en (English), cs (Czech), nl (Dutch), de (German), it (Italian), pl (Polish), sk (Slovak), es (Spanish). Set it BEFORE the creative brief and script (create_project or set_narrator_voice): they are written in it.language_accent(string, optional) — Optional regional accent, e.g. "Castilian Spanish" or "Mexican Spanish". Defaults to a native accent of the language; changing the language clears it.
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, in the project's spoken language (narratorVoice.language). 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. video_quality picks the models the video is filmed with: "standard" (default — Grok Imagine and MiniMax H3, affordable) or "premium" (Seedance 2.5 for every scene, most realistic, about 29 credits per second of video; English only for now). Ask the user which they want before the first storyboard.
project_id(string, required) — The project's id.video_quality(standard|premium, optional)
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.
If you have any questions about this document, please contact us at support@retiplex.com