MCP server documentation

Account context: the balance (prepaid dollars, plan credits, or internal and never blocked), the plan, your projects (id + name, most generation tools need a projectId), and the avatars you can use (id, name, gender), plus the full cost sheet. Call this first.

Free: discover what every tool can do, its options (providers, modes, ratios, voices, templates), its credit cost, and whether it blocks while rendering. The catalog browser for this MCP (the aitachyon analog of a model catalog). Optional `filter` narrows by tool name or keyword. Call this and get_me before generating.

Free: list the concrete choosable presets per tool - camera motions, script/export templates, image providers + quality, edit ops, scene direction, voices, aspect ratios, caption platforms. The menu of exact enum values to pass verbatim (the aitachyon analog of presets_show). Optional `filter` narrows by group name or value.

Free: check the status of an async render — by kind (scene | avatar) + taskId, or by the statusPath a still-rendering call handed back (covers every async tool). Returns the status, a poll_after_seconds hint for non-terminal jobs, and the media url once completed. sync:true long-polls server-side for up to ~25s and returns as soon as the job is terminal (use it instead of spamming). generate_scene / avatar_generate already auto-wait, so use this to re-check a long render or one whose auto-wait timed out.

Free: the queryable ENGINE catalog — every model this MCP can drive (live), every engine this MCP can drive. action: list (browse, filter by type image|video|audio|3d and/or status live|planned|missing) | search (keyword) | get (model_id, full record) | recommend (describe the GOAL — e.g. 'cheap vertical b-roll with audio' — returns the top 5 with match reasons and the exact tool + params to use). Call this before picking an engine; prefer recommend when unsure.

Generate one on-brand marketing image. Providers: nanobanana (default, photoreal) | seedream (cheap draft) | recraft (crisp text/logos) | imagen (Google retired Imagen 4; renders on Nano Banana 2.1) | openai (gpt-image-2, best text + editing, 4 cr). ultra4k:true = native 4K (Nano Banana Pro, falls back to Seedream 5.0), 13 cr. Base 4 cr, +3 for the people skin-finish pass unless finish:false. Supports i2i (referenceImageIds + referenceMode), composited headline/cta and brand logo (placeLogo/logoPosition). getCost:true previews the exact price (pass provider/ultra4k).

Edit an existing generated image (2 credits for remove-bg, upscale, vectorize; enhance 14, inpaint and replace-bg 5, remix 4, outpaint 3): remove-bg | upscale | enhance | vectorize | replace-bg | inpaint. Non-destructive (returns a new image). replace-bg/inpaint need a prompt; inpaint needs a base64 PNG mask. getCost:true previews the price.

Create an on-brand DESIGN carousel rendered in code from the real brand theme. Safe sequence: brand_reference_kit -> lock exact copy -> getCost:true -> render. For bilingual or approved copy, lockedSlides is required and bypasses model authoring: every French title/body is rendered before its English counterpart. requireLogo:true rejects before charging when no usable brand logo exists. Extra placements are free.

Free and non-mutating: inspect a public website before creation and return its canonical URL, real logo candidates, fonts, colors, image references and video references. Call first for every brand-locked carousel or campaign.

Free: return the brand-art-directed prompt (no image, no credits) so you can review/edit it, then pass it back to images_generate as finalPrompt.

Free: up to 5 ready-to-generate marketing image concepts (title, hook, cta, style, prompt) tailored to the project's brand.

