1.Overview
What it is
The server lets an agent do what you do in the studio: read your account, price a render, make images, videos, audio and avatars, look at what came back and keep or kill it. It is metered like the studio: a render holds its price from your credits as a locked preview and nothing is charged until a take is kept. Everything an agent makes lands in your Library.
Endpoint
Streamable HTTP at https://elyum.ai/mcp. With OAuth there is no key to paste: the client opens our consent page, you choose what it may do, and it is connected. A client without OAuth sends an MCP token from Connections as Authorization: Bearer ek_mcp_…. For a client that only runs local servers there is a stdio shim on npm: npx -y @elyum/mcp.
The API's MCP server
This is the studio's MCP server: previews you keep or kill, paid from your studio credits. Building on the API instead? It has its own MCP server, connected with OAuth or an API key: final files at API prices, paid from your API balance. See API MCP server.
2.Connect a client
With OAuth there is no key to paste: the client opens our consent page, you choose what it may do, and it is connected. A client without it takes an MCP token from Connections in place of ek_mcp_….
Claude Code
One command in your terminal. Or skip the header and let Claude Code run the OAuth flow (it opens the consent page here).
claude mcp add --transport http elyum https://elyum.ai/mcp --header "Authorization: Bearer ek_mcp_…"
# or, OAuth (no key to paste):
claude mcp add --transport http elyum https://elyum.ai/mcpClaude.ai and Desktop
Settings → Connectors → Add custom connector. Paste the URL; Claude signs in through our consent page (OAuth) — pick scopes and a daily cap there.
Name: Elyum
URL: https://elyum.ai/mcp
(then in a chat: "Make a 5-second Seedance 2.5 clip at 720p and show me the preview")Cursor
Click the button (deep link) or add to ~/.cursor/mcp.json.
{
"mcpServers": {
"elyum": { "url": "https://elyum.ai/mcp", "headers": { "Authorization": "Bearer ek_mcp_…" } }
}
}Codex
Codex CLI / IDE — either the hosted URL or the npm shim over stdio (same tools).
# ~/.codex/config.toml
[mcp_servers.elyum]
url = "https://elyum.ai/mcp"
bearer_token_env_var = "ELYUM_API_KEY" # export ELYUM_API_KEY=ek_mcp_…
# or stdio via npm:
[mcp_servers.elyum]
command = "npx"
args = ["-y", "@elyum/mcp"]
env = { ELYUM_API_KEY = "ek_mcp_…", ELYUM_MCP_URL = "https://elyum.ai/mcp" }Other clients
Windsurf, VS Code, Cline, Zed… any client that takes an mcpServers/servers block. Streamable HTTP with a bearer header, or stdio via npx @elyum/mcp.
{
"mcpServers": {
"elyum": {
"type": "http",
"url": "https://elyum.ai/mcp",
"headers": { "Authorization": "Bearer ek_mcp_…" }
}
}
}
// stdio alternative:
{ "mcpServers": { "elyum": { "command": "npx", "args": ["-y", "@elyum/mcp"], "env": { "ELYUM_API_KEY": "ek_mcp_…", "ELYUM_MCP_URL": "https://elyum.ai/mcp" } } } }Signed in, Connect in the studio shows the same setup for your account.
3.Sign-in, scopes and the daily cap
OAuth
Claude Code, Claude.ai, Claude Desktop and most current clients connect with OAuth: on the consent page you pick the scopes, an optional daily cap and, inside a business, which client the connection works for. Its access token is an MCP token like any other, listed under Connections; revoking a token or a connection there signs the agent out at once.
MCP tokens
Authorization: Bearer ek_mcp_…An MCP token (ek_mcp_…) opens this server only; an API key is refused here. Make one on Connections, where you can also revoke it.
Scopes
| Scope | Lets the agent |
|---|---|
read | Read the account, models, estimates, job status and the Library. |
generate | Start renders. A render holds its price in credits and charges nothing yet. |
spend | Keep renders: the only action that charges. |
Daily cap
A daily cap limits what a token or connection may hold or spend in a rolling 24 hours. A runaway loop stops at the cap (429 key_cap), not at an empty balance.
4.How a render works
The workflow
- 1
elyum_accountThe credits, the plan, kills left, and the agent guide. Agents call it first. - 2
elyum_estimateFree; what a render will hold, before it runs. - 3
elyum_make_image,elyum_make_video,elyum_make_audio,elyum_make_avatarEach returns ajobIdat once. - 4
elyum_waitBlocks up to 55 seconds; call it again with the same jobId until the result is there, with a thumbnail to judge. - 5
elyum_keeporelyum_killKeep what you would use (it is charged and its original unlocks), kill what you would not.
Previews, keep and kill
Image, video and avatar renders come back as locked previews (480p, watermarked) with their price held from your credits. elyum_keep charges that price and unlocks the full-quality original, which can then be downloaded or used as an input. elyum_kill releases what was held; kills are an allowance per billing period, and a preview left undecided costs nothing. Audio has no preview: it is charged when it renders. Everything lands in your Library.
Plan-included models
A model your plan includes for 0 credits (unlimited images on Pro and Ultra, free upscaling) answers 403 browser_only over MCP, with nothing held; pass creditMode: true to render it at its normal price, after asking the user.
Guided prompts
Guided flows the client can offer as slash commands or prompts:
| Prompt | What it does | Arguments |
|---|---|---|
cinematic-shot | A cinematic sequence | brief, shots, aspect |
mini-drama | A mini drama with a recurring cast | premise, characters, scenes |
ugc-ad | One UGC ad | product, hook, creator |
clone-winner | Clone a winning ad | videoUrl, product, creator |
5.Tools
Every tool the server registers. Kind is the scope it needs: read, write (free changes), generate (starts a render) or spend (charges).
Account and models
Read the account, pick a model and price a render before it runs.
elyum_account
readAccountThe studio balance, the plan, kills left this billing period and the agent guide. Call it first. Inside a business it adds the workspace, your role, the client this connection works for and the monthly budgets.
No arguments.elyum_models
readModelsEvery model family: its tasks, its price in credits, its length range and whether free credits can run it (plansOnly). Pass a family id as model on a render (the task picks its route), or leave model out for the default.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
model | string | No | — | A family id or model id from the list: answers that model's full details (each task's durations, aspect ratios, resolutions, inputs, voices, Kling controls). |
elyum_estimate
readEstimateFree. What a render will hold from the studio balance, at studio prices, quoted on the model the render would run. You pay per kept output, never more than this; audio is charged on render.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
kind | "image" | "video" | "avatar" | "audio" | Yes | — | What to price. |
mode | string | No | — | video: any elyum_make_video mode (ugc when left out); audio: tts (default), music or sfx. |
model | string | No | — | Price this model or family instead of the default; extend: the model that made the clip. |
images | integer 0–30 | No | — | image: how many reference images. Any makes it an edit, quoted on the edit model. |
resolution | string | No | — | image: 1K / 2K / 4K; video: 480p / 720p / 1080p, as you will pass it to the render. |
duration | number | No | default 8 | Video seconds; for clone, edit, motion and captions, the source clip's length; audio: music 5–300, sfx 0.5–22. |
characters | integer | No | — | audio tts: the script's length in characters (speech is priced by it). |
lite | boolean | No | — | clone: quote Elyum Recast Lite (clips of 4–15 s). |
prompt | string | No | — | video: the prompt you will send. The answer counts it as the model does (characters, @Image tags in the model's own form) against the model's limit: prompt.chars, prompt.max, prompt.fits. The words Elyum adds around a prompt never count. |
elyum_referral
readReferral linkThe user's Elyum Earn referral link, what it pays, and their affiliate or partner status.
No arguments.Media and characters
Bring files in and keep the faces and subjects a film or an ad needs.
elyum_upload
writeUpload mediaBrings a product photo, a reference clip or an audio file into Elyum (PNG, JPG, WebP; MP4, MOV, WebM up to 60 MB; MP3, WAV) from a public URL or base64 bytes. Returns a /media URL for productUrl, imageUrl, videoUrl or audioUrl. Free.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
url | string (URL) | No | — | A public http(s) URL to fetch. Give url or base64. |
base64 | string | No | — | The file's bytes, base64 (a data: prefix is fine). |
mimeType | string | No | — | Required with base64, e.g. image/png. |
filename | string | No | — | The file's name; its extension sets the type when nothing else does. |
elyum_creators
readList creatorsCreators (consistent faces) you can put in front of the camera: the house creators everyone shares, plus the workspace's own. Pass an id as creatorId to make_image or make_video, or in elyum_make_cinema's cast.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
kind | "character" | "location" | "prop" | No | default character | location or prop lists Cinema Studio's saved places and objects instead. |
elyum_add_creator
writeAdd a creatorSaves a face as a reusable creator from one clear, front-facing photo (the customer's founder, an employee, a model they hold the rights to). Free.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
name | string 1–60 | Yes | — | The creator's name. |
image | string | Yes | — | An http(s) URL of the photo, one of your /media URLs (a kept render) or a data URI. |
traits | string ≤ 200 | No | — | A short description used in prompts, e.g. "30s, warm, wears glasses". |
kind | "character" | "location" | "prop" | No | default character | location or prop saves a place or an object for Cinema Studio's cast (a kept location plate, a product). |
elyum_kling_subjects
readList Kling subjectsThe workspace's reusable Kling subjects (ks_… ids). Put them in kling.subjects and cite @Subject1, @Subject2 in that order.
No arguments.elyum_kling_subject_save
writeSave a Kling subjectCreates or updates a Kling subject from 2–4 uploaded photos or one 3–60 s clip, with an optional MP3 voice. Upload the media first. The first image is the subject's permanent cover.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
id | string | No | — | An existing subject to edit; leave it out to create one. |
requestId | string 16–80 | Yes | — | A stable id for this save. Never repeat an uncertain attempt under a new one. |
name | string 1–80 | Yes | — | The subject's name. |
description | string ≤ 1000 | No | — | What the subject is. |
images | string[] ≤ 4 | No | — | Photo URLs from elyum_upload. |
video | string | null | No | — | One clip URL instead of photos. |
voice | string | null | No | — | An MP3 voice URL; null removes the voice. |
tags | string[] 1–7 | No | — | Characters, Animals, Items, Costumes, Scenes, Effects, Others. |
elyum_kling_subject_delete
writeDelete a Kling subjectDeletes one of the workspace's Kling subjects. Files made with it stay.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
id | string | Yes | — | The subject's ks_… id. |
Make
Start a render. Each returns a jobId at once; the result comes from elyum_wait.
elyum_make_image
generateMake an imageOne still: a key frame, a character sheet, a poster, a product shot, a thumbnail. References make it an edit that keeps the subject faithful; without them it is text to image. Returns a jobId for elyum_wait.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
prompt | string ≥ 3 | Yes | — | The scene: subject, framing, lens, light, palette, mood. |
creatorId | string | No | — | Put this creator in the shot (elyum_creators). |
productUrl | string | No | — | A product photo, kept faithful in the output. |
imageUrls | string[] ≤ 10 | No | — | Reference images: a character sheet, a style frame, a set. |
aspectRatio | string | No | default per model | 9:16, 1:1, 4:5, 16:9… |
resolution | string | No | default per model | 1K, 2K or 4K (a GIF or an SVG has one size per ratio: leave it out). |
format | png | gif | svg | No | default png | GPT Image 2.6: gif = an animated loop (from a prompt or animating reference images), svg = vector markup (from a prompt only). Costs what the model's 1K still does. |
frames | integer 2–16 | No | default 9 | format gif: frames in the loop. |
frameMs | integer 20–2000 | No | default 200 | format gif: milliseconds each frame shows (100 fast, 400 slow). |
model | string | No | — | A specific model. Leave it out and the role's default is used (elyum_models lists them). |
kling | object | No | — | Kling controls (below, "Kling options"); only for Kling models. |
creditMode | boolean | No | default false | Render a model the user's plan includes free at its normal studio price. Plan-included renders exist only in the studio in a browser: without this they answer browser_only and nothing is charged. Ask the user first. |
clientRef | string | No | — | Any unique string up to 120 characters. A retry with the same ref returns the first answer instead of rendering twice. |
elyum_make_video
generateMake a videoOne clip. t2v: text only. i2v: animate a key frame. ref: reference stills, clips or audio become a new shot that keeps the look (@Image1, @Video1, @Audio1 in the prompt). ugc: a creator and a product, a selfie-style talking clip. clone: Elyum Clone, a 4–30 s clip made again with your people, products or images. captions, edit, extend. Returns a jobId for elyum_wait.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
prompt | string | No | — | The shot: who, where, the action, the camera move, any spoken line in quotes. Optional for clone; not needed for captions. |
mode | "ugc" | "i2v" | "t2v" | "ref" | "clone" | "captions" | "edit" | "extend" | "motion" | No | — | Worked out when left out: creatorId or productUrl → ugc, imageUrl → i2v, else t2v. Say ref for the same character across shots. |
creatorId | string | No | — | A saved creator. |
productUrl | string | No | — | A product photo. |
imageUrl | string | No | — | i2v: the first frame; ref: the first reference (@Image1); ugc: an opening frame. |
imageUrls | string[] ≤ 28 | No | — | ref: more references (@Image2…); clone: more people, outfits, products or a place. |
endImageUrl | string | No | — | A last frame, on models that take one. |
videoUrl | string | No | — | clone, captions, edit, extend: the source clip; ref: a reference clip (@Video1). |
videoUrls | string[] ≤ 3 | No | — | ref, edit: more reference clips (@Video2…). |
audioUrl | string | No | — | ref, edit: an audio reference (@Audio1): a song, a voice line, a beat to follow. |
audioUrls | string[] ≤ 10 | No | — | More audio references (@Audio2…). |
duration | integer 2–30 | No | default 8 | Seconds. Seedance 2.5 edit and clone follow the source clip's length. |
aspectRatio | string | No | default per model | 9:16, 16:9, 1:1 or auto; Wan 3.0 and Wan 3.0 Prime also 21:9 (text and reference modes). |
resolution | string | No | default per model | 720p or 1080p. |
audio | boolean | No | default true | Native sound and dialogue. |
seed | integer 0–2147483647 | No | — | Wan 3.0 and Wan 3.0 Prime: a seed, to vary a take on purpose. The same seed does not promise the same take. |
promptExpansion | boolean | No | default — | Wan 3.0 and Wan 3.0 Prime: false sends your prompt exactly as written, true keeps the model's own rewriting on. Left out, Wan 3.0 can render either way (state it to be sure); Prime rewrites. |
autoLength | boolean | No | — | Wan 3.0 and Wan 3.0 Prime: true lets the model pick the length (leave duration out). The longest take is held; only the seconds it makes are charged. |
draft | boolean | No | default false | Seedance 2.5 (t2v, i2v, ref): true renders a 480p draft of the shot, to check the take before the full-quality render. Charged when it lands: it is not a preview and cannot be killed. Leave resolution out. |
draftId | string | No | — | Seedance 2.5: the jobId of a finished draft, up to 7 days old. Renders the same take at 1080p, charged when it lands (it cannot be killed). Send it alone: the prompt, the references and every other setting are the draft's. |
keepAudio | boolean | No | default true | clone: keep the source clip's soundtrack. |
cloneMode | "swap" | "motion" | No | default swap | clone: swap keeps the clip and changes only what you name; motion makes a new video on the clip's movement and cuts. |
sourceModel | string | No | — | extend: the model that made the source clip. |
model | string | No | — | A specific model. Leave it out and the role's default is used (elyum_models lists them). |
kling | object | No | — | Kling controls (below, "Kling options"); only for Kling models. |
clientRef | string | No | — | Any unique string up to 120 characters. A retry with the same ref returns the first answer instead of rendering twice. |
elyum_make_audio
generateMake audioSpeech (a voice-over of your script), music (a track from a brief, 5–300 s) or a sound effect (up to 22 s). Audio is charged when it renders: it has no keep or kill. The result is an MP3.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
mode | "tts" | "music" | "sfx" | No | default tts | tts: the prompt is the script; music: the track brief; sfx: the sound. |
prompt | string 2–4000 | Yes | — | The script, or a one-line brief. |
voice | string | No | default Aria | tts: a voice the model lists in elyum_models. |
duration | number | No | — | Seconds: music 5–300 (60 when left out; the price follows it), sfx 0.5–22. |
model | string | No | — | A specific model. Leave it out and the role's default is used (elyum_models lists them). |
clientRef | string | No | — | Any unique string up to 120 characters. A retry with the same ref returns the first answer instead of rendering twice. |
elyum_cinema_looks
readCinema Studio looksFree. Cinema Studio's catalogue for elyum_make_cinema: its models, every camera setting (genre, era, camera body, lens, focal length, aperture, lighting, colour palette, speed ramp, tempo) with each option's id and what it looks like, the camera movements, the emotions, hand-placed lights, the AI Cast builder's traits and the edit changes.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
section | string | No | default all | all, models, look, palettes, moves, emotions, lights, cast_sheet or edit. |
elyum_make_cinema
generateShoot in Cinema StudioA Cinema Studio shot set up like a film camera: the scene plus a look, up to two hand-placed lights and a cast of saved characters, locations and props named in the prompt by tag, whose photos ride along so faces, places and objects hold from shot to shot. kind video: a shot from text, from a start frame, or with references and the cast; kind image: a keyframe, an AI Cast sheet or a location (make), or an edit of a picture (edit). Returns a jobId for elyum_wait; the take files under Cinema Studio in the Library.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
kind | "video" | "image" | No | default video | A shot, or a keyframe (image). |
prompt | string | No | — | The scene: who (by cast tag or @Image number), where, the action, any spoken line in quotes. Video: #move ids (#dolly-in) where each move happens. |
model | string | No | — | A Cinema Studio model (elyum_cinema_looks, section models); the first is the default. |
look | object | No | — | One option id per setting: genre, era, camera, lens, focal, aperture, lighting, palette, speed, tempo. Genre, era, aperture, lighting, palette, speed and tempo are for video. |
moves | string[] ≤ 6 | No | — | Video: camera movements added at the end of the scene, in order. |
colors | string[] 2–12 | No | — | Video: a palette of your own (#rrggbb, the main colour first) instead of look.palette. |
lights | object[] ≤ 2 | No | — | Video: hand-placed lights instead of look.lighting — color (#rrggbb), brightness 0–100, diffuse 0–100, direction (front-top-left…). |
cast | object[] ≤ 6 | No | — | Saved elements: kind (character, location, prop), id (elyum_creators), token (@Name in the prompt), and for a character an emotion and its level. |
make | "cast" | "location" | No | — | kind image: an AI Cast character sheet (16:9) or an empty location instead of a keyframe. |
sheet | object | No | — | make cast: the AI Cast builder's picks (elyum_cinema_looks, section cast_sheet). |
edit | true | { change } | No | — | kind image: change the picture in imageUrl, keeping the rest — texture, lighting or angle, or what the prompt says. |
imageUrl | string | No | — | Video: the start frame (elyum_still gives one); image with edit: the picture to change. |
endImageUrl | string | No | — | Video: the end frame (needs a start frame). |
imageUrls | string[] ≤ 16 | No | — | Reference images (@Image1…), before the cast's photos. Not with a start frame. |
videoUrls | string[] ≤ 3 | No | — | Video: reference clips (@Video1…). |
audioUrls | string[] ≤ 10 | No | — | Video: audio references (@Audio1…). |
duration | integer 2–30 | No | default 5 | Video seconds. |
aspectRatio | string | No | default 16:9 | 16:9, 9:16, 1:1…; auto keeps a start frame's shape. |
resolution | string | No | — | Video 480p / 720p / 1080p; image 1K / 2K / 4K. |
audio | boolean | No | — | Video: native sound (the model's default when left out). |
creditMode | boolean | No | — | Image: pay the normal price for a model the plan includes free (otherwise browser_only). Ask the user first. |
clientRef | string | No | — | Any unique string up to 120 characters. A retry with the same ref returns the first answer instead of rendering twice. |
elyum_make_avatar
generateMake a talking avatarA talking head from one photo and a script. Use a creator's photo for a consistent face. Returns a jobId for elyum_wait.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
photoUrl | string | Yes | — | A front-facing photo (a creator's imageUrl works). |
script | string 2–1200 | Yes | — | Exactly what is said, about 2.5 words a second. |
voice | string | No | — | Text-to-speech avatar models only: the voice. |
aspectRatio | string | No | — | 9:16, 16:9, 1:1… |
model | string | No | — | A specific model. Leave it out and the role's default is used (elyum_models lists them). |
clientRef | string | No | — | Any unique string up to 120 characters. A retry with the same ref returns the first answer instead of rendering twice. |
Results
Wait for a render, look at it, find it again.
elyum_wait
readWait for a resultWaits up to timeoutSeconds for a render and answers its status, percent done and time left (percent is marked estimated when it comes from how long renders like it take), or the result with a thumbnail per output to judge before keeping (a clip: four frames across it). A short wait (5–15 s, or 0) keeps the chat free; call again with the same jobId, never submit again. A client that sends a progress token gets progress notifications while it waits.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
jobId | string | Yes | — | The jobId a make tool returned (g_…). |
timeoutSeconds | integer 0–55 | No | default 50 | How long to wait; 0 answers at once. |
thumbnails | boolean | No | default true | Return thumbnails with the result. |
elyum_job_status
readJob statusOne instant check of a render: status, percent done and time left, or the result.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
jobId | string | Yes | — | The jobId a make tool returned (g_…). |
thumbnails | boolean | No | default true | Return thumbnails with the result. |
elyum_library
readLibraryTakes and uploads in the workspace, newest first, made in the studio or by an agent: link, locked or kept, the price to keep, prompt, model and size, with a thumbnail of the first ones. Cinema Studio takes carry the look, lights and cast they were shot with.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
limit | integer | No | default 20 | How many, at most 100 a page. |
kind | "image" | "video" | "avatar" | No | — | Only this kind. |
studio | string | No | — | Only one studio's: image, video, cinema, recast, marketing, avatar, upscale, batch or upload (the user's own files). |
genId | string | No | — | One take in full: the whole prompt, the request as sent and the files it was made from. |
lockedOnly | boolean | No | — | Only previews not decided yet. |
before | ISO time | No | — | Items made before it: the at of the last item, for the next page. |
thumbnails | integer 0–12 | No | default 6 | How many of the first items carry a thumbnail. |
elyum_still
writeStill from a takeFree. Cuts a frame out of a kept clip into an image any render takes as an input: the last frame as the next shot's start frame, any moment as a reference still. The still is saved to the Library as an upload. A locked preview is refused (keep it first); an image take answers with its own link.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
genId | string | Yes | — | The take (g_…). |
index | integer ≥ 0 | No | default 0 | Which output. |
at | number | "first" | "last" | No | default last | Seconds into the clip, or its first or last frame. |
Keep and kill
The decision on a preview: keep charges, kill releases.
elyum_keep
spendKeepThe only tool that charges. Unlocks a render you have looked at and would use, at its quoted studio price: the full-quality original becomes downloadable and usable as an input. Confirm with the user unless they already said what to keep.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
genId | string | Yes | — | The genId from elyum_wait. |
index | integer ≥ 0 | No | default 0 | Which output of that render. |
elyum_kill
writeKillReleases a preview you don't want: what it held goes back to the balance and the preview stays as a record. Kills are an allowance per billing period; past it the answer is 409 kill_allowance. Leaving a preview undecided costs nothing.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
genId | string | Yes | — | The render's genId. |
index | integer ≥ 0 | No | default 0 | Which output. |
reason | string | No | — | wrong_motion, identity_drift, anatomy_physics, text_garbled, off_prompt, off_style, artifacts or good_dont_need. |
Business tools
Only on a connection inside a business.
elyum_clients
readbusinessClientsThe business's active clients with their ids and the monthly budget left on each, and which client this connection works for. Listed only on a business connection.
No arguments.elyum_jobs
readbusinessJobsThe business's live jobs this connection reaches: id, code, name, client, the budget left and whether a render can be charged to it from here. Listed only in a business with jobs, where every make_* tool also takes `job` (an id, code or exact name): its budget pays and the take is filed in its project.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
wrapped | boolean | No | default false | List wrapped jobs too (they take no renders). |
Kling options
The kling object on elyum_make_image and elyum_make_video, for Kling models only. elyum_models lists what each Kling model takes.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
outputs | integer 1–9 | No | — | How many outputs in one request. |
storyMode | boolean | No | — | A set of story frames; up to 9 images are held and unused ones released. |
multiShot | boolean | No | — | Several shots in one clip. |
asmr | boolean | No | — | ASMR sound. |
soundPrompt | string ≤ 2500 | No | — | What the sound should be. |
musicPrompt | string ≤ 2500 | No | — | What the music should be. |
keepSound | boolean | No | — | Keep the source clip's sound. |
orientation | "image" | "video" | No | — | Motion control: follow the image's or the clip's orientation. |
imageRoles | string[] ≤ 6 | No | — | subject, scene or style, per reference image. |
subjects | string[] ≤ 10 | No | — | Kling subject ids (ks_…); @Subject1 is the first. |
6.Resources
| Resource | What it holds |
|---|---|
elyum://guide | The agent guide: formats, the workflow and the traps. Read it before the first render. |
elyum://account | Balance, plan, kills left. |
elyum://creators | House and workspace creators. |
elyum://models | Which model serves each role, and what it supports. |
elyum://pricing | The plans and their prices. |
elyum://jobs/{id} | A render's status, like elyum_job_status. |
7.Errors and limits
Error codes
A refused call comes back as a tool error with the HTTP status, a code, the message and what the agent should do next.
| Code | Meaning |
|---|---|
402 | Not enough credits. The agent tells the user; it never kills other previews to make room. |
key_cap | The token's daily cap is reached. Stop and tell the user. |
scope | The token lacks the scope for this tool. Create one with it on Connections. |
locked | A preview was used as an input. Keep it first. |
browser_only | A plan-included model over MCP. Nothing charged; ask before retrying with creditMode. |
plan_required | Free credits cannot run this model (Seedance and Kling video, Upscale). Pick another one, or a plan unlocks it. |
kill_allowance | No kills left this billing period. |
concurrency | Too many renders in flight. Wait for one to finish (elyum_wait), then retry. |
maintenance | No render starts until it is over. Nothing was charged. |
renewal_failed | The plan's payment failed; renders are paused until it is paid. |
Safe retries
clientRef on every create tool makes a retry safe: the same ref returns the first answer instead of rendering twice.
8.Businesses
Inside a business, every MCP token and OAuth connection works for one client (everything lands there), the business level (the shared business library), or any client, chosen when the token is created on Connections while working in the business, or under “Connect to” on the consent screen.
- On an any-client connection every tool that touches work takes a required
clientargument (a client id or its exact name).elyum_clientslists the clients and the budget left on each. - The agent sees its client's work and the business library, never another client's.
elyum_accountgains anagencyblock: workspace, role, client and the monthly budgets. - Budgets are hard limits:
429 member_budgetand429 client_budgethold nothing and tell the agent to stop and ask. - In a business with jobs, every
make_*tool takes an optionaljob(an id, code or exact name;elyum_jobslists them): the job's budget pays (429 project_budgetwhen it is used up), and pictures and clips are filed in the job's project, as the studio's job picker does.
Auto-connect from Claude
On Claude Team and Enterprise, a business can connect Elyum for every member at once: members get Elyum in Claude when they sign in to Claude, with no Elyum sign-in and no consent screen. Claude vouches for each member by email (enterprise-managed authorization), and Elyum connects the member of the business with that verified email. Nobody else is connected, and no account is created.
- In Claude, an Owner opens Organization settings → Connectors, adds Elyum (
https://elyum.ai/mcp), opens Managed authorization and chooses Claude-issued. Copy the issuer URL Claude shows (https://identity.anthropic.com/issuers/…). - In Elyum, the business's Owner opens MCP → Auto-connect while working in the business, pastes the issuer URL, picks what a member's Claude may do (read, generate, spend) and a daily credit cap per member, and saves.
- Paste the Tenant ID shown on the same page into Claude's Tenant ID field. It ties the issuer to this business alone.
- Each member needs an Elyum account in the business with a verified email that matches their Claude email.
Every connection is listed under Connections and lasts an hour; Claude renews it on its own. Turning auto-connect off, or removing a member from the business, stops it within the hour. Budgets, the daily cap and scopes apply as for any connection. Only Claude-issued identities are accepted (an identity provider such as Okta is not supported yet), and changing or removing the setting signs every auto-connected member out at once.
9.The playbook agents get
Served as elyum://guide, returned by elyum_account, and at /llms-full.txt. Drop it into a Cursor rules file, AGENTS.md or a Claude skill if your client doesn't read MCP resources.
# 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.