---
title: MCP tools
description: 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.
icon: Wrench
---
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.
`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 [#core]
| 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 [#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 [#defaults]
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 [#mcp-only-models]
`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](/en/docs/api-reference/models#mcp-only).
## Capability-dependent tools [#conditional]
| 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 [#app-only]
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 [#unsupported-parameters]
`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:
```text
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](/en/docs/api-reference/submit#warnings).
## Details [#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.
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".
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](/en/docs/mcp) page.