Generate a short b-roll video clip (~5s) and WAIT for the render. ENGINES: seedance (default - fast=6 / hd=184 cr flat, identity refs; prefer seedance-2.5 for HD) | seedance-2.5 (4-30s, resolution 480p|720p (default)|1080p at 6|13|31 cr/s, nativeAudio at no extra cost, identity refs OR start image + endImage, i2v keeps the image aspect) | grok (Grok Imagine, audio-native, 5 cr/s, 1-15s) | hailuo (Minimax Hailuo 02, best physics + facial emotion, 5 cr/s, silent, 6|10s, text-to-video 16:9 only) | kling (Kling v3, 5 cr/s silent / 10 cr/s sound) | wan (Wan 2.7, character consistency, 6 cr/s, the model adds its own audio) | omni (Gemini Omni 1.1 Flash by Google, 720p, native audio always, 6 cr/s, 4-10s; veo and veo-lite are aliases of it at the same price, since Google shuts the Veo 3.1 preview models down on 2026-10-22). Gemini engines are 16:9|9:16 only. RATIO (default 9:16): text-to-video honors 9:16|16:9|1:1 on every other engine except hailuo. Image-to-video on seedance-2.5, grok, kling, wan and hailuo keeps the start image's shape: an explicit ratio the image does not have is refused before any charge (omit ratio to keep the image's shape; engine seedance crops the image to the ratio). The result states the aspect read from the finished file. Text-to-video (brand-directed) or image-to-video (imageUrl/imageId). IDENTITY (seedance hd tier or seedance-2.5, never downgraded): referenceImageUrls/Ids (<=4); endImageUrl/Id pins the LAST frame. cameraMotion forces a camera move. Returns the final mp4 URL. getCost:true previews (pass engine / mode / duration / nativeAudio / references).

Upscale/enhance a finished video to 1080p or 4K (studio-grade upscaler) and WAIT for the result. Source: a completed sceneId, or any owned videoUrl. Metered: 2 cr/s at 1080p, 5 cr/s at 4K, minimum 5 (durationSeconds is REQUIRED - it drives the exact bill). Failed jobs are auto-refunded. getCost:true previews the price.

Reframe/expand a finished video to a NEW aspect ratio (Generative reframe) and WAIT - one 16:9 hero becomes 9:16 + 1:1 placements without regenerating. Source: completed sceneId or owned videoUrl. Metered 11 cr/s (durationSeconds drives the bill, default 5). Auto-refund on failure. getCost:true previews.

Motion control / puppeteering and WAIT: transfer the motion + camera of a DRIVING video onto a character STILL - one filmed take drives N avatar variants (the UGC multiplier). imageUrl = the character still; videoUrl = the driving take. Metered 7 cr/s of driving video, min 35 (pass durationSeconds). Auto-refund on failure. getCost:true previews.

Image -> 3D GLB mesh (engines: tripo default | trellis | hunyuan) and WAIT. Opens the 3D modality: product mockups, game-ready assets, AR props. textured:true adds surface textures + PBR (tripo). 22 cr base / 49 cr textured. Returns the GLB url (fal CDN). Auto-refund on failure. getCost:true previews.

Dub/translate a finished video's speech into another language, lip-synced back (Studio dubbing) and WAIT. One ad -> N languages. Source: completed sceneId or owned videoUrl; targetLang e.g. en|fr|es|de|it|pt|ja|ko. 49 cr/min, min 49 (pass durationSeconds). Auto-refund on failure. getCost:true previews.

Clone a voice from 10s-5min of clean single-speaker audio - returns a reusable voiceId for voice_speak. 81 cr one-time. RULE: a cloned voice is used ONLY on the speaker's own content (the no-AI-face rule extends to voice). getCost:true previews. Requires the 2026-07-24 deploy.

Generate speech with a CLONED voice : text + the voiceId from voice_clone -> a normal voiceover row usable in avatar_generate / video_lipsync / assemble_export. 3 cr per 450-char block. getCost:true previews. Requires the 2026-07-24 deploy.

Score a finished video for virality BEFORE posting: samples 6 frames and judges them with a vision model - hook strength, pacing, clarity, CTA, retention risks, and max 3 concrete fixes, plus a 0-100 virality score. A judge pass grounded in our own stack. Flat 5 cr, synchronous. Source: completed sceneId or owned videoUrl. Requires the 2026-07-24 deploy.

