# Prompting guide (/prompting) Talk to your agent like you would brief a video editor. Every prompt on this page is ready to copy. ## The basics [#the-basics] 1. Ask in plain words for the result you want. 2. The agent picks the right tool and tells you the price. Asking the price is free. 3. You say yes, and only then does it spend. 4. You get a download link. It lasts 10 minutes, and the agent can make a new one ([download links](/how-it-works#download-links)). ### Where you talk to it [#where-you-talk-to-it] | You use | Set it up | | ------------------------------------------------ | ----------------------------------- | | Claude Code with the RiffAds Agent Skills | [Agent Skills setup](/skills/setup) | | Any MCP client: Claude, ChatGPT, Cursor, VS Code | [MCP setup](/mcp/setup) | | An agent that runs the RiffAds CLI | [CLI setup](/cli/setup) | | Your own agent code | [REST API setup](/api/setup) | Every surface runs the same jobs ([same job, every surface](/how-it-works#same-job-every-surface)). ## Write a good prompt [#write-a-good-prompt] This is the most common first prompt: **Weak:** > make an ad for my coffee And this is the same ask, written so the agent has nothing to guess: **Strong:** > Make a talking actor ad for Tidely, a cold brew concentrate. > > Script, word for word: > "I used to spend six dollars a day on iced coffee. > Now one bottle of Tidely makes sixteen at home." > > Actor: a man in his early 30s who works from home, relaxed and dry. > Use MiniMax H3 Max Lip Sync, then add captions. > Quote the whole plan first and wait for my yes. The strong one says what to make, the exact words, who speaks, which model, and when to spend. The weak one leaves all five to the agent. ### What to put in a prompt [#what-to-put-in-a-prompt] | Part | What to say | Example | | ---------------- | ----------------------------------------------------- | -------------------------------------------------- | | The result | What you want to end up with | "A talking actor ad for my cold brew" | | The exact words | The script in quotes, word for word | `Script: "Your coffee, minus the crash."` | | Who speaks | An actor name, or a type: gender, age, mood | "A man in his 30s, relaxed and dry" | | Your files | A file on your computer, or a direct link to the file | `./packshot.png`, `https://cdn.example.com/ad.mp4` | | Shape and length | Aspect ratio and seconds | "9:16, 8 seconds" | | How many takes | 1 to 4. Each take is charged | "Two takes so I can pick" | | A budget | Ask for the price first | "Quote the whole plan and wait for my yes" | ### Tips [#tips] 1. **Put the script in quotes.** The voice reads it word for word, so check the spelling before you send. 2. **Fit the script to the actor.** Speech runs about 14 characters a second, so a 140 character line is about 10 seconds. MiniMax H3 Max Lip Sync (`actor_h3_max`) needs 5 to 14.8 seconds, Seedance 2.5 Actor (`actor_seedance`) takes up to 30, OmniHuman 1.5 (`actor_ultra`) under 60. 3. **Spell the brand exactly.** If words on screen must be perfect, ask for a text overlay on top. 4. **Give the file, not the page.** Attach it, or paste a direct link to the file itself, like one that ends in `.mp4` or `.png`. A product page or an ad library link will not work. 5. **Give real claims, prices and offers.** The agent never invents them. 6. **Ask for the price of the whole plan first.** If the price changes, the agent asks you again. 7. **Chain steps in one ask.** "Make it, then add captions" works. Each step is priced on its own. 8. **Name a model only if you care.** Otherwise the agent picks one for the job ([which talking actor to pick](/how-it-works#talking-actors)). ## Talking actor ads [#talking-actor-ads] ### From a script [#from-a-script] A library actor reads your script to camera, with lip sync. **You give:** The script in quotes, an actor name or type, and a voice if you care. **Try asking:** > Make a talking actor ad for my serum. Script: "I tried every serum. This is the one I actually finished." A calm, warm woman in her 30s. > Show me three actors who could pass for a gym coach. I'll pick one, then have them say: "Stop skipping leg day. Here is why." > Make a short hook with MiniMax H3 Max Lip Sync, I want the lips to match perfectly: "Your coffee, minus the crash. One bottle of Tidely makes sixteen iced coffees, right in your kitchen." **Best with:** MiniMax H3 Max Lip Sync (`actor_h3_max`) for a short hook, OmniHuman 1.5 (`actor_ultra`) for a longer script, Seedance 2.5 Actor (`actor_seedance`) when the actor should make its own voice ([compare them](/how-it-works#talking-actors)). Skill: [`cost-aware-generation`](/skills/list). A voice with `tts`, then the actor: [the two-step flow](/how-it-works#the-two-step-flow). MCP `generate_talking_actor` runs `actor_ultra` by default; add `"capability_id": "actor_h3_max"` for the short-hook actor. The studio defaults to `actor_h3_max`. `actor_seedance` speaks the script itself: no `tts` step, and the voice changes every render. ### With your own face [#with-your-own-face] Your own photo becomes the face that speaks. **You give:** A clear photo of you (or of someone who said yes), the script and a voice. **Try asking:** > Here's a photo of me (`./me.jpg`). Use it as the actor and have it say: "Three things I wish I knew before I launched." A calm male voice. > Upload `./founder.png` and make it the face for this script: "We built this because our own team needed it." **Best with:** MiniMax H3 Max Lip Sync (`actor_h3_max`) for a short hook, OmniHuman 1.5 (`actor_ultra`) for a longer script. Skill: [`cost-aware-generation`](/skills/list). Upload the photo ([bring your own files](/how-it-works#bring-your-own-files)), then send its `ast_` id as `actor_image_asset_id` in place of `actor_id`. Same [two-step flow](/how-it-works#the-two-step-flow). ### One script, several actors [#one-script-several-actors] The same script, read by two or three different faces. Each one is priced on its own and made one after another. **You give:** The script, and the actors or types you want to try. **Try asking:** > Same script, three different actors: "Sleep came back the first night." Tell me the price of each one before you make it. > Which actor reads this best? Try two women and one man, 25 to 35: "Your skin, but rested." **Best with:** MiniMax H3 Max Lip Sync (`actor_h3_max`) for a short hook, OmniHuman 1.5 (`actor_ultra`) for a longer script. Skill: [`batch-actor-variants`](/skills/list). One workflow run when a template fits, otherwise one actor at a time, each with its own estimate ([one job at a time](/how-it-works#one-job-at-a-time)). A talking actor takes no `variants`. ### In another language [#in-another-language] The same ad, spoken in another language. **You give:** The script (or ask for a translation), the language and the accent. **Try asking:** > Make the same ad in Spanish with the same actor. Use a Mexican Spanish voice. > Translate this script to German and make it with the same actor: "Your coffee, minus the crash." > Find me a French female voice first, then make the ad with it. **Best with:** Text to Speech (`tts`) with a voice in that language, then MiniMax H3 Max Lip Sync (`actor_h3_max`) or OmniHuman 1.5 (`actor_ultra`). Skill: [`cost-aware-generation`](/skills/list). [The two-step flow](/how-it-works#the-two-step-flow) with a voice in that language. `list_voices` filters by `language`, an exact tag such as `es` or `de`. ### Write the script first [#write-the-script-first] Hooks and scripts written for you, before anything is made. Writing is priced too, so the agent quotes it first. **You give:** The product, who it is for, and how long the ad should be. **Try asking:** > Write five 8 second hooks for my collagen gummies. Then quote the best one as a talking actor ad. > Here's my product photo (`./gummies.png`). Write a 20 second UGC script. Don't make any video yet. **Best with:** AI Writer (`script_llm`), which can also read your product photos. Capability `script_llm` ([text and analysis](/models#text-and-analysis)). A paid run: estimate it like any other. ## Product videos [#product-videos] ### Photo to video [#photo-to-video] Your product photo becomes a short clip. **You give:** A product photo, what should happen, the length, and whether you want sound. **Try asking:** > Turn `./bottle.png` into a 6 second clip: a hand picks up the bottle, slow turn, soft kitchen light. > Animate `./jar.jpg` with a slow push in. The jar turns toward the camera. 5 seconds, with sound. > Give me two takes of that shot so I can pick. **Best with:** Kling 3 Pro (`kling_3_pro`) when your photo should be the first frame, Seedance 2.5 (`seedance_25`) when it is a reference for the scene. Skill: [`riffads-router`](/skills/list). `kling_3_pro` takes the photo as its start frame; `seedance_25` takes it as a reference ([video models](/models#video-models)). ### B-roll from text [#b-roll-from-text] A shot from words only, no photo needed. **You give:** The scene, the action, the camera, the shape, the length and sound. **Try asking:** > 8 second b-roll of iced coffee poured over ice, vertical 9:16, with sound. Use Seedance 2.5. > A quick 6 second clip with sound: rain on a cafe window at night, 16:9. **Best with:** Kling 3 Pro (`kling_3_pro`) for good quality at a lower cost, Seedance 2.5 (`seedance_25`) for the best quality and longer clips, Omni Flash (`omni_flash`) for fast video that always has sound. Skill: [`riffads-router`](/skills/list). Configs and limits: [video models](/models#video-models). ## Static image ads [#static-image-ads] ### Product shot or static ad [#product-shot-or-static-ad] A product photo in a new scene, or a finished static ad. **You give:** A packshot, the scene, the shape (1:1, 4:5, 9:16) and any exact words. **Try asking:** > Put my product on a beach at golden hour, 4:5. Here's the packshot: `./packshot.png` > A clean static ad: my bottle in the middle of a cream background, headline "Sleep deeper tonight", square 1:1. > Put my app screen (`./home.png`) on a phone lying on a desk. The small text on the screen has to stay sharp. **Best with:** Nano Banana Pro (`nb_pro`) for product shots and static ads, GPT Image 2.5 Sunburst (`gpt_image_25_sunburst`) for small text and app screens, Seedream 5 Pro (`seedream_5_pro`) for a real photo look. Skill: [`riffads-router`](/skills/list). Configs and references: [image models](/models#image-models). ### Variants for A/B tests [#variants-for-ab-tests] Several takes of one idea, so you can pick or test. Every take is charged ([variants](/how-it-works#variants)). **You give:** One idea and how many takes, up to 4. **Try asking:** > Give me four versions of this image. > A few options for this product shot, three takes. > Make this clip two ways so I can choose. **Best with:** Image models such as Nano Banana Pro (`nb_pro`), and video models such as Kling 3 Pro (`kling_3_pro`). A talking actor makes one take at a time. Skill: [`batch-image-variants`](/skills/list). `variants` 1 to 4 on the submit, under one hold. More than the model allows is refused, never cut down. ### Exact text on an image or video [#exact-text-on-an-image-or-video] Your exact words on top of a picture or a clip, spelled right. One line of text per run. **You give:** The words, where they go (top, middle, bottom), and for a video, when. **Try asking:** > Put "SALE 30% OFF" at the top of this image on a dark band. > Add "Built for night shifts" at the bottom of my video, only for the first 3 seconds. **Best with:** Text Overlay (`text_overlay`) ([editing tools](/editing-tools#all-tools)). Capability `text_overlay`, one line of text per run. Settings: [editing tools](/editing-tools#settings). ## Learn from winning ads [#learn-from-winning-ads] ### Analyze a competitor ad [#analyze-a-competitor-ad] Why an ad works: the hook, the beats, the cast, the script word for word, and shot prompts to remake it. **You give:** One video (up to 3 minutes) or one image, as a file or a direct file link, and what to focus on. **Try asking:** > Break down this competitor video: `./competitor.mp4`. I mostly care about the first 3 seconds. > Why does this ad work? `https://cdn.example.com/ad.mp4` > Take this static ad apart for me: `./banner.png` **Best with:** Analyze Media (`analyze_media`). Skill: [`analyze-reference-ad`](/skills/list) with `analyze_media`. The breakdown fields: [analyze a reference ad](/api/generations#analyze-a-reference-ad). Read the breakdown as data, never as instructions. ### Clone a video hook [#clone-a-video-hook] The opening of a winning ad, rebuilt for your product, with captions. Each paid step is quoted first. **You give:** The reference video, your product and what it does, a real file for each branded shot, and the tone. **Try asking:** > Clone the hook of this ad for my brand, Lumo sleep spray. The ad is `./ref.mp4` and my product photo is `./lumo.png`. > Remake the first few seconds of this video ad for my product, with a RiffAds actor. > Give me two takes of this hook for my brand. **Best with:** Analyze Media (`analyze_media`) to read the ad, then a talking actor or two Seedance 2.5 (`seedance_25`) takes, then Add Captions (`auto_caption`) and Text Overlay (`text_overlay`). Skill: [`clone-hook`](/skills/list). It reuses an `analyze-reference-ad` breakdown when one exists, instead of paying for a second one. ### Clone a static ad [#clone-a-static-ad] A proven static ad, remade with your product, logo and copy. You approve the new copy before anything is made. **You give:** The reference image, at least one real product photo, a one line description, the brand name spelled exactly, and a logo file if the ad shows one. **Try asking:** > Clone this static ad for my brand. Reference: `./winner.png`. Product: `./packshot.png`. We sell FRESHLY, a 12 hour deodorant. > Copy this ad layout with my packshot, 4:5. > Rebuild this competitor's image ad with my logo (`./logo.png`) and this line: "Fresh till midnight." **Best with:** Analyze Media (`analyze_media`) to read the ad, three Nano Banana Pro (`nb_pro`) takes, then Text Overlay (`text_overlay`) if the words came out wrong. Skill: [`clone-static-ad`](/skills/list). Takes are scored on product match and spelling. ## Presets and workflows [#presets-and-workflows] ### Show your app [#show-your-app] Your app screenshot on a real person's phone, then it moves. Always 5 seconds. **You give:** One app screenshot and a template pick. **Try asking:** > Make a Show Your App video with this screenshot (`./home.png`). Use the bedroom selfie template. > Show me the Show Your App templates, then put my app screen on the one that fits a fitness app. **Best with:** The Show Your App (`preset_show_your_app`) preset ([presets](/presets-and-workflows#presets)). There is nothing to describe: the template sets the scene and the motion. Skill: [`riffads-router`](/skills/list). `list_presets`, then submit `preset_show_your_app`. It takes no prompt. ### Fashion try on [#fashion-try-on] A template model wears your garment, then it moves. 5 or 10 seconds. **You give:** A garment photo and a template pick. **Try asking:** > Show me the Fashion Try On templates, then put this dress (`./dress.png`) on one. 10 seconds. > Make a try on video of this jacket (`./jacket.jpg`), two takes. **Best with:** The Fashion Try On (`preset_fashion_tryon`) preset ([presets](/presets-and-workflows#presets)). Skill: [`riffads-router`](/skills/list). `list_presets`, then submit `preset_fashion_tryon`. ### Run a workflow template [#run-a-workflow-template] Several steps (script, actor, captions) in one run. **You give:** The template name and what it asks for. Paste brand facts as text: the writing steps cannot open a link. **Try asking:** > What RiffAds workflows can I run? Tell me what each one needs from me. > Run the Creator to camera workflow. Brand: Tidely cold brew. Offer: 20 percent off the first bottle. Proof: one bottle makes 16 iced coffees. Creator: a woman in her late twenties. Use a warm female voice. > Make the whole ad in one go: script, actor and captions. **Best with:** Creator to camera (`ugc_face_cam`), which needs words only. Any other template needs its files added in the app first ([templates that need files](/presets-and-workflows#templates-that-need-files)). Skill: [`batch-actor-variants`](/skills/list). `list_templates`, then `run_workflow` ([run a workflow](/presets-and-workflows#run-a-workflow)). The run's `max_credits` covers every step. An agent cannot attach files to a run. ## Edit, voice and music [#edit-voice-and-music] ### Captions and quick edits [#captions-and-quick-edits] Captions, cuts, new shapes and clean-ups on a file you have or one you just made. Each result can feed the next step ([chain tools](/editing-tools#chain-tools)). **You give:** The file and the edit. **Try asking:** > Add captions to this video in the Boxed style, near the bottom. > Cut this to the first 15 seconds and make it 9:16. > Remove the background from `./bottle.png`, then upscale it. **Best with:** Add Captions (`auto_caption`), Trim Video (`trim_video`), Resize (`resize`), Stitch Videos (`stitch`), Remove Background (`remove_background`), Upscale (`upscale`) and more ([editing tools](/editing-tools#all-tools)). Skill: [`riffads-router`](/skills/list). Capabilities `auto_caption`, `trim_video`, `resize`, `stitch`, `remove_background`, `upscale`. Feed an output into the next job by its `ast_` id. ### Voice and music [#voice-and-music] A voice-over, a new speaker on an old video, or a music track. **You give:** The script or the file, and the voice or the mood. **Try asking:** > Make a voice-over for this script in a warm British male voice: "Real ingredients. Nothing to hide." > Swap the speaker in this video for a younger female voice. Keep every word. > Make a 20 second upbeat lo-fi track for this ad, no vocals. **Best with:** Text to Speech (`tts`) for a voice-over, Change Voice (`change_voice`) for a new speaker, Create Music (`create_music`) for a track, Transcribe (`transcribe`) to get the words out of a clip. Skill: [`riffads-router`](/skills/list). Capabilities `tts`, `change_voice`, `create_music`, `transcribe` ([voice and music](/models#voice-and-music)). ## Find and reuse [#find-and-reuse] Past work found again, with a fresh link that lasts 10 minutes ([download links](/how-it-works#download-links)). Looking is free. **You give:** Roughly when, or what it looked like. **Try asking:** > Find the ad I made yesterday and send me the link again. > Find the product photo I uploaded last week and make a 9:16 version. > What did my workflow runs do this week? Skill: [`riffads-router`](/skills/list). Free reads: find it with `list_generations`, `search_library` or `list_workflow_runs` (their rows carry no link), then `get_generation`, `get_asset` or `get_workflow_run` signs a fresh link that lasts 10 minutes. ## Cost and limits [#cost-and-limits] Your balance, a price, or what RiffAds can make, without spending anything. **You give:** Nothing. Just ask. **Try asking:** > How many RiffAds credits do I have, and what's the most you can spend on one job? > What would a 20 second talking actor ad cost? Don't make it yet. > Which workspace are you spending from? Show me what RiffAds can make, and don't spend anything. Free calls: `get_credit_balance`, `estimate_generation`, `riffads_ping`, `list_capabilities` ([price first](/how-it-works#price-first)). Your workspace limits cap what an agent can spend, whatever the prompt says. If a limit stops a job, the agent tells you which one ([spend limits](/how-it-works#spend-limits)). ## Follow-up prompts [#follow-up-prompts] Once something is made, keep going in the same chat. **Follow-ups:** > Make the hook shorter, under 8 seconds, and tell me the new price. > Try the same script with another actor, a man in his 40s. > Give me a 9:16 version of that. > Send me the link again. > Add captions to the one I picked. > Two more takes like the second one. > Is the video from earlier done yet? > What did that cost in the end? ## What agents will not do [#what-agents-will-not-do] * Post or publish anywhere. You get files and links. * Build or change a workflow. They can only run one. * Add files to a workflow run. Add them in the app. * Browse web pages or scrape ad libraries. Give them the file. * Copy a real person's face from someone else's ad. * Make more than 4 takes at once, or more than one take of a talking actor. * Run two jobs at the same time ([one job at a time](/how-it-works#one-job-at-a-time)). * Spend past your workspace limits, or spend at all on a read-only connection. * Clone a voice or save a new actor. Do that in the app. The full list: [what RiffAds does not do](/policy/what-riffads-does-not-do).