# Make videos with Opus Motion: guide for AI agents

You are a coding agent inside someone's project, and they asked for a video for it. Opus Motion has video templates. You read the repo, talk with the person, and make a draft: a link that opens Opus Motion with the video playing live with your texts, images and clips. They review it and export the MP4 themselves.

**You don't make or render the video** (no HyperFrames, Remotion, ffmpeg or video skills): you fill a template over HTTP.

Plain HTTPS and JSON at https://opusmotion.com. No key, no account, no MCP.

**Talk before you choose.** Never pick a template in silence. At most two messages before the draft: (1) what you understood plus your questions, (2) your proposals. If the person already said "you choose" or "just do it", use the defaults below and say that you did.

**If the API refuses** (a 429 or a 5xx), tell the person what it said and stop. Never open the site in a browser to fill the studio by hand.

**Read what they asked**; don't ask again what it answers:
- **Research which fit best:** search wide in step 3 (several categories, both formats, premium too unless they said free) and propose your 3 to 5 best, ranked, each with why.
- **A launch, a new feature, a vertical:** that is the purpose or format. A new feature: find it in the recent commits or the CHANGELOG, and say which.
- **A template they picked** (its page's link or its title): go straight to step 4, in the format the prompt names.

## 1. Read the repo
- The README, the landing page's copy (`app/page.*`, `src/pages/index.*`, `index.html`, i18n or content files), `package.json` and `docs/`: the name as written, what it does, who it's for, 3 to 5 real benefits, real numbers, the call to action, the language.
- Brand: a logo (`public/`, `assets/`, `src/assets/`: logo.svg, logo.png, icon.png, favicon.svg) and the colors (`tailwind.config.*`, or CSS variables like `--primary`).
- Images: real screenshots (desktop or phone), product photos, the app icon (`docs/`, `screenshots/`, `marketing/`, `public/`, README images).
- Videos: real clips of the product (screen recordings or demos, `.mp4` or `.mov`, in `public/`, `docs/`, `marketing/`, `assets/`).
- Only what is in the repo. Never invent a feature, a number, a customer or a price. Never generate or fake a screenshot or a video of the product.

## 2. Say what you understood, and ask once
`GET https://opusmotion.com/api/v1/templates` first: its `summary` has the real premium prices (`premiumUsdPerExport`) and the categories. Then one message:

> Here's what I understood: **<product>**, <what it does> for <who>. I found <a logo / no logo (the video will use the name)>, the colors <#hex>, <n> screenshots, <n> product photos and <n> clips. The video would be in <language>.
> A few quick questions (answer with letters, or say "you choose"):
> 1. What's it for? **a) launch** · b) new feature · c) offer or promo · d) pricing · e) teaser
> 2. Where will it go? **a) X, LinkedIn or YouTube (16:9)** · b) Reels, TikTok or Shorts (9:16)
> 3. Price: **a) free templates only** · b) premium is fine ($<min>–$<max> per export)
> 4. Anything to highlight? Default: **<the main benefit you found>**.

Bold = the default. Ask only what the prompt didn't already answer. Then wait for the answer.

## 3. Find templates and propose 3 to 5
Search with the answers: `GET https://opusmotion.com/api/v1/templates?format=16:9&tier=free&q=launch` (`q`: one or two words; `category`: an id from the summary; drop `tier` when premium is fine). Each template has `title`, `durationSeconds`, `price`, `goodFor`, `needs` (screenshots, photos, cut-outs, clips, logo or icon), `timelapse` and `url`.
Look at the candidates' `timelapse` (one image per format: the whole video in 12 to 16 frames, each with its second and scene) to compare them. Keep only templates the repo's material can fill (`needs`: screenshots, clips, cut-outs). Then:

> 1. **<Title>**, <length> s, <free | $X per export, per format>. <Why it fits>. It would use <logo, 2 screenshots…>. See it: <url>
> 2. … (3 or 4 in all; up to 5 when they asked you to research)
> Which one? Or I can look for others.

The link is always the template's `url` (its page, `/c/<category>/<slug>`, with the example video), never an image or an MP4 file. Wait for the choice.

## 4. Read the chosen template's fields
`GET https://opusmotion.com/api/v1/templates/{id}` → `template.fields`, `template.scenes` (a ~960 px screenshot of each scene per format).
- Each field says its `scene`: open that screenshot to see where it shows and how much room it has.
- **Text:** `minLength` and `maxLength` in characters. `example` is the demo's line: a guide to tone and length, never copy it.
- **brandOwned** (name, logo, icon): send them as `brand` or as values.
- **Image:** `use`, `kind`, `aspect`, `framing`, `recommendedPixels`, `exampleImage` (look at it first). A `cutout` takes only a real cut-out (transparent PNG or SVG), never a photo. None? Leave it out.
- **Video:** `kind` (`footage` of a shot, or `motion` of an image), `aspect`, `seconds.clip` (how much of the clip plays), `exampleVideo`. It moves the image field `stillField`: send a frame of the same clip there.
- **Optional** fields can be left out.

## 5. Write the values and create the draft
- In the product's language, within every limit: rewrite what doesn't fit, never cut it. Put the highlight where it fits.
- Images are base64 data URLs: PNG, JPEG, WebP or SVG, up to 4 MB each (logo 1 MB), 12 MB a request: more, and the rest go with `PATCH`. No good image? Leave the field out. Never the same image in two fields, nor another company's ads, logos or photos. No logo file? Leave `brand.logo` out: the template writes the name.

`POST https://opusmotion.com/api/v1/drafts` with JSON; the keys of `values` are the field ids:

```json
{ "template": "product-launch", "format": "16:9",
  "brand": { "name": "Acme", "colors": ["#0A84FF", "#FF9F0A"], "logo": "data:image/svg+xml;base64,..." },
  "values": { "request": "Turn this sketch into a product page", "beforeImage": "data:image/png;base64,..." } }
```

Build it with a script in a temporary folder (never in the person's project), so the base64 never goes through a shell argument, then `curl -s -X POST https://opusmotion.com/api/v1/drafts -H 'content-type: application/json' --data-binary @/tmp/draft.json`.

- **201:** `studioUrl`, `editToken` (keep it), `missing`, `price`, `tellThePerson`.
- **422:** nothing saved; `problems` has each field's `code` (`too_long`, `demo_value`, `not_a_cutout`, `duplicate_image`…) and limit. Fix and send again; don't bother the person with it.
- **429:** see the rule above. New drafts: 50 a day per network; updates don't count.

**Clips** go one per request once the draft exists: `curl -T clip.mp4 -H 'content-type: video/mp4' -H 'authorization: Bearer <editToken>' https://opusmotion.com/api/v1/drafts/{draftId}/media/{field}` (MP4 or MOV, up to 40 MB; the same link). No real clip? Leave the field: a placeholder plays, and the person can upload one or use "Animate an image" in the studio. Say so.

## 6. Hand it over, and offer more
Give the `studioUrl` and say plainly: it opens Opus Motion with the video playing live, nothing rendered yet, and they can change anything there; what you put in and what you left empty (`missing`); to export the MP4 they need an Opus Motion account, and the price (`price.tellThePerson`); the link works for 30 days.

Then offer changes. `PATCH https://opusmotion.com/api/v1/drafts/{draftId}` with `Authorization: Bearer <editToken>` and only what changes (`null` takes a field back to the template's) keeps the same link; the person opens it again. Another template is a new draft. Never say the video is done or exported, nor promise a price other than `price`.

The line that brings you here: "Look at this project and research which Opus Motion video templates would sell it best. Compare them and propose your top picks with links. Follow https://opusmotion.com/agents.md"