Free: curated viral video preset TEMPLATES - open recipes (engine + prompt + camera + duration) that expand into a generate_scene call with {subject} swapped for the user's subject. The full recipe is visible and every axis is tweakable before spending. Optional filter narrows by name/vibe.

Lip-sync an EXISTING video to a new audio track (Lipsync retrofit) and WAIT - revoice a finished scene without regenerating it (the retrofit counterpart of avatar_generate, which creates FROM a still). Source: completed sceneId or owned videoUrl + audioUrl (e.g. from voiceover_generate). syncMode handles length mismatch: bounce (default) | loop | cut_off | silence | remap. Metered 7 cr/s, min 18 (durationSeconds REQUIRED). Auto-refund on failure. getCost:true previews.

Remove the background of an EXISTING video (Background removal, green-screen output) and WAIT. Source: completed sceneId or owned videoUrl. Flat 3 credits. Auto-refund on failure.

Generate a lip-synced talking-avatar video from a presenter still + a voiceover, and WAIT for the render. Per-second billing (kling/omnihuman: max(42, ceil(audioSeconds)*7) credits). imageUrl must be a storage URL (e.g. from creator_presenter.path or avatars_persona); audioUrl + voiceoverId from voiceover_generate. getCost:true previews the price (pass audioSeconds for an exact figure).

Talking UGC in ONE call: a person who says your text, with a quality ElevenLabs voice and a mouth synced to it. Give the text and exactly ONE face: avatarId (recommended), imageUrl, or sceneId / videoUrl (an existing clip of the person -> re-voiced with Sync lipsync-2). With avatarId the default look is 'phone': the same face is re-shot once as a vertical 9:16 front-camera selfie in a real room (no mic, no studio, setting: bedroom|kitchen|car|living_room|bathroom|desk), then REUSED for every later clip with the same setting and prop (look.reused in the result; newLook:true re-shoots). The engines animate the face, not the body: anything held must be in that still, so pass holding ("a white serum bottle") or productImageId, and keep lines short. look:'as_is' animates the library portrait itself. imageUrl is used as it is (the video keeps its ratio). Engine: kling (default, head and face, best value) or omnihuman (body moves, about 5x the price). Leave voiceId out to get a voice that matches the face (pass gender for a raw image or clip). Use this instead of laying a voiceover over a clip. Billed as its parts: phone still 4 cr the first time + voiceover (5 cr / 450 chars) + avatar (max(42, sec*7)) or lipsync (max(18, sec*7)). getCost:true previews.

Create a synthetic on-brand presenter face (4 credits) that appears in your avatar library. Returns the face image URL. getCost:true previews the price.

Create a Twin avatar from photos of the same person (4 credits; +108 if a zero-drift LoRA training kicks off with >=12 refs). Returns the twin face URL. getCost:true previews the price (it accounts for the LoRA when you pass >=12 refs).

Render a UGC 'creator holding the product' still (4 credits). Its .path feeds avatar_generate as imageUrl. Pass creatorId (an avatar id) for a specific face. getCost:true previews the price.

Free: classify the brand product (digital vs physical) and capture a site screenshot for digital products. Returns shotIds.

Free: list the voiceId values voiceover_generate accepts, per provider. elevenlabs = curated ad voices; google = one Chirp3-HD voice per language (pass languageCode too); fish_audio = your own reference_id. Call before voiceover_generate to pick a voice.

Generate a voiceover mp3. Credits = provider rate x blocks(450 chars): google=1, fish_audio=3, elevenlabs=5 per block. Returns audioUrl + duration + the voiceover id (needed by avatar_generate). getCost:true previews the price (pass provider + text).

Generate a short background music bed (4-30s, flat 10 credits). Returns the mp3 url. getCost:true previews the price.

Generate a short sound effect (2 credits). Returns the mp3 url. getCost:true previews the price.

