MCP
MCP tools
Parameters for the 10 core and 5 optional Clipia MCP tools, default models, slugs with a slash and the seven app-only helpers behind result cards.
With an API key, Clipia MCP gives an AI agent 10 core tools. chat, generate_scenario, compose_video, generate_presentation and edit_presentation are added when the matching product capabilities are enabled. Over OAuth in claude.ai and ChatGPT the set can be narrower, for example without get_balance. Seven more app-only helpers drive interactive cards and never enter the model's context. Every generation call returns its cost in credits, and get_balance shows what's left.
Typical flow
generate_image or generate_video starts a job. If the response isn't final yet (status IN_QUEUE or IN_PROGRESS), call wait_generation with the returned request_id until the status is COMPLETED, FAILED or CANCELED. Images often come back finished in one call; video takes one to ten minutes to render.
Core tools
| Tool | Purpose | Parameters |
|---|---|---|
generate_image | Image from text, or editing from reference images. Usually returns the finished result in one call | prompt, model, aspect_ratio, resolution, num_images, image_urls, negative_prompt, seed, input, include_preview, wait_seconds, idempotency_key |
generate_video | Video from text or from a start frame. Returns request_id and cost right away | prompt, model, duration, aspect_ratio, resolution, image_url, end_image_url, image_urls, video_url, audio_url, reference_video_urls, generate_audio, negative_prompt, seed, input, wait_seconds, idempotency_key |
generate_audio | Text-to-speech with a chosen voice. Returns an audio file when done (mp3 or wav, depending on the model) | text, model, voice, language, stability, secondary_voice, similarity, previous_text, input, wait_seconds, idempotency_key |
generate_music | Background music or a soundtrack from a description of mood, genre and tempo, or a song with your own words (lyrics) | prompt, lyrics, style, instrumental, model, input, wait_seconds, idempotency_key |
wait_generation | Waits for a job to finish, up to 30 seconds per call | request_id, wait_seconds, include_preview |
get_generation | Instant status and result: a preview plus a full-quality original_url | request_id, include_preview |
list_models | Model catalog: slug, type, capabilities, price in credits. Returned in pages | type, search, limit, offset |
get_model | One model's parameter schema (input_schema) and price | model, locale |
get_balance | Credit balance, API call count and 30-day spend | — |
search_templates | Search 3,500+ curated prompts in Russian and English | query, media_type, limit |
Required parameters: prompt for generate_image and generate_music; text for generate_audio; request_id for wait_generation and get_generation; model for get_model; query for search_templates.
Parameter limits
| Parameter | Tool | Values |
|---|---|---|
num_images | generate_image | 1 to 4, model-dependent |
image_urls | generate_image | up to 10 public https reference URLs: one for editing, 2–10 to merge people, products and styles into one image; the limit is set by the model |
image_url | generate_video | one https URL of the start frame; switches the default model to image-to-video. The character photo for lip-sync and motion-control models |
end_image_url | generate_video | one https URL of the last frame; requires image_url; works on every model that supports a last frame |
image_urls | generate_video | up to 9 https URLs of reference images (characters, products, style) for multi-reference and video-edit models |
video_url | generate_video | the driving clip for motion control (required there, 3–30 s; up to 10 s with character_orientation: "image") or the source clip for video-edit models |
audio_url | generate_video | the speech recording (mp3 or wav) for lip-sync: the clip length follows the audio |
reference_video_urls | generate_video | up to 10 reference clips; the limit is declared by the model in get_model (3 on Seedance 2.0, 10 on Seedance 2.5); the server measures each clip and adds its seconds to the cost |
duration | generate_video | clip length in seconds, 3–30, allowed values in get_model; lip-sync and motion control take the length from the file; with reference_video_urls it must be a whole number of seconds within the model range (4–15 s; 4–30 s on Seedance 2.5) |
prompt | generate_video | required for text-to-video; optional when the call carries media input (lip-sync, motion control) |
text | generate_audio | 10–10,000 characters on the default model; other models have their own limits — see text_limits in get_model |
stability, similarity, secondary_voice, previous_text | generate_audio | ElevenLabs v4 only: stability and similarity from 0 to 1, previous_text up to 100 characters; other speech models reject the call |
prompt | generate_music | up to 3,000 characters on the default model; a description longer than 1,000 characters also needs style or lyrics |
lyrics, style | generate_music | your own song text up to 5,000 characters and a style up to 1,000 characters on the default model; a model without a custom mode rejects the call |
instrumental | generate_music | default true — no vocals; false when lyrics is set |
wait_seconds | generate_image, generate_audio, generate_music | 0 to 25, default 20 |
wait_seconds | generate_video | 0 to 25, default 0 |
wait_seconds | wait_generation | 1 to 30, default 25 |
include_preview | generate_image, wait_generation, get_generation | default true |
type | list_models | text, image, video or audio |
limit | list_models | 1 to 100, default 50 |
offset | list_models | 0 or more, default 0 — how many models to skip |
locale | get_model | en or ru, default en — the language of labels and hints in input_schema; parameter names and values do not depend on it |
idempotency_key | generate_image, generate_video, generate_audio, generate_music, generate_scenario, chat | a safe-retry key, up to 255 characters, kept for 24 hours. The same key with different input, including another num_images or a switch between a single run and a batch, returns an idempotency_key_reuse error; while the first chat call is running, request_in_progress |
media_type | search_templates | image or video |
limit | search_templates | 1 to 20, default 8 |
input carries extra model-specific parameters from the model's input_schema (see get_model). They are merged with the top-level fields.
Argument types of generate_image, generate_video, generate_audio, generate_music, chat, generate_scenario, wait_generation and get_generation are checked before anything runs: a value of the wrong type returns invalid_request with the field name. A number may also be sent as a string: duration: "5" equals 5, while a loose form like "5s" returns invalid_request.
Default models
If you omit model, the server picks one. As of November 2026 the defaults in the server code are:
| Tool | Default model |
|---|---|
generate_image | nano-banana-2 |
generate_video | seedance-2-fast-t2v, or seedance-2-fast-i2v when image_url is set |
generate_audio | eleven-v4-turbo |
generate_music | suno-v6 |
chat, generate_scenario | gemini-3.5-flash-lite |
The defaults are server configuration and can change without a documentation update — if the result matters, pass model explicitly, picked from list_models (for text, with type: "text"). The model actually used and the cost come back in the tool's response. The default video model is tuned for quality and is not the cheapest one: compare reference prices in list_models before a long or batch job.
Slugs with a slash
generate_image and generate_video accept slugs that contain a slash: google/imagen4, google/imagen4-fast, google/imagen4-ultra, grok-imagine/text-to-image, grok-imagine/image-to-image, midjourney/v7, midjourney/v8.1, grok-imagine/text-to-video, grok-imagine/image-to-video, midjourney/v7-image-to-video. Pass them verbatim, without encoding the slash; list_models gives the current list. The REST API accepts the same slugs, except for running midjourney/v8.1 — see Model catalog.
Capability-dependent tools
| Tool | Purpose | Parameters | Available when |
|---|---|---|---|
chat | Calls a text model: reply, token usage and cost in credits | model, prompt or messages (roles system, user, assistant), max_tokens, temperature, response_format (text, json_object, json_schema), idempotency_key (up to 255 characters) | AI Gateway is enabled |
generate_scenario | Splits a video brief into scenes with English prompts and durations, plus a soundtrack prompt | prompt (required), duration_seconds (10–120, default 30), scene_count (2–12), aspect_ratio (9:16, 16:9, 1:1), style, model, idempotency_key (up to 255 characters) | AI Gateway is enabled |
compose_video | Stitches 2–20 finished video scenes into one clip with a soundtrack, voiceover and subtitles | scenes (required, 2–20), audio_request_id or audio_url, voiceover_request_id or voiceover_url, subtitles (up to 100), aspect_ratio (9:16, 16:9, 1:1), resolution (720p, 1080p), normalize, idempotency_key (8–128 characters) | Server-side composition is enabled |
generate_presentation | Creates a deck: editable PPTX, PDF and PNG slide previews | title (required, up to 120 characters), slides (required, 3–20), language (ru, en), theme (midnight by default, slate, noir, forest, ember, paper, ivory, azure; clipia-dark and clean-light only for decks about Clipia), brand (name, website) | Presentations are enabled |
edit_presentation | Changes an existing deck, reusing unchanged illustrations | work_id (defaults to the latest finished deck), title, language, theme, slides (operations set, insert, delete, move), regenerate_images, regenerate_all_images | Presentations are enabled |
Composition jobs have a request_id starting with cmp_, presentation jobs with prs_. Wait for them with the same wait_generation. generate_presentation and edit_presentation have no idempotency_key parameter: repeating a call is billed again.
App-only helpers
These seven helpers drive interactive result, rerun and composition cards in clients that can render them. They are hidden from the model and don't use the agent's context. You don't need to call them from your own code.
| Tool | Purpose |
|---|---|
app_get_generation | State of one generation for a live card |
app_get_generations | State of several cards in one request |
app_get_rerun_options | Options for rerunning a finished generation |
app_rerun_generation | Reruns a generation from a card after an explicit user action |
app_get_compose_editor | State of the composition editor |
app_recompose_video | Rebuilds a composed video after an explicit change |
app_report_event | Card render and original-opened events |
A parameter the model does not know
generate_image, generate_video, generate_audio and generate_music reject a call before the generation starts when input or the top-level arguments contain a misspelled name, or a parameter the chosen model is known not to apply — for example seed or negative_prompt on a model that does not declare them. No generation is created and no credits are reserved. The invalid_request error names the rejected parameters and lists the ones the model declares:
Unsupported parameters for model "nano-banana-2": negative_prompt, seed. Parameters declared by this model: aspect_ratio, prompt, resolution. Call get_model with model "nano-banana-2" for types and allowed values, then retry without the unsupported parameters. The generation was not started.The agent only has to drop the named parameters, or look up their exact names and values in get_model, and retry. Calls that use parameters from get_model, and calls with defaults, work as before; a test key behaves the same as a live one. In the same situation the REST API accepts the request and lists such parameters in warnings — see Submit a generation.
Details
generate_image — text-to-image and image-to-image from the references in image_urls (up to 10 URLs; the limit is set by the model). num_images up to 4 returns several variants as a single tile. Pass seed for repeatability only to models that declare it (see get_model): the default model does not declare it and rejects the call. Identical calls within about 20 seconds are merged into one generation; to get variants from separate calls, give each its own idempotency_key.
generate_video — text-to-video and image-to-video; image_url switches the default model to I2V. One call renders one clip: for several variants, make separate calls with a different idempotency_key each (on models that declare seed, such as the default one, a different seed also works). Model parameters from get_model (input_schema.parameters) go into input; some of them (for example sound, mode, speed, audio, multi_shots) change the cost of the call. On motion-control models the driving video in video_url sets both the clip length and the cost: the server measures it, and duration has no effect on the cost. With reference_video_urls, the server-measured seconds of each reference clip are added to the output duration.
generate_audio — text-to-speech. get_model returns the model's allowed text length in text_limits; longer text is rejected with a 400 before anything is charged, so split it into parts. After COMPLETED the file is at output.audio.url, its format (mp3 or wav, depending on the model) is in output.audio.format, and the request_id can be passed as voiceover_request_id to compose_video.
generate_music — music from a text description. No vocals by default, so it sits well under a voiceover; pass lyrics to get a song with your own words. When done, the MP3 is at output.audio.url; music usually needs polling with wait_generation.
wait_generation — waits up to wait_seconds for the job to finish and returns its current state. Call it again until the status is final. If the server had to deviate from the request while running it, the wait_generation and get_generation responses carry a warnings array — for example audio_dropped: the audio track did not pass the model's safety check, so the video has no sound and the cost is unchanged. The field is omitted when there is nothing to report.
get_generation — a status and result snapshot without waiting: an optimized preview and an original_url for the full-quality download.
list_models / get_model — the model catalog with prices and capabilities, and the detailed parameter schema of one model. Text models are priced per 1K input and output tokens. list_models returns one page of the catalog: total is the number of models matching the filters, and truncated: true means the page does not hold all of them. Narrow the list with type or search, or request the next page by passing offset equal to next_offset from the response.
get_balance — the connected account's credit balance, API call count and 30-day spend. Some client apps don't show this tool.
search_templates — hybrid (full-text plus semantic) search over the library of ready-made prompts. Each result has a ready prompt and a recommended model.
chat and generate_scenario answer in a single call, with no polling. The server holds a call for up to two minutes, so cap long chat answers with max_tokens and pass an idempotency_key: after a dropped connection, a retry with the same key returns the finished answer without a new charge. The cost is based on input and output tokens and charged in credits.
Prompting tips
Video models work best with English prompts; for images, Russian works too. Don't put on-screen text into a video prompt — it renders with artifacts; add captions at composition time with subtitles. For a static camera, add "static locked camera, no zoom, no pan".
Sandbox
A key prefixed clipia_test_ switches the tools to test mode: generate_image and generate_video return a canned result instantly and no credits are charged. That's handy for debugging polling and response parsing in CI. Use a clipia_live_ key for real generations.
Server address and client setup are on the Clipia MCP page.
Use Clipia with AI agents
Give AI agents video, image, speech, music and presentation tools through Clipia MCP, or automate image and video generation with the REST API.
TypeScript SDK
The official Clipia TypeScript SDK (npm clipia-ai 1.5.0) — install, generation queue, catalog and price estimates, webhook checks, errors and the clipia CLI.