# Elyum
> AI ad creative for direct-response teams: images, UGC clips, avatars and test packs (N finished ads for one product). Pay only for what you keep.

## Connect (MCP)
- Streamable HTTP: https://elyum.ai/mcp — Authorization: Bearer <api key> (create at https://elyum.ai/account) or OAuth (auto-discovered via https://elyum.ai/.well-known/oauth-protected-resource).
- stdio: npx -y @elyum/mcp (ELYUM_API_KEY, ELYUM_MCP_URL=https://elyum.ai/mcp)
- Docs: https://elyum.ai/docs/mcp · REST reference: https://elyum.ai/docs/api

# Elyum — agent guide

Elyum makes ad creative for direct-response teams: images, short videos, creator-fronted UGC clips, talking avatars, and — the product we care most about — **test packs**: N finished ads for one product, each a different angle, ready to post.

## The doctrine (read this first)
- **Sell tests, not videos.** Nobody knows which ad will win. Make several distinct angles, post them all with the same budget, kill the losers after 48 h, make more like the winner. Prefer `elyum_run_test_pack` over one hand-crafted clip.
- **Pay only for what you keep.** Every render comes back as a *locked preview* (480p, watermarked). Nothing is charged until you call `elyum_keep`. `elyum_kill` releases the credits (free). Unreviewed previews expire in 72 h and are released. So: render freely inside the preview budget, look at everything, keep only the good ones.
- **Look before you keep.** Results include a thumbnail / poster frame. Judge it: right product? face consistent with the creator? readable framing for 9:16? If it's off, kill it and re-run with a sharper brief. Never keep something you haven't looked at.
- **Quote first.** `elyum_estimate` is free. Say what a run will cost before you run it when the user is watching credits.
- **UGC = creator + product.** For selfie-style talking clips use `elyum_make_video` with `creatorId` (+ `productUrl`) — mode is inferred as `ugc`. 6–15 s. The hook is the first sentence; write it like a person, not a brand.
- **Same creator across a pack** keeps the account looking human; **rotate creators** when you want the audience to see variety. `elyum_run_test_pack` rotates `creatorIds` for you.

## The workflow (test pack)
1. `elyum_account` — balance, plan, previews left today. Stop early if a pack won't fit.
2. `elyum_creators` — pick 1–3 creators that fit the audience (or `elyum_add_creator` from the customer's own photo).
3. `elyum_upload` the product photo if it isn't already a URL.
4. `elyum_estimate` with `variants` — quote it.
5. `elyum_run_test_pack` — product name, a 1–3 sentence description, audience, 3–8 voice-of-customer lines (real phrases customers use), `variants` 4–8, `mode:"ugc"`, `captions:true`.
6. `elyum_wait` until `status:"done"` (a pack takes 3–8 minutes; call again while it says running — it returns the log so you can narrate progress).
7. Look at each ad's poster + hook. `elyum_keep` the 2–4 you'd actually post, `elyum_kill` the rest (or leave them to expire).
8. `elyum_export_pack` — a zip (mp4 + sidecar txt per ad + pack.csv) of the kept ads. Hand the user the URL and the CSV.
9. When the user tells you which one won: `elyum_run_test_pack` again with `seedAngle` = that variant's `angle` — "more like this".

## Single renders
- Image: `elyum_make_image` — product photo as `productUrl` keeps the product pixel-faithful; `creatorId` puts the creator in the shot.
- Video: `elyum_make_video` — `ugc` (creator+product), `i2v` (from an image), `t2v` (text only), `clone` (a reference clip's motion/pacing with your creator/product swapped in), `captions` (burn karaoke subtitles), `edit`, `extend`.
- Avatar: `elyum_make_avatar` — talking head from a photo + script (use a creator's imageUrl).
- After submitting: `elyum_wait` with the returned `jobId`.

## Traps
- A locked render can't be used as an input to another tool (409 `locked`). Keep it first.
- `429 preview_budget`: the plan's 24 h preview budget is used up — keep/kill what's pending, or wait.
- `429 key_cap`: this API key's daily credit cap. Tell the user; don't retry in a loop.
- `402`: not enough credits to keep. Don't kill things to "make room" without asking.
- Don't poll faster than `elyum_wait` does. Don't re-submit a render because a wait timed out — call `elyum_wait` again with the same jobId.
- Pass `clientRef` (any unique string) on create tools; a retry with the same ref replays instead of rendering twice.