Elyum

Elyum MCP

Let Claude, Cursor, Codex — any MCP client — create in your Elyum studio: cinematic shots, mini dramas with a recurring cast, music videos, UGC clips, product images, talking avatars, music and voice-overs. Same metering as the studio: renders come back as locked previews, and nothing is charged until a take is kept.

Endpointhttps://elyum.ai/mcpAuthOAuth, or an MCP token ek_mcp_…TransportStreamable HTTP
On this page

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

Not 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).

Terminal
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/mcp

Claude.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.

Connector
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.

~/.cursor/mcp.json
{
  "mcpServers": {
    "elyum": { "url": "https://elyum.ai/mcp", "headers": { "Authorization": "Bearer ek_mcp_…" } }
  }
}
Add to Cursor

Codex

Codex CLI / IDE — either the hosted URL or the npm shim over stdio (same tools).

~/.codex/config.toml
# ~/.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
{
  "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

Header
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

ScopeLets the agent
readRead the account, models, estimates, job status and the Library.
generateStart renders. A render holds its price in credits and charges nothing yet.
spendKeep 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. 1
    elyum_account
    The credits, the plan, kills left, and the agent guide. Agents call it first.
  2. 2
    elyum_estimate
    Free; what a render will hold, before it runs.
  3. 3
    elyum_make_image, elyum_make_video, elyum_make_audio, elyum_make_avatar
    Each returns a jobId at once.
  4. 4
    elyum_wait
    Blocks up to 55 seconds; call it again with the same jobId until the result is there, with a thumbnail to judge.
  5. 5
    elyum_keep or elyum_kill
    Keep 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

Free/Unlimited generations are only available via browser

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:

PromptWhat it doesArguments
cinematic-shotA cinematic sequencebrief, shots, aspect
mini-dramaA mini drama with a recurring castpremise, characters, scenes
ugc-adOne UGC adproduct, hook, creator
clone-winnerClone a winning advideoUrl, 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

readAccount

The 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

readModels

Every 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.

ParameterTypeRequiredDefaultDescription
modelstringNo—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

readEstimate

Free. 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.

ParameterTypeRequiredDefaultDescription
kind"image" | "video" | "avatar" | "audio"Yes—What to price.
modestringNo—video: any elyum_make_video mode (ugc when left out); audio: tts (default), music or sfx.
modelstringNo—Price this model or family instead of the default; extend: the model that made the clip.
imagesinteger 0–30No—image: how many reference images. Any makes it an edit, quoted on the edit model.
resolutionstringNo—image: 1K / 2K / 4K; video: 480p / 720p / 1080p, as you will pass it to the render.
durationnumberNodefault 8Video seconds; for clone, edit, motion and captions, the source clip's length; audio: music 5–300, sfx 0.5–22.
charactersintegerNo—audio tts: the script's length in characters (speech is priced by it).
litebooleanNo—clone: quote Elyum Recast Lite (clips of 4–15 s).
promptstringNo—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 link

The 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 media

Brings 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.

ParameterTypeRequiredDefaultDescription
urlstring (URL)No—A public http(s) URL to fetch. Give url or base64.
base64stringNo—The file's bytes, base64 (a data: prefix is fine).
mimeTypestringNo—Required with base64, e.g. image/png.
filenamestringNo—The file's name; its extension sets the type when nothing else does.

elyum_creators

readList creators

Creators (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.

ParameterTypeRequiredDefaultDescription
kind"character" | "location" | "prop"Nodefault characterlocation or prop lists Cinema Studio's saved places and objects instead.

elyum_add_creator

writeAdd a creator

Saves 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.

ParameterTypeRequiredDefaultDescription
namestring 1–60Yes—The creator's name.
imagestringYes—An http(s) URL of the photo, one of your /media URLs (a kept render) or a data URI.
traitsstring ≤ 200No—A short description used in prompts, e.g. "30s, warm, wears glasses".
kind"character" | "location" | "prop"Nodefault characterlocation or prop saves a place or an object for Cinema Studio's cast (a kept location plate, a product).

elyum_kling_subjects

readList Kling subjects

The 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 subject

Creates 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.

ParameterTypeRequiredDefaultDescription
idstringNo—An existing subject to edit; leave it out to create one.
requestIdstring 16–80Yes—A stable id for this save. Never repeat an uncertain attempt under a new one.
namestring 1–80Yes—The subject's name.
descriptionstring ≤ 1000No—What the subject is.
imagesstring[] ≤ 4No—Photo URLs from elyum_upload.
videostring | nullNo—One clip URL instead of photos.
voicestring | nullNo—An MP3 voice URL; null removes the voice.
tagsstring[] 1–7No—Characters, Animals, Items, Costumes, Scenes, Effects, Others.

elyum_kling_subject_delete

writeDelete a Kling subject

Deletes one of the workspace's Kling subjects. Files made with it stay.

ParameterTypeRequiredDefaultDescription
idstringYes—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 image

One 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.

ParameterTypeRequiredDefaultDescription
promptstring ≥ 3Yes—The scene: subject, framing, lens, light, palette, mood.
creatorIdstringNo—Put this creator in the shot (elyum_creators).
productUrlstringNo—A product photo, kept faithful in the output.
imageUrlsstring[] ≤ 10No—Reference images: a character sheet, a style frame, a set.
aspectRatiostringNodefault per model9:16, 1:1, 4:5, 16:9…
resolutionstringNodefault per model1K, 2K or 4K (a GIF or an SVG has one size per ratio: leave it out).
formatpng | gif | svgNodefault pngGPT 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.
framesinteger 2–16Nodefault 9format gif: frames in the loop.
frameMsinteger 20–2000Nodefault 200format gif: milliseconds each frame shows (100 fast, 400 slow).
modelstringNo—A specific model. Leave it out and the role's default is used (elyum_models lists them).
klingobjectNo—Kling controls (below, "Kling options"); only for Kling models.
creditModebooleanNodefault falseRender 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.
clientRefstringNo—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 video

One 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.

ParameterTypeRequiredDefaultDescription
promptstringNo—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.
creatorIdstringNo—A saved creator.
productUrlstringNo—A product photo.
imageUrlstringNo—i2v: the first frame; ref: the first reference (@Image1); ugc: an opening frame.
imageUrlsstring[] ≤ 28No—ref: more references (@Image2…); clone: more people, outfits, products or a place.
endImageUrlstringNo—A last frame, on models that take one.
videoUrlstringNo—clone, captions, edit, extend: the source clip; ref: a reference clip (@Video1).
videoUrlsstring[] ≤ 3No—ref, edit: more reference clips (@Video2…).
audioUrlstringNo—ref, edit: an audio reference (@Audio1): a song, a voice line, a beat to follow.
audioUrlsstring[] ≤ 10No—More audio references (@Audio2…).
durationinteger 2–30Nodefault 8Seconds. Seedance 2.5 edit and clone follow the source clip's length.
aspectRatiostringNodefault per model9:16, 16:9, 1:1 or auto; Wan 3.0 and Wan 3.0 Prime also 21:9 (text and reference modes).
resolutionstringNodefault per model720p or 1080p.
audiobooleanNodefault trueNative sound and dialogue.
seedinteger 0–2147483647No—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.
promptExpansionbooleanNodefault —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.
autoLengthbooleanNo—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.
draftbooleanNodefault falseSeedance 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.
draftIdstringNo—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.
keepAudiobooleanNodefault trueclone: keep the source clip's soundtrack.
cloneMode"swap" | "motion"Nodefault swapclone: swap keeps the clip and changes only what you name; motion makes a new video on the clip's movement and cuts.
sourceModelstringNo—extend: the model that made the source clip.
modelstringNo—A specific model. Leave it out and the role's default is used (elyum_models lists them).
klingobjectNo—Kling controls (below, "Kling options"); only for Kling models.
clientRefstringNo—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 audio

Speech (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.

ParameterTypeRequiredDefaultDescription
mode"tts" | "music" | "sfx"Nodefault ttstts: the prompt is the script; music: the track brief; sfx: the sound.
promptstring 2–4000Yes—The script, or a one-line brief.
voicestringNodefault Ariatts: a voice the model lists in elyum_models.
durationnumberNo—Seconds: music 5–300 (60 when left out; the price follows it), sfx 0.5–22.
modelstringNo—A specific model. Leave it out and the role's default is used (elyum_models lists them).
clientRefstringNo—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 looks

Free. 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.

ParameterTypeRequiredDefaultDescription
sectionstringNodefault allall, models, look, palettes, moves, emotions, lights, cast_sheet or edit.

elyum_make_cinema

generateShoot in Cinema Studio

A 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.

ParameterTypeRequiredDefaultDescription
kind"video" | "image"Nodefault videoA shot, or a keyframe (image).
promptstringNo—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.
modelstringNo—A Cinema Studio model (elyum_cinema_looks, section models); the first is the default.
lookobjectNo—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.
movesstring[] ≤ 6No—Video: camera movements added at the end of the scene, in order.
colorsstring[] 2–12No—Video: a palette of your own (#rrggbb, the main colour first) instead of look.palette.
lightsobject[] ≤ 2No—Video: hand-placed lights instead of look.lighting — color (#rrggbb), brightness 0–100, diffuse 0–100, direction (front-top-left…).
castobject[] ≤ 6No—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.
sheetobjectNo—make cast: the AI Cast builder's picks (elyum_cinema_looks, section cast_sheet).
edittrue | { change }No—kind image: change the picture in imageUrl, keeping the rest — texture, lighting or angle, or what the prompt says.
imageUrlstringNo—Video: the start frame (elyum_still gives one); image with edit: the picture to change.
endImageUrlstringNo—Video: the end frame (needs a start frame).
imageUrlsstring[] ≤ 16No—Reference images (@Image1…), before the cast's photos. Not with a start frame.
videoUrlsstring[] ≤ 3No—Video: reference clips (@Video1…).
audioUrlsstring[] ≤ 10No—Video: audio references (@Audio1…).
durationinteger 2–30Nodefault 5Video seconds.
aspectRatiostringNodefault 16:916:9, 9:16, 1:1…; auto keeps a start frame's shape.
resolutionstringNo—Video 480p / 720p / 1080p; image 1K / 2K / 4K.
audiobooleanNo—Video: native sound (the model's default when left out).
creditModebooleanNo—Image: pay the normal price for a model the plan includes free (otherwise browser_only). Ask the user first.
clientRefstringNo—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 avatar

A talking head from one photo and a script. Use a creator's photo for a consistent face. Returns a jobId for elyum_wait.

ParameterTypeRequiredDefaultDescription
photoUrlstringYes—A front-facing photo (a creator's imageUrl works).
scriptstring 2–1200Yes—Exactly what is said, about 2.5 words a second.
voicestringNo—Text-to-speech avatar models only: the voice.
aspectRatiostringNo—9:16, 16:9, 1:1…
modelstringNo—A specific model. Leave it out and the role's default is used (elyum_models lists them).
clientRefstringNo—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 result

Waits 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.

ParameterTypeRequiredDefaultDescription
jobIdstringYes—The jobId a make tool returned (g_…).
timeoutSecondsinteger 0–55Nodefault 50How long to wait; 0 answers at once.
thumbnailsbooleanNodefault trueReturn thumbnails with the result.

elyum_job_status

readJob status

One instant check of a render: status, percent done and time left, or the result.

ParameterTypeRequiredDefaultDescription
jobIdstringYes—The jobId a make tool returned (g_…).
thumbnailsbooleanNodefault trueReturn thumbnails with the result.

elyum_library

readLibrary

Takes 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.

ParameterTypeRequiredDefaultDescription
limitintegerNodefault 20How many, at most 100 a page.
kind"image" | "video" | "avatar"No—Only this kind.
studiostringNo—Only one studio's: image, video, cinema, recast, marketing, avatar, upscale, batch or upload (the user's own files).
genIdstringNo—One take in full: the whole prompt, the request as sent and the files it was made from.
lockedOnlybooleanNo—Only previews not decided yet.
beforeISO timeNo—Items made before it: the at of the last item, for the next page.
thumbnailsinteger 0–12Nodefault 6How many of the first items carry a thumbnail.

elyum_still

writeStill from a take

Free. 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.

ParameterTypeRequiredDefaultDescription
genIdstringYes—The take (g_…).
indexinteger ≥ 0Nodefault 0Which output.
atnumber | "first" | "last"Nodefault lastSeconds into the clip, or its first or last frame.

Keep and kill

The decision on a preview: keep charges, kill releases.

elyum_keep

spendKeep

The 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.

ParameterTypeRequiredDefaultDescription
genIdstringYes—The genId from elyum_wait.
indexinteger ≥ 0Nodefault 0Which output of that render.

elyum_kill

writeKill

Releases 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.

ParameterTypeRequiredDefaultDescription
genIdstringYes—The render's genId.
indexinteger ≥ 0Nodefault 0Which output.
reasonstringNo—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

readbusinessClients

The 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

readbusinessJobs

The 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.

ParameterTypeRequiredDefaultDescription
wrappedbooleanNodefault falseList 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.

ParameterTypeRequiredDefaultDescription
outputsinteger 1–9No—How many outputs in one request.
storyModebooleanNo—A set of story frames; up to 9 images are held and unused ones released.
multiShotbooleanNo—Several shots in one clip.
asmrbooleanNo—ASMR sound.
soundPromptstring ≤ 2500No—What the sound should be.
musicPromptstring ≤ 2500No—What the music should be.
keepSoundbooleanNo—Keep the source clip's sound.
orientation"image" | "video"No—Motion control: follow the image's or the clip's orientation.
imageRolesstring[] ≤ 6No—subject, scene or style, per reference image.
subjectsstring[] ≤ 10No—Kling subject ids (ks_…); @Subject1 is the first.

6.Resources

ResourceWhat it holds
elyum://guideThe agent guide: formats, the workflow and the traps. Read it before the first render.
elyum://accountBalance, plan, kills left.
elyum://creatorsHouse and workspace creators.
elyum://modelsWhich model serves each role, and what it supports.
elyum://pricingThe 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.

CodeMeaning
402Not enough credits. The agent tells the user; it never kills other previews to make room.
key_capThe token's daily cap is reached. Stop and tell the user.
scopeThe token lacks the scope for this tool. Create one with it on Connections.
lockedA preview was used as an input. Keep it first.
browser_onlyA plan-included model over MCP. Nothing charged; ask before retrying with creditMode.
plan_requiredFree credits cannot run this model (Seedance and Kling video, Upscale). Pick another one, or a plan unlocks it.
kill_allowanceNo kills left this billing period.
concurrencyToo many renders in flight. Wait for one to finish (elyum_wait), then retry.
maintenanceNo render starts until it is over. Nothing was charged.
renewal_failedThe 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 client argument (a client id or its exact name). elyum_clients lists the clients and the budget left on each.
  • The agent sees its client's work and the business library, never another client's. elyum_account gains an agency block: workspace, role, client and the monthly budgets.
  • Budgets are hard limits: 429 member_budget and 429 client_budget hold nothing and tell the agent to stop and ask.
  • In a business with jobs, every make_* tool takes an optional job (an id, code or exact name; elyum_jobs lists them): the job's budget pays (429 project_budget when 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.

  1. 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/…).
  2. 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.
  3. Paste the Tenant ID shown on the same page into Claude's Tenant ID field. It ties the issuer to this business alone.
  4. 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://guide
# 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.