Generate N distinct video script variants (3 credits). tone+duration+cta required. templateId picks the angle (problem-solution | storytelling | direct-response | ugc-style | testimonial | saas_demo). getCost:true previews the price.

Free: write or improve a single line of copy. kind = headline | hook | caption | cta | audience | angle | description.

Generate per-platform social captions (2 credits). platforms: instagram|tiktok|linkedin|x|facebook. getCost:true previews the price.

Analyze a website and create the project's brand (6 credits). Returns the brand row (name, colors, tone, products). getCost:true previews the price.

Synthesize a brand from a text description (6 credits) when there's no site to scrape. getCost:true previews the price.

Generate a brand logo (4 credits): wordmark | monogram | emblem. Returns PNG + SVG urls (PNG becomes the brand logo). getCost:true previews the price.

Generate N distinct campaign angles (2 credits): title, hook, primaryText, cta. Returned inline (not persisted). getCost:true previews the price.

Free: plan a shot-by-shot arc for a video (cinematic b-roll or creator UGC). Returns ordered shots to feed generate_scene + assemble_export.

Free: search reference imagery (Pexels) or pin a reference into a project (action='pin' + url + projectId). Returns results, or the pinned image id (use as an i2i reference).

Assemble a final video (1 credit) from generated assets. templates: classic | ugc_demo | scene_reel | creator_reel. Returns the final mp4 url. (Blocking ffmpeg render, up to ~5 min.) getCost:true previews the price.

Free: the job-linked credit ledger. Every spend line carries its job_id (taskId) and engine; every refund line links back to the job it refunds, and failed-job spends show refunded_credits so nothing is a silent mystery. Use it to answer 'what did I pay for' and to verify a failed render actually refunded. limit up to 200.

Free: browse past completed generations across every type (image | scene | avatar | voiceover | video-job) with signed URLs and, per row, the exact CHAIN hint for using it as the input of the next generation (image id -> i2i refs, scene id -> upscale/lipsync/matte, voiceover url -> lipsync audio...). The library that closes the use-as-input loop. Filters: type, projectId, limit (max 100).

Free: delete one item from the library for good, by its typed ref (img_, scn_, avt_, vo_, vjob_ followed by the id, as show_generations or a generation returns it): the file in storage, then the library entry. The charge stays on the ledger. Cannot be undone. A job still running cannot be deleted (finish or fail it first). With a key bound to a project, only that project's items are reachable.

Free: preview the art-directed VIDEO prompt before spending anything - the scenes analog of images_director_preview. Runs the same brand director as generate_scene and returns the expanded scene script + the always-on casting/realism locks. Edit the text, then call generate_scene with { prompt: <edited>, preDirected: true } to use it VERBATIM (no second director pass). An editable-script gate before anything is spent.

Free: mechanical anti-slop lint over generated copy or a design pack. Pass text (ad copy/script/captions) OR a JSON design spec OR an array of specs (batch). Checks: em-dashes, decorative emoji, filler marketing verbs (elevate/seamless/unleash...), banned palettes (purple gradients, graphite+orange, near-black+neon), generic fonts (Inter/Roboto/Arial), stacked exclamations, and batch anti-convergence (two designs sharing palette+font+layout). Returns findings or a clean bill. Run it on every pack BEFORE showing it to the user.

Free: import an image by URL, a public http(s) URL the MCP fetches or a data:image/...;base64 URL for a file you hold locally, and store it in your account (png/jpg/webp/gif, 25 MB cap). This makes inputs origin-agnostic and is the foundation of 'recreate this reference' (grab a still off the web, then use it). Returns { path, url } and, with projectId, an imageId to pass straight into images_generate.referenceImageIds (referenceMode product or identity). The url feeds generate_scene/avatar_generate imageUrl. bucket: images (default) | products | avatars | brands.

Free: get a time-limited signed read URL for one of your storage objects (bucket + path, path must start with your user id).