Generation MCP Server
Generate images, video, audio, and music via AI — and optionally persist the results as workspace assets.
|
|
queued mode, returns its assetIds at once and keeps generating; it may optionally persist into the user's Assets so the result is reachable from the VFS server like any other file.https://api.charmiq.ai/mcp/generationTools
list_models | |
create_image | |
create_music | |
create_sound_effect | |
create_speech | |
create_text | |
create_video |
list_models first for media. It tells you which providers and which model IDs the calling user is currently allowed to use. create_text's language models are listed in its own model input.Provider-as-Key
create_* tool uses a provider-as-key input shape: configuration goes under a key named for the provider you're targeting. Exactly one provider key may be present.{ "google": { "modelId": "imagen-4.0-ultra-generate-001", "prompt": "An overhead photo of a wooden desk with a brass compass", "aspectRatio": "16:9" } }
elevenlabs | |
google | |
openai | |
openrouter |
list_models returns the supported model IDs, and the tool's input schema documents the per-provider parameters. Treat it like a discriminated union with the provider as the discriminator.create_text is the exception: it takes a model ID directly (Claude 5.5 Haiku when omitted), with no provider key and no provider configuration. The Platform builds each model's configuration from that model's own defaults, so a call never attaches tools, MCP servers or web search. A model that searches on its own, such as Perplexity's Sonar, still does.Output Modes
mode parameter that controls what comes back and what gets persisted:url (default) | assetIds + usable URLs | |
asset | assetIds only | |
content | ||
content+asset | assetIds | |
content+url | assetIds + URLs | |
queued | assetIds at once, while the Assets are still generating |
url, asset, content+asset, content+url, queued), the returned assetIds correspond to charmiq://file/<id> URIs, and the result's text names both (Asset IDs: and URIs:). An Application in a document plays or shows a file by its URI. Pass them to VFS server tools like read_file or describe_file to read or manage the asset.content is right for one-shot pipelines that just want bytes and don't want to clutter the user's Assets. Everything else persists.queued never waits: its result carries queued: true, and each Asset is generated in the background. Read each URI with the VFS server's describe_file until its storeStatus is stored (it then carries downloadUrl) or failed (its errorMessage says why). Use it for a generation that can take longer than a minute (video, a full song) and for a caller that may leave before the generation completes, such as an Application on a phone.create_text has no mode and no queued form: it returns the reply's text and makes no document or Asset, so it always waits for the whole reply. Its Usage is recorded like any generation's. Like every waiting call, a caller stops waiting after 60 seconds; the reply, and its Usage, may still complete. For a long reply, ask for fewer tokens (maxOutputTokens) or a faster model.Where Assets Are Stored
parentFolderId names, or at the root for 'root'; a named folder you cannot add to is refused. When parentFolderId is omitted, they go to the folder of the document the request comes from — the document a Charm runs in, or the document hosting an Application — when you can add to that folder, and share its permissions. Otherwise (you only view that folder, the document is at the root, or there is no document, as for an external client) they go to your root, private to you. content mode stores nothing and reads no folder.Generation Notes by Type
Images — create_imagesupports both text-to-image and image-to-image. PassimageUrlsfor the image-to-image case; the URLs can becharmiq://file/<id>URIs from the user's Assets or external HTTPS URLs. Imagen models handle multi-sample batching natively (sampleCount1–4);gemini-2.5-flash-imageis the natural-language edit path (replaces the deprecated Imagen mask-based edit) and returns one image per call.Speech (TTS) — create_speechsupports single-speaker and multi-speaker modes (up to 2 speakers). Multi-speakertextis oneName: textline per turn, each starting with a configured speaker name. Gemini 3.8 TTS models speaktextverbatim: delivery direction goes instyle(per speaker in multi-speaker mode) or inline as a[direction], which styles the speech after it and is never spoken; a|reaction|inside a turn is the listener's backchannel; vocal events such as<sigh>or<short pause>go inline in the text.Sound effects — create_sound_effecttakes a description of the sound (a door creak, rain on a roof), never words to speak: speech iscreate_speech, a composition iscreate_music.elevenlabstakes adurationSeconds(0.5–30), a seamlessloopand apromptInfluence(0–1);openrouter(Seed Audio) chooses the length itself (up to 120 seconds) and takes none of those. A control the provider does not take is refused, never ignored. Inlist_models, typesound-effectlists these models; typeaudiois speech.Music — Prompts are weighted: each prompt has a text description plus a 0.0–1.0weight. Mix several prompts with different weights to nudge the result.Video — Veo generations are the longest-running of the four. Expect them to take longer than image generation. Text — create_texttakes aprompt(what to write), optionalinstructions(how to write it: a role, a format, rules), amodeland an optionalmaxOutputTokensup to the model's own limit. One call is one reply, with no tools attached and no document. The named model is the one that runs. The result carries the reply'stext, themodel, and astopReason(lengthwhen the reply hitmaxOutputTokens, and the result's text then says so). A reply with no text, such as a refusal, is a failed call (success: false) whose text says why. A control it does not take, such astemperature, is refused.
Where It Was Made
Chat, not the Workspace it is about); the Platform supplies it, and a
place argumentdoes not change it. Called from outside a document, the optional
place records wherethe generation was made: the same captured Place
create_note takes (see the Note MCPServer). A Place that names a Material is accepted only when you can read that
Material; otherwise nothing is generated or charged.
Patterns
list_modelsfirst, every time. The supported model set changes; the cost of one extra call is negligible.Default to urlmode for user-facing flows. It returns usable URLs immediately and persists for later access.Default to contentmode for pipelines. No Assets clutter, no follow-up VFS calls.Use queuedwhen the caller can check back. Check every few seconds withdescribe_file, and give up after a few minutes: an Asset can staystoringif its generation never settles.Provider-as-key is non-negotiable for media. Exactly one provider key per call. Two providers (or zero) is a request error — unless providernames which one to use (create_image), in which case the other block is ignored.Options are per-model. quality,size,style, andbackgroundvalidate against the chosen model — a cross-model value (maxquality ongpt-image-2) fails the call immediately, naming the supported values.