io.github.most-ai-com/mostai-mcp

Animate a still picture into a video. `prompt` describes the MOTION, `source` is the image (https URL or local path). On bytedance/seedance-2.5-turbo, bytedance/seedance-2-fast, bytedance/seedance-2-mini, wan/3-0-video and minimax/minimax-h3, `mode` defaults to `reference` on the backend — which treats the photo as a style/subject reference, NOT the frame to animate. Since that would defeat the point of this tool, leaving `mode` unset here auto-applies `mode='frames'` on those five models (a result warning says so); pass `mode='reference'` explicitly to get the reference behaviour instead. A SECOND picture in `source` becomes the last frame only in `mode='frames'`. google/veo-3.1-fast(-relax) already default to `frames` on the backend, so nothing changes there. Models carrying the 'video:first_last_frame' capability (kwaivgi/kling-v3.0, bytedance/seedance-1.5-pro) have no `mode` at all — two pictures in `source` are first/last frame by input order. The default xai/grok-imagine-video takes up to 7 pictures as references (all forwarded) and reads `mode` as TONE (normal/fun/spicy), never frames. xai/grok-imagine-video-1.5 and minimax/hailuo-2.3-fast are image-to-video ONLY — a call with no `source` picture is refused before anything is uploaded or charged. Default `xai/grok-imagine-video` — budget, Russian voice-over, free quota; it adapts the aspect ratio to the attached photo. For a talking/singing portrait use the lip-sync app instead (generate_media with kling/ai-avatar, photo + audio); for a trending dance from one photo use kwaivgi/kling-v2.6-motion-control with a preset. Slow — prefer `wait=False` and poll media_status(); your MCP client may enforce a shorter tool timeout than the server's 10-minute wait, and a wait that runs out returns status 'progress' with a poll hint rather than an error. Money, `free_mode`, `save_path`, `max_price` and the duplicate guard (`new_variant`) behave exactly as in generate_image — the video window is 20 minutes, since a clip…

