Mage.Space

Stop a queued or running request started with generate. Its Gems are not refunded. A finished request cannot be cancelled, and cancelling a cancelled one changes nothing.

Save a private character from a name and an image (a public https URL or a data URL of a JPEG or PNG), optionally with a voice clip (MP3 or WAV, trimmed to 10 seconds). Returns its handle: mention it in a generate prompt as @handle. Publishing a character happens in the Mage app.

Save a private reference: an outfit, pose, location, or object from an image (a public https URL or a data URL of a JPEG or PNG), or a voice clip (kind: audio) from audio (MP3 or WAV, trimmed to 15 seconds). Returns its handle: mention it in a generate prompt as @handle.

Get a signed URL to upload a local file too large for a data URL (over about 3 MB): an image, a video, or an audio clip, up to 100 MB. Only for a file on a machine where you can run commands: this server cannot read files attached to the chat. PUT the file to upload_url before upload_url_expires_at with exactly the returned headers, for example curl -X PUT -T clip.mp4 -H 'Content-Type: video/mp4' -H 'x-goog-content-length-range: 0,104857600' '<upload_url>'. Then pass url as a media input to generate (a first frame, reference images, or a source video) or as the image or audio of create_character or create_reference; estimate_cost measures a video at url to price it. Each upload holds one file: for a new or corrected file, call create_upload again, never PUT to an earlier upload_url, because the CDN keeps serving the first file at url for up to 4 hours. The file is deleted at url_expires_at.

Delete one of the account's characters by its id from list_characters. Its handle stops working in prompts at once.

Delete one of the account's references by its id from list_references. Its handle stops working in prompts at once.

Price a generation before starting it: takes the same architecture and config as generate and returns what it would charge in Gems, with the account balance, or the refusal generate would answer, so a config that breaks the model's rules is caught here for free. Nothing is charged or stored. A video input is measured to price it when it is a create_upload url, an earlier result, or a data URL; a video on another host answers requires_media_measurement, since only generate downloads it: upload it with create_upload to price it first.

Start an image, video, or audio generation, paid in Gems from the account. config is a partial config in the model's field names (see get_model), layered onto the model's defaults; set model_id to the variant you chose from list_models; mention saved characters and references in prompt as @handle; and pass media inputs as https URLs of the files or data URLs, uploading a larger local file with create_upload first. Check the price with estimate_cost first; it also refuses a config the model would refuse, at no cost. The account runs a limited number of generations at once, counting ones started in the Mage app (get_account shows how many are in flight); past it, generate answers too_many_requests, so start a batch in waves. Make a new idempotency_key for each generation you mean to start, and send the same key again only to retry a call whose response you did not get: the retry returns the original request without charging again. Returns a request_id; call get_request with it to wait for the result.

The connected Mage account: its username, its Gems balance, what auto top-up can add when a generation needs more (gems.auto_top_up: the Gems of one package, bought at most once per generation, and the Gems it can still add this month, null for no monthly limit; both 0 when it is off), and how many generations are in flight against its limit. Every generation started here is paid from this balance, and generate refuses one past the limit (too_many_requests), counting generations started in the Mage app too, so read this before starting a batch.

Describe one model: the JSON Schema of the config generate takes (input_schema), the allowed values of each option (options, narrowed per model_id in options_by_model), its defaults (base_config), the fields that take image and video URLs, the @handle mentions it accepts and its image budget, the rules a request must follow, its price in Gems at its defaults, its documentation page, and, as in list_models, its tier and each variant's price and what it is best for and trades off.

Read a request started with generate: its status (queued, in_progress, completed, failed, or cancelled), its result, and the Gems it charged. It waits up to wait_seconds (default 45, at most 120) for the request to finish; call it again while the status is queued or in_progress. To follow many requests at once, list_history with status: "in_progress" (or queued, completed, failed) lists them with their request_id. A result's url stays available for 30 days, so tell the user to download what they want to keep. Generations started in the Mage app are not requests; list_history shows them.

List the account's saved characters, newest first: each one's handle, name, image, and voice. Put @handle in a generate prompt to include the character. Other users' public characters also work by handle, but are not listed.

List the account's generations from the last 30 days, newest first, whatever started them (source): the Mage app (app), the API (rest), this MCP server (mcp), the Mage sidekick (agent), or auto-creation (auto). Each has its prompt, model, status, result URL, and billing: gems with the Gems charged, or unlimited for app generations covered by a membership. request_id is set for API, MCP, and sidekick generations, which get_request and cancel_request accept. Media expires 30 days after it was made; the user's saved creations, kept permanently, are in search_creations.

List the models Mage generates with, as a guide to choosing one. Unless the user names a model, generate images with Mango 4 (mango, model_id mango-v4), video with Cherry 2 Pro (cherry, model_id cherry-2-pro), and audio with Seed Audio (seed_audio, model_id seed-audio-1.0) (defaults). Each model has its id (the architecture get_model, estimate_cost, and generate take), media type, tier, price in Gems at its defaults, and summary; each variant has its model_id, price, options, image budget, and what it is best for and trades off. By default only the default and recommended models are listed: the rest are opt-in, listed with include_opt_in, and run only when the user asks for one by name. Call get_model before using one.

List the account's saved references, newest first: outfits, poses, locations, objects, and voice clips. Narrow to one kind (outfit, pose, location, object, or audio), for example outfit for the user's outfits. Mention a reference in a generate prompt as @handle.

Search the creations the user saved in Mage, which are kept permanently: by meaning with query (for example "a red car at night"), by media type, by collection, or by date. Without a query, newest first. Each result has its permanent URL, prompt, and model.