# Elyum — full agent guide > Every top AI video, image, audio and 3D model in one studio. Every render is a free preview (Keep/Kill): nothing is charged until you keep a take, and killed takes are refunded within the plan's kill allowance. The short summary for answer engines is https://elyum.ai/llms.txt. ## Connect (MCP) - [MCP endpoint](https://elyum.ai/mcp): Streamable HTTP — Authorization: Bearer or OAuth (auto-discovered via [protected-resource metadata](https://elyum.ai/.well-known/oauth-protected-resource)). - [Create an MCP token](https://elyum.ai/studio/mcp/connections): MCP tokens (ek_mcp_…) work on /mcp; REST API keys (ek_live_…, [https://elyum.ai/console/keys](https://elyum.ai/console/keys)) do not. - stdio alternative: npx -y @elyum/mcp (env: ELYUM_API_KEY = your MCP token, ELYUM_MCP_URL=https://elyum.ai/mcp) ## Docs - [MCP guide](https://elyum.ai/docs/mcp): how to connect an agent and the full tool reference. - [API MCP server](https://elyum.ai/open/docs/mcp): the API's own MCP server (https://api.elyum.ai/v1/mcp), connected with OAuth or an API key: final renders at API prices, paid from the API balance. Not this guide's server. - [REST API reference](https://elyum.ai/docs/api): the same capabilities over plain HTTP. - [API v1](https://elyum.ai/open): one endpoint for every model, final renders charged on delivery; every model's price and a Playground. - [Pricing and plans](https://elyum.ai/pricing): one credit balance across every model — video by the second and resolution, images by the render; previews are free. ## Machine-readable - [auth.md](https://elyum.ai/auth.md): how an agent gets credentials (API key, MCP token or OAuth 2.1). - [API catalog](https://elyum.ai/.well-known/api-catalog): RFC 9727 linkset of every public service. - [MCP server card](https://elyum.ai/.well-known/mcp/server-card.json): live tool list, transport and authentication. # Elyum — agent guide Elyum is a full AI creative studio — every top video, image, audio and avatar model in one place, cheaper than anywhere else in the market. People make cinematic shots and short films, mini dramas with a recurring cast, music videos, UGC and creator content, product and brand work, explainers, talking avatars, music, voice-overs and sound. The disruptive part is **Keep/Kill**: every render comes back as a locked preview, nothing is charged until you keep it, and a render you don't like is killed for a full credit refund. Misses cost nothing — in practice that drives cost per usable output down 70%+ versus the next cheapest alternative. On top of raw model access, the same tools produce finished pieces when asked: creator-fronted UGC clips and talking avatars. ## The doctrine (read this first) - **Format first.** Find out what is being made before you pick a tool — a film scene, a mini drama, a music video, a UGC clip, a product shot, an explainer. Never assume an ad; a photo or a link is a reference until the user says it is a product. - **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). Undecided previews never expire: they stay open, with their credits on hold, until kept or killed. Previews are never limited; kills are an allowance per billing period: a kill uses 1, except Seedance 2.5 and Seedance 2.0, not its Fast or Mini routes (1 / 2 / 4 at 480p / 720p / 1080p; Seedance 2.0 at 4K uses 8) Wan 3.0 (1 / 1 / 2) and Kling 4.0 (1 / 2 at 720p / 1080p). So: render freely, look at everything, keep only the good ones, and don't kill what you can simply leave. - **Render freely; the misses are free.** Nobody gets the perfect take first try. Run several attempts (different prompts, different models), judge them all, keep the one that's right. On Elyum extra attempts cost nothing until you keep, so volume of tries is the strategy — never nurse one prompt. - **Outcomes, not knobs.** Say *what* you want — Elyum routes to the right model, serializes the params, and falls back when a model fails. Pass a specific `model` slug only when the user asks for one; otherwise omit it and let the role default work. - **Consistency is a reference.** A character, a set or a product stays the same across shots when the same reference stills ride along on every render: `elyum_make_video` mode `ref` with `imageUrl` + `imageUrls` (they are @Image1, @Image2… in the prompt), `productUrl` for a product, `creatorId` for a saved face. Repeat the wardrobe and lighting words too. - **Look before you keep.** Results include a thumbnail: the image, or four frames across a clip (left to right, top to bottom). Judge it: right subject? face consistent with the reference? readable framing for the aspect? continuity with the previous shot? If it's off, kill it and re-run with a sharper brief. Never keep something you haven't looked at. - **Continuity from earlier takes.** `elyum_library` shows takes with thumbnails, one studio at a time (`studio: "cinema"` lists Cinema Studio's, each with the look and cast it was shot with). `elyum_still` cuts a frame out of a kept clip: its last frame is the next shot's start frame. - **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` when there is a product) — 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 several takes** keeps the account looking human; **rotate creators** when you want the audience to see variety — pass a different `creatorId` on each take. ## Formats (what to do for each) Elyum does not stitch clips yet: deliver the parts in order and say so. - **Cinematic shot / short film**: a shot list → one key frame per shot (`elyum_make_image`, one look sentence — lens, palette, time of day — repeated in every prompt, 16:9) → `elyum_make_video` mode `i2v` per approved frame (5–10 s, audio on, the camera move in the prompt) → music or ambience with `elyum_make_audio`. In Cinema Studio (`elyum_make_cinema`) the camera is set up, not written: genre, era, camera body, lens, focal length, aperture, lighting, palette, speed ramp, tempo and camera moves by id (`elyum_cinema_looks`), plus a cast of saved characters, locations and props (`elyum_creators` with `kind`) named in the prompt by tag. Keep the same look and cast on every shot, and start each shot on the last one's final frame (`elyum_still`). - **Mini drama**: cast stills first (`elyum_make_image`, full body, neutral background, wardrobe spelled out — or a saved creator), then one `elyum_make_video` mode `ref` per scene with the stills as `imageUrl` + `imageUrls`, the line of dialogue in quotes, 9:16, 5–10 s, audio on. Same stills, wardrobe words and lighting words in every scene; re-run a scene whose face drifted. - **Music video**: the track first (`elyum_make_audio` mode `music`, 60–120 s; the price scales with length), then a visual concept and 6–8 clips (`t2v`, or `ref` with a performer still) mapped to its sections, audio off. - **UGC / creator content**: `elyum_make_video` with `creatorId` (+ `productUrl`), hook first. Ad variants at volume: the same call several times, a different hook (and creator) on each, then keep the winners — see the workflow below. - **Product / brand**: `elyum_make_image` with `productUrl` (pixel-faithful) for studio shots, scenes, lifestyle and thumbnails; animate a still with `i2v`. - **Explainer / faceless**: script beats → stills → `i2v` on the strongest → `elyum_make_audio` mode `tts` for the voice-over. - **Talking avatar**: `elyum_make_avatar` from a photo + script. ## The workflow (single renders — the main lane) 1. `elyum_account` — balance, plan, kills left this period. 2. `elyum_estimate` — quote the render before running it. 3. Submit: - Image: `elyum_make_image` — a photo as `productUrl` keeps the subject pixel-faithful; `creatorId` puts a saved creator in the shot; `imageUrls` are style/character references. - Video: `elyum_make_video` — `t2v` (text only), `i2v` (animate a frame), `ref` (reference stills/clips → a NEW shot that keeps the look — the film and drama move), `ugc` (creator + product), `clone` (Elyum Recast — a 4–30 s clip with your creator / product / images in it; `cloneMode` `swap` keeps the clip and changes only what you name, `motion` re-renders it on the same beats; Elyum works out what each image is for; the prompt is optional; `lite: true` is Elyum Recast Lite — fewer credits (quote both with `elyum_estimate`), clips of 4–15 s, up to 10 images), `captions` (burn karaoke subtitles), `edit`, `extend`. In `ref` and `edit`, `audioUrl` / `audioUrls` are audio references (@Audio1…) — a song, a voice line or a beat the clip follows; upload mp3/wav with `elyum_upload`, and check `audioInput` with `elyum_models` {model} (Seedance 2.5 takes them). - Audio: `elyum_make_audio` — `tts` (voice-over), `music` (a track), `sfx` (one sound). Charged on render. - Avatar: `elyum_make_avatar` — talking head from a photo + script (use a creator's imageUrl). 4. `elyum_wait` with the returned `jobId` until `status:"done"`. A short `timeoutSeconds` (5–15) keeps the chat free and answers the percent done and the time left meanwhile. 5. Judge the preview. `elyum_keep` what's good (the only charge), `elyum_kill` what isn't (full refund), re-run with a sharper brief. ## The workflow (UGC ads at volume) When the user wants several finished ads for one product: 1. `elyum_creators` — pick 1–3 creators that fit the audience (or `elyum_add_creator` from the customer's own photo). 2. `elyum_upload` the product photo if it isn't already a URL. 3. Write 4–8 hooks, each from a different angle (problem and solution, social proof, demo, comparison, objection, urgency), in the customer's own words when the user has reviews or DMs to draw on. 4. `elyum_estimate` (video, mode `ugc`) — quote one take and multiply by the number of takes. 5. `elyum_make_video` once per hook with `creatorId` + `productUrl`, 9:16, 8–15 s, the prompt = the hook + a 2–3 sentence script, a different creator per take when you want variety, a `clientRef` on each. If it answers that too many renders are in flight, `elyum_wait` for one to finish, then go on. Mode `captions` burns karaoke subtitles into a kept take. 6. `elyum_wait` on each `jobId` until `status:"done"`. 7. Look at each poster. `elyum_keep` the ones you'd actually post, `elyum_kill` the rest. 8. When the user tells you which one won: render a few more takes that keep that hook's angle and change the opening line, the proof or the scene — "more like this". ## Traps - A locked render can't be used as an input to another tool (409 `locked`). Keep it first. - `409 kill_allowance`: the plan's kills for this billing period cannot cover this kill (`needed` = the kills it uses) — previews are never limited, kills are. Keep what is good and tell the user when kills reset (`resetsAt`). - `429 key_cap`: this token's daily credit cap. Tell the user; don't retry in a loop. - `402 renewal_failed`: the user's plan didn't renew because the payment failed, so every render is paused, free ones included; nothing was held. Stop and tell the user to update the payment method in the Elyum app (Account → Billing) — it resumes as soon as the payment goes through. Don't retry in a loop. - `503 maintenance` ("Supplier under maintenance"): every render is refused on every model while the studio's supplier is being serviced; nothing was held. Tell the user and try again later — don't retry in a loop. - `403 browser_only` ("Free/Unlimited generations are only available via browser."): the user's plan includes that model for 0 credits, but only in the Elyum studio in a browser; nothing was held. `elyum_estimate` says so up front (`browserOnly: true`, `credits` = the normal rate). Tell the user they can make it free in the studio, or — only with their go-ahead — repeat the call with `creditMode: true` to pay that rate here. - `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. - A prompt over the model's limit is refused (400 `prompt_too_long`), counted as the model reads it; the words Elyum adds around it never count. `elyum_estimate` with `prompt` counts it before you render. ## Working inside a business Only when `elyum_account` has an `agency` block — otherwise skip this. - **Which client.** `agency.client` says who this connection works for: one client, "business level", or "any". On an any-client connection every tool that touches work takes a required `client` (an id or exact name from `elyum_clients`). Ask the user which client when it isn't clear — never pick one yourself. - **What lands where.** Renders, uploads and characters you make land in that client (or the business library at business level). You see that client's work plus the business library; another client's work is not there for you (404 / `input_forbidden`). - **Business assets are yours to use.** Characters and uploads in the business library work in every client. - **Budgets are hard limits.** `429 member_budget` (the user's monthly limit) and `429 client_budget` (the client's) mean stop and tell the user — an Owner or Admin raises them. Never retry in a loop, never move the work to another client to get around one. `agency.budgets` shows what is left. ## Jobs Only when `elyum_account` says `agency.jobs` — otherwise skip this. - **Charge the job.** Work for a production is charged to its job: pass `job` (its id, code or exact name; `elyum_jobs` lists them) on every make_* call for it. Its budget pays, its spend counts the take, and pictures and clips are filed in the job's project. Ask the user which job when it isn't clear; never pick one yourself. A render without `job` is charged to no job. - **Only jobs that take renders here.** `elyum_jobs` says `canRender` for each: a wrapped job, a closed job the user is not on the crew of, and another client's job take none. - **A job's budget is a hard limit.** `429 project_budget` means stop and tell the user: the Owner or an Admin raises it, or anyone asks for more on the job. Never charge another job, or drop `job`, to get around it. - **Two kinds of job.** A render's `jobId` (g_…) is what `elyum_wait` polls; a production's job is a `prj_…` id or its code. Never pass one for the other.