Get an independent SECOND OPINION from a different AI model — optionally on files it reads. Offer this proactively whenever an outside check would help: a plan you are about to commit to, a risky or contested decision, a calculation, generated code before it ships, a document worth a second reader. The default `chatgpt-free` costs 0 ₽ and is unlimited, so a sanity check is always safe. Any other text model bills ₽ PER TOKEN (see `cost` in the reply, `price_in_per_token`/`price_out_per_token` in describe_model) — bonuses first, then the ₽ balance, after the reply. A paid model returns `status: "needs_confirmation"` with the price and an estimate BEFORE anything is uploaded or sent; relay it to the user and re-call with confirm=True only after they agree (see MOSTAI_WARN_CHAT_RUB). Never spend on a paid model without that. `files`: one local path or a list (max 10, 50 MB each, no URLs). Documents (pdf/docx/pptx/txt/md/rtf/epub/…), spreadsheets (xlsx/csv/…), pictures (jpg/png/gif/webp/ heic/svg — OCR'd AS TEXT: the consultant reads what was extracted, it does NOT see the picture) and audio/video (mp3/mp4/wav/m4a/webm — the audio track is transcribed; .mov is refused). Parsing is asynchronous (seconds to a few minutes); this call waits up to `wait_timeout` seconds (default 180, max 300). It NEVER sends while a file is still parsing — you get `status: "files_pending"` (nothing sent, nothing spent) and re-call with the same `session` (omit `files`) a little later. Parsed files stay attached to the session and are re-injected into EVERY later message there — free on chatgpt-free, billed as prompt tokens each time on a paid model. `on_parse_error`: "auto" (default) — on a free model, answer using the files that parsed and warn about the failed ones; on a paid model, or when no file parsed at all, return `status: "parse_failed"` without sending. "abort" always returns parse_failed; "continue" always sends with what parsed. `session`: pass the value a previous call return…

Generate text with a MostAI text model and return the full reply. `chatgpt-free` (default) costs nothing and is unlimited. Every other text model bills ₽ PER TOKEN — `price_in_per_token` / `price_out_per_token` in describe_model (the catalogue's `credits_per_message` is a legacy number, not what MostAI charges) — bonuses first, then the ₽ balance, booked after the reply. Their `price_rub: 0` does NOT mean free. This tool has no confirmation gate: for a paid model prefer ask_second_opinion, which quotes the price and asks first. `session` continues a MostAI-side conversation: the files attached there come back automatically, but earlier TURNS are not replayed by the backend — use ask_second_opinion(session=...) for a follow-up that remembers the previous answer. No text model can see a picture (attachments_limit=0 on all of them). To have a model READ a document, spreadsheet, picture (OCR) or recording, use ask_second_opinion(files=[...]).

Permanently DELETE one of your generations. Irreversible. `item_id` is the numeric `id` from a generation/gallery result (NOT `public_id`, the string used by media_status / share_link / preview_media); every generate_* / media_status result carries both.

Everything needed to call one model correctly on the first try. Returns the normalized spec: `parameters` ({name: {type, options, default}} — the allowed values, e.g. duration 5/10/15, quality 720p/1080p), `inputs` (attachment slots with max counts / durations and whether they are required), `no_prompt`, `named_inputs` (uuid-valued slots such as faceswap's swap_image / input_image — pass them to generate_media as `named_images={slot: file}`), `capabilities`, `badge`, `disclaimer` (plain text), price (`price_rub` + `price_per_sec_rub`), `free_left` and an `example_call` you can copy. Two fields appear only where they exist: `presets` (dance templates — only on kwaivgi/kling-v2.6-motion-control) and `voices` (only on the three TTS models: elevenlabs/v3, elevenlabs/text-to-dialogue-v3, google/gemini-3.1-flash-tts). Call this before generating with an unfamiliar model — the generic tool defaults are not valid for every model, and a wrong parameter is refused before it costs anything.

Download a generated file (image/video/audio) to local disk; return its binary path. `url` is a result link from generate_* / media_status / list_gallery. `dest_path` may be a file path or a directory; the default is absolute — `$MOSTAI_HOME/downloads`, i.e. `~/.mostai-mcp/downloads` — and does not depend on the working directory. A RELATIVE `dest_path`, however, resolves against the server's working directory, which is not the caller's folder: under the shared HTTP hub the server runs once per machine, so pass an absolute path whenever the file must land somewhere specific. The MostAI cookie is sent only if the URL is on the app host. Returns {path, bytes, content_type, url}. Use this when you need the raw file (e.g. to upload into an ad campaign); use the result `url` directly when a stored link is enough (the file is hosted for a long time).

Image-to-image: transform an existing picture according to `prompt`. `source` = the reference image as an https URL or a local file path (or a list of them to combine several). When `source` is a list, every picture is a reference of equal standing — say in `prompt` which one is the photo to redraw and which are style references. Use an edit-capable model (`capabilities` contains 'image:edit' — see list_models / describe_model); the default google/nano-banana-2 takes up to 14 references and has free quota. For removing a background, upscaling, enhancing or swapping a face, do NOT prompt an edit model — call the dedicated app through generate_media (see its docstring): it is cheaper and far more reliable. Money, `free_mode`, `aspect_ratio` (including on models that honour it without declaring it in the catalogue — see generate_image) and the duplicate guard (`new_variant`) behave exactly as in generate_image.

Price a media generation in ₽ WITHOUT running or paying for it. Pass the same `duration` / `quality` / `parameters` you intend to generate with — price depends on them (a 30s 1080p clip is not the catalogue's "from" price). `duration` / `quality` given here override the same keys in `parameters`, and both take exactly the strings/ints describe_model lists (e.g. '1080p', 10). Invalid values are refused here, listing what the model allows; model ids come from list_models(type='video'). Returns `price_rub` (per generation), `price_per_sec_rub` (added per second, video) and `free_left`: -1 = unlimited free runs / a positive number = that many free runs left / 0 = the free quota is used up / null = this model has no free tier. With free quota the generation can cost 0₽ instead of the quoted price.

Speech, dialogue or music from text. Costs ₽ (single digits for TTS, ~20₽ a song). The model-specific parameter keys are filled in for you from `text`/`voice`/`style`: - `elevenlabs/v3` (default) — one narrator; `voice` is a NAME, expressive, good Russian. Omitting `voice` gives Rachel (female). Typically female: Rachel, Jane, Juniper, Arabella, Hope, Blondie, Priyanka, Alexandra, Monika; typically male: James, Bradford, Reginald, Austin, Kuon, Mark, Grimblewood (gender inferred from the studio's voice notes — verify with describe_model(model).voices). - `google/gemini-3.1-flash-tts` — `voice` like 'Kore'/'Puck'. - `elevenlabs/text-to-dialogue-v3` — several speakers: pass `text=""` and put the lines in `dialogue=[{"text": "...", "voice": "James"}, {"text": "...", "voice": "Arabella"}, …]`. IMPORTANT: this model accepts only 67 specific voices — NOT the full ElevenLabs catalogue elevenlabs/v3 draws from — and a voice outside that set (e.g. "Ellen", "Jane") is REFUSED here before anything is charged, not passed through to a paid failure. A known name from describe_model(model).voices is resolved to its ElevenLabs id for you; a raw id works too, as long as it is one of the 67. - `suno` — MUSIC. `text` is sung verbatim as the lyrics: write full lyrics and use [Verse] / [Chorus] tags. `style` = genre/mood; `voice` = 'female' (default) or 'male' — suno has no named voices, any other value is dropped with a warning. An unknown voice on elevenlabs/v3 or google/gemini-3.1-flash-tts is a warning, not a refusal (those voice lists are a frontend snapshot that can lag a live catalogue) — see describe_model(model).voices for the current ones. The dialogue model above is the one exception: its 67-voice set is a closed provider enum, not a snapshot, so an unaccepted voice there is a hard refusal instead. `parameters` is MERGED over the payload built above, so you can override one key and keep the rest. The keys per model (describe_model(model).paramete…

Generate an image from a prompt. Costs ₽ (single digits to ~10₽ for the popular models) — or 0₽ when free quota is available, which happens automatically. Default `google/nano-banana-2` follows instructions well, edits, and has free generations. See list_models(type='image') for the rest and describe_model(model) for that model's valid `quality`; leave it None to take the model's own default. `images` = reference pictures (a bare https URL/local path, or a list of them) for image-to-image on edit-capable models — edit_image is the simpler shape for that. A `url` from an earlier generate_*/media_status/list_gallery result works here too — no download needed. `aspect_ratio` is checked against the catalogue when the model lists `aspect_ratio` options (describe_model). Some models honour it WITHOUT declaring it in the catalogue — e.g. google/nano-banana-2, google/nano-banana-pro, openai/image-2, and video models that offer it in the studio UI: a common value ('1:1', '16:9', '9:16', '4:3', '3:4', …) still works there, it just cannot be validated up front, and an unrecognised value on one of THESE models is silently dropped by the backend rather than rejected — check the actual output if you are not sure it took effect. Money: an invalid parameter is refused before anything is charged. A generation at or above MOSTAI_WARN_PRICE (default 50₽) returns `needs_confirmation` and charges nothing — relay the price to the user and only then re-call with confirm=True. `max_price` is a per-call cap that REPLACES the MOSTAI_MAX_PRICE hard cap for this call (omit it to keep the configured cap). `free_mode`: None = auto (free when quota remains and you did not pin quality), True = force free (the backend then locks quality/duration to the cheapest option), False = always pay. `save_path` also downloads the result — pass an absolute path: a relative one resolves against the server's working directory, not yours. `wait=False` returns {public_id, status:'progress'} at once — poll me…

Call ANY model in the catalogue — including the "AI apps" that take no prompt at all and are driven by attachments. Costs ₽ (a few to a few dozen per run). `images` / `videos` / `audios` / `named_images` accept a bare https URL/local file path or a list of them; `named_images` fills the `named_inputs` slots describe_model lists (an unlisted slot is refused before anything is uploaded). A `url` from an earlier generate_*/media_status/list_gallery result can be passed straight back as a reference — no download needed. Task -> model -> what to pass: - swap a face: model="faceswap", named_images={"swap_image": face.jpg, "input_image": photo.jpg} — swap_image is the NEW face, input_image the target photo. Which face in a multi-face target gets replaced cannot be chosen: use a single-face target. - remove the background (transparent PNG): "background-remover-v1", images=[photo] - upscale a photo: "prunaai/p-image-upscale", images=[photo], parameters={"factor": "x2"|"x4"} - restore / enhance a photo: "enhance-photo", images=[photo] - animate a photo: "livephoto", named_images={"image": photo}, parameters={"duration": 5|10} — livephoto reads a NAMED slot, not the plain image list, so images=[photo] would be uploaded and then ignored by the backend - picture -> SVG: "vectorize", images=[photo]; prompt -> SVG: "vector-image", prompt="..." - upscale a video: "bytedance/video-upscaler", videos=[clip], parameters={"quality": "720p"|"1080p"|"2k"|"4k"} - lip-sync a portrait to a voice: "kling/ai-avatar", images=[photo], audios=[voice] - trending dance from one photo: "kwaivgi/kling-v2.6-motion-control", images=[photo], preset="Ландыши" (or videos=[your own reference clip]) `preset` only applies to the dance model; pass a template name (describe_model lists them), a filename, or your own https URL. Parameters are validated against the catalogue before anything is uploaded or charged. For a plain prompted edit on an edit-capable model use edit_image — the sam…

Generate a video from a prompt (and optional pictures). Costs ₽ — video is the expensive family, tens to hundreds per clip, so check estimate_price first when the model is unfamiliar. Default `xai/grok-imagine-video` is the budget option with Russian voice-over and free quota. See list_models(type='video'); describe_model(model) lists the valid `duration` (in seconds) / `quality` / `mode` for that model. Leave a parameter None and the model's own default applies — nothing is sent that you did not ask for. `xai/grok-imagine-video-1.5` and `minimax/hailuo-2.3-fast` are image-to-video ONLY — a call with no `images` is refused before anything is uploaded or charged. `mode` is MODEL-SPECIFIC. Only models whose `mode` options include 'reference'/'frames' place pictures as first/last frame: bytedance/seedance-2.5-turbo, bytedance/seedance-2-fast, bytedance/seedance-2-mini, wan/3-0-video, minimax/minimax-h3, google/veo-3.1-fast, google/veo-3.1-fast-relax as of the 2026-09-03 snapshot. There 'reference' = each picture is a style/subject reference and 'frames' = the first picture is the first frame, an optional second the last (this tool keeps whatever `mode` you pass, including its default 'reference' on those five models — animate_image instead defaults to 'frames' there, since a still photo is the whole point of animate_image). The default xai/grok-imagine-video uses `mode` for TONE (normal/fun/spicy), takes up to 7 reference pictures and does no frame placement — always check describe_model(model).parameters.mode. `images` = reference frames (a bare string or a list); `videos` / `audios` feed models that take them (e.g. a lip-sync avatar). `sound` is 'on'/'off' where supported. A `url` from an earlier generate_*/media_status/list_gallery result can be passed straight back in `images`/`videos`/`audios` as a reference — no download needed. Video is slow: prefer `wait=False` and poll media_status(public_id). With `wait=True` the server waits at most 10 minutes and then…

Current MostAI balance in ₽, plus the free generations available right now. `free_generations` maps model id -> free runs remaining TODAY (-1 = unlimited; the quota resets daily at `free_reset_at`, UTC). Those cost 0₽: the generate_* tools use them automatically when quota remains and you did not pin a paid quality/duration. The map is cached and may be up to 60 s stale — list_free_generations() reads it live.

Like a generation (yours or someone's public one). `item_id` is the numeric `id` from a generation/gallery result (NOT `public_id`, the string used by media_status / share_link / preview_media); every generate_* / media_status result carries both.

How many FREE generations remain per model TODAY, read LIVE. Returns {"free_generations": {model_id: remaining today}, "limits": {model_id: daily allowance}, "reset_at": ISO-8601 UTC when the daily quota comes back, "note": …}; -1 means unlimited, a model absent from the maps has no free tier. The reading also refreshes the cache get_balance serves from. The generate_* tools use this quota automatically; pass free_mode=True to insist on it (the backend then locks quality/duration to the cheapest option) or free_mode=False to always pay.

List recent generations. `success_only` keeps only finished ones; `tag` filters by tag; `public=True` browses the public/explore feed instead of your own gallery. Items come most recent first; each carries `id` (delete/publish/like), `public_id` (media_status/share_link/preview_media), `status`, `model`, `prompt`, `url`/`urls` and `error`.

List MostAI models, LIVE from the API. Prices are in ₽ per generation. `type`: 'image', 'video', 'audio' or 'text' (omit for everything). Sorted cheapest first by default; text models sort by `price_rub_per_1k_tokens.output` instead (free models first), since they are billed in ₽ per token, not in ₽ per generation. Shortlist by capability from this list, then call describe_model(id) for the exact parameters that model accepts. Each row carries: - `free_left` — remaining free generations. -1 = unlimited; null = no free tier. The key is always present, so test for null, not for absence. - `capabilities` — what the model can do, e.g. 'image:edit', 'video:first_last_frame', 'video:audio_rus', 'low_moderation'. This is the field to filter on. - `inputs` — which attachment SLOTS exist and their limits ("image≤14", "image=1 (required), audio=1 (required)"). It says nothing about what each slot is FOR; describe_model spells that out. - `no_prompt` — True = an "AI app" driven by attachments/parameters, called through generate_media. - `badge`, `price_per_sec_rub` (added per second of video) and `price_from` (True = the listed price is the cheapest tier; the real charge depends on quality/duration — use estimate_price for that). Retired models are hidden, matching the website; pass include_deprecated=True to see them.

Poll the status/result of a media generation by its public_id. Returns `status` ('progress' while running, 'success' when done, anything else means it failed → the view also carries `failed: true`), `id` (the numeric id used by delete_media / publish_media / like_media), `public_id`, `url`/`urls` (set on success), and on failure `error` (readable reason, usually content moderation) plus `alternatives` — other models worth trying. Polling also updates the duplicate guard: once a job started with wait=False reports its outcome here, an identical generate_* call within the window is answered with that outcome instead of a stale 'progress' snapshot.

Return a generated IMAGE inline so you can actually SEE it and judge it. Accepts a result URL or a public_id (from generate_* / list_gallery). For an image, shows the image itself; for a video, shows its thumbnail. Use this to review a result before downloading it or pushing it into a campaign. (Audio has no visual preview.) The image is returned as tool output and is visible to the user in the conversation too — there is no private preview.

Publish (or unpublish) one of your generations to the public gallery. Returns the updated record. `item_id` is the numeric `id` from a generation/gallery result (NOT `public_id`, the string used by media_status / share_link / preview_media); every generate_* / media_status result carries both.

Public share URL for a generation (no API call) -> https://most-ai.com/s/{public_id}. This only formats the link — it does not check that the item exists, that it succeeded or that it is published.

Show balance and the configured spending guards (low-balance threshold + price caps). Configure via env: MOSTAI_MIN_BALANCE (low-balance alert, default 50), MOSTAI_WARN_PRICE (mark a generation 'expensive', default 50), MOSTAI_MAX_PRICE (hard cap — refuse generations above it; unset = no cap), MOSTAI_DEDUPE (0 = duplicate guard off), MOSTAI_DEDUPE_WINDOW_S (how long an identical generate_* repeat returns the earlier result; unset = 600 s image/audio, 1200 s video; 0 = never reuse a finished result, a running one is still never started twice) and MOSTAI_WARN_CHAT_RUB (ask_second_opinion/chat: 0 = every paid text model needs confirm=True, N = ask only when the estimated cost is >= N ₽). A `max_price` passed to a single generate_* call REPLACES the MOSTAI_MAX_PRICE cap for that one call — it is a per-call cap, not an extra limit on top of the configured one.

Get the link to add funds to the MostAI balance. The USER pays on the MostAI page — this server cannot take, hold, confirm or route a payment (no such capability, by design); it only hands over the link. On that page the user picks their country and payment method (card, SBP, etc. — the site shows what fits their country) and any current bonus is shown there. Relay `pay_url` to the user and tell them to open it; nothing is charged here. `amount_rub` is optional and only used to phrase the message — the amount is chosen on the page.

Account profile: email, message credits and permissions. `message_credits` is a separate currency from the ₽ balance: it pays for `chat` messages only, media generation spends ₽.