---
title: Инструменты MCP
description: Параметры 10 базовых и 5 дополнительных инструментов Clipia MCP, модели по умолчанию, slug с косой чертой и семь служебных инструментов карточек.
icon: Wrench
---

По API-ключу Clipia MCP даёт AI-агенту 10 базовых инструментов. `chat`, `generate_scenario`, `compose_video`, `generate_presentation` и `edit_presentation` добавляются, когда включены соответствующие возможности. При входе через OAuth в claude.ai и ChatGPT набор может быть уже, например без `get_balance`. Ещё семь служебных инструментов обслуживают интерактивные карточки в приложениях и в контекст модели не попадают. Каждый вызов генерации возвращает стоимость в кредитах, `get_balance` показывает остаток.

<Callout type="info" title="Типичный сценарий">
`generate_image` или `generate_video` ставит задачу. Если ответ ещё не финальный (статус `IN_QUEUE` или `IN_PROGRESS`), вызывайте `wait_generation` с полученным `request_id`, пока статус не станет `COMPLETED`, `FAILED` или `CANCELED`. Изображения часто приходят готовыми за один вызов, видео рендерится от одной до десяти минут.
</Callout>

## Базовые инструменты [#core]

| Инструмент | Назначение | Параметры |
| --- | --- | --- |
| `generate_image` | Изображение по тексту или редактирование по референсам. Обычно возвращает готовый результат за один вызов | `prompt`, `model`, `aspect_ratio`, `resolution`, `num_images`, `image_urls`, `negative_prompt`, `seed`, `input`, `include_preview`, `wait_seconds`, `idempotency_key` |
| `generate_video` | Видео по тексту или по стартовому кадру. Сразу возвращает `request_id` и стоимость | `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` | Озвучка текста выбранным голосом. После завершения — аудиофайл (mp3 или wav, зависит от модели) | `text`, `model`, `voice`, `language`, `stability`, `secondary_voice`, `similarity`, `previous_text`, `input`, `wait_seconds`, `idempotency_key` |
| `generate_music` | Фоновая музыка или саундтрек по описанию настроения, жанра и темпа, либо песня на ваш текст (`lyrics`) | `prompt`, `lyrics`, `style`, `instrumental`, `model`, `input`, `wait_seconds`, `idempotency_key` |
| `wait_generation` | Ждёт, пока задача не завершится, до 30 секунд за вызов | `request_id`, `wait_seconds`, `include_preview` |
| `get_generation` | Мгновенный статус и результат: превью и `original_url` в полном качестве | `request_id`, `include_preview` |
| `list_models` | Каталог моделей: slug, тип, возможности, цена в кредитах. Отдаётся страницами | `type`, `search`, `limit`, `offset` |
| `get_model` | Схема параметров (`input_schema`) и цена одной модели | `model`, `locale` |
| `get_balance` | Баланс кредитов, число вызовов API и расход за 30 дней | — |
| `search_templates` | Поиск по 3500+ отобранным промптам на русском и английском | `query`, `media_type`, `limit` |

Обязательные параметры: `prompt` у `generate_image` и `generate_music`; `text` у `generate_audio`; `request_id` у `wait_generation` и `get_generation`; `model` у `get_model`; `query` у `search_templates`.

### Ограничения параметров [#limits]

| Параметр | Инструмент | Значения |
| --- | --- | --- |
| `num_images` | `generate_image` | от 1 до 4, зависит от модели |
| `image_urls` | `generate_image` | до 10 публичных https-ссылок на референсы: одна — для правки, 2–10 — чтобы объединить людей, товары и стили в одном кадре; лимит задаёт модель |
| `image_url` | `generate_video` | одна https-ссылка на стартовый кадр; переключает модель по умолчанию на image-to-video. У lip-sync и моушн-контроля — фото персонажа |
| `end_image_url` | `generate_video` | одна https-ссылка на последний кадр; нужен `image_url`; работает на любой модели с поддержкой последнего кадра |
| `image_urls` | `generate_video` | до 9 https-ссылок на референсы (персонажи, товары, стиль) для мультиреференсных моделей и правки видео |
| `video_url` | `generate_video` | ведущий ролик для моушн-контроля (обязателен, 3–30 с; до 10 с при `character_orientation: "image"`) или исходник для моделей правки видео |
| `audio_url` | `generate_video` | запись речи (mp3 или wav) для lip-sync: длина ролика равна длине записи |
| `reference_video_urls` | `generate_video` | до 10 роликов-референсов; лимит объявляет модель в `get_model` (3 у Seedance 2.0, 10 у Seedance 2.5); секунды каждого ролика сервер измеряет сам и прибавляет к стоимости |
| `duration` | `generate_video` | длина клипа в секундах, 3–30, допустимые значения — в `get_model`; lip-sync и моушн-контроль берут длину из файла; с `reference_video_urls` — целое число секунд в диапазоне модели (4–15 с, у Seedance 2.5 — 4–30 с) |
| `prompt` | `generate_video` | обязателен для text-to-video; с медиа на входе (lip-sync, моушн-контроль) можно не передавать |
| `text` | `generate_audio` | 10–10 000 символов у модели по умолчанию; у других моделей границы свои — они в `text_limits` из `get_model` |
| `stability`, `similarity`, `secondary_voice`, `previous_text` | `generate_audio` | только у ElevenLabs v4: `stability` и `similarity` от 0 до 1, `previous_text` до 100 символов; другие речевые модели отклоняют вызов |
| `prompt` | `generate_music` | у модели по умолчанию до 3 000 символов; описание длиннее 1 000 символов требует `style` или `lyrics` |
| `lyrics`, `style` | `generate_music` | свой текст песни до 5 000 символов и стиль до 1 000 символов у модели по умолчанию; модель без своего режима отклоняет вызов |
| `instrumental` | `generate_music` | по умолчанию `true` — без вокала; с `lyrics` — `false` |
| `wait_seconds` | `generate_image`, `generate_audio`, `generate_music` | от 0 до 25, по умолчанию 20 |
| `wait_seconds` | `generate_video` | от 0 до 25, по умолчанию 0 |
| `wait_seconds` | `wait_generation` | от 1 до 30, по умолчанию 25 |
| `include_preview` | `generate_image`, `wait_generation`, `get_generation` | по умолчанию `true` |
| `type` | `list_models` | `text`, `image`, `video` или `audio` |
| `limit` | `list_models` | от 1 до 100, по умолчанию 50 |
| `offset` | `list_models` | от 0, по умолчанию 0 — сколько моделей пропустить |
| `locale` | `get_model` | `en` или `ru`, по умолчанию `en` — язык подписей и подсказок в `input_schema`; имена и значения параметров от языка не зависят |
| `idempotency_key` | `generate_image`, `generate_video`, `generate_audio`, `generate_music`, `generate_scenario`, `chat` | ключ безопасного повтора, до 255 символов, хранится 24 часа. Тот же ключ с другим входом, в том числе с другим `num_images` или при переходе между одиночным запуском и батчем, возвращает ошибку `idempotency_key_reuse`; пока первый вызов `chat` не завершён — `request_in_progress` |
| `media_type` | `search_templates` | `image` или `video` |
| `limit` | `search_templates` | от 1 до 20, по умолчанию 8 |

В `input` передаются дополнительные параметры конкретной модели из её `input_schema` (см. `get_model`). Они объединяются с полями верхнего уровня.

Типы аргументов `generate_image`, `generate_video`, `generate_audio`, `generate_music`, `chat`, `generate_scenario`, `wait_generation` и `get_generation` проверяются до запуска: значение неверного типа вернёт `invalid_request` с именем поля. Число можно передать и строкой: `duration: "5"` равно `5`, а нестрогая запись вроде `"5s"` вернёт `invalid_request`.

## Модели по умолчанию [#defaults]

Если `model` не указан, сервер выбирает модель сам. На ноябрь 2026 года в коде сервера это:

| Инструмент | Модель по умолчанию |
| --- | --- |
| `generate_image` | `nano-banana-2` |
| `generate_video` | `seedance-2-fast-t2v`, а с `image_url` — `seedance-2-fast-i2v` |
| `generate_audio` | `eleven-v4-turbo` |
| `generate_music` | `suno-v6` |
| `chat`, `generate_scenario` | `gemini-3.5-flash-lite` |

Умолчания задаются настройкой сервера и могут меняться без правки документации — если важен результат, передавайте `model` явно, выбрав его через `list_models` (для текста — с `type: "text"`). Фактическая модель и стоимость приходят в ответе инструмента. Модель по умолчанию для видео подобрана по качеству и не самая дешёвая: перед длинным или пакетным заданием сравните справочные цены в `list_models`.

## Slug с косой чертой [#mcp-only-models]

В `generate_image` и `generate_video` можно передать slug с косой чертой: `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`. Передавайте его дословно, без кодирования косой черты; актуальный список даёт `list_models`. Те же slug принимает и REST API, кроме запуска `midjourney/v8.1`, — см. [«Каталог моделей»](/ru/docs/api-reference/models#mcp-only).

## Инструменты, зависящие от возможностей [#conditional]

| Инструмент | Назначение | Параметры | Когда доступен |
| --- | --- | --- | --- |
| `chat` | Запрос к текстовой модели: ответ, расход токенов и стоимость в кредитах | `model`, `prompt` или `messages` (роли `system`, `user`, `assistant`), `max_tokens`, `temperature`, `response_format` (`text`, `json_object`, `json_schema`), `idempotency_key` (до 255 символов) | Включён AI Gateway |
| `generate_scenario` | Разбивает видеобриф на сцены с английскими промптами и длительностью плюс промпт саундтрека | `prompt` (обязательный), `duration_seconds` (10–120, по умолчанию 30), `scene_count` (2–12), `aspect_ratio` (`9:16`, `16:9`, `1:1`), `style`, `model`, `idempotency_key` (до 255 символов) | Включён AI Gateway |
| `compose_video` | Собирает 2–20 готовых видеосцен в один ролик с саундтреком, озвучкой и субтитрами | `scenes` (обязательный, 2–20), `audio_request_id` или `audio_url`, `voiceover_request_id` или `voiceover_url`, `subtitles` (до 100), `aspect_ratio` (`9:16`, `16:9`, `1:1`), `resolution` (`720p`, `1080p`), `normalize`, `idempotency_key` (8–128 символов) | Включён серверный монтаж |
| `generate_presentation` | Создаёт презентацию: редактируемый PPTX, PDF и PNG-превью слайдов | `title` (обязательный, до 120 символов), `slides` (обязательный, 3–20), `language` (`ru`, `en`), `theme` (`midnight` по умолчанию, `slate`, `noir`, `forest`, `ember`, `paper`, `ivory`, `azure`; `clipia-dark` и `clean-light` — только для презентаций о Clipia), `brand` (`name`, `website`) | Включены презентации |
| `edit_presentation` | Меняет готовую презентацию, переиспользуя неизменённые иллюстрации | `work_id` (по умолчанию последняя готовая), `title`, `language`, `theme`, `slides` (операции `set`, `insert`, `delete`, `move`), `regenerate_images`, `regenerate_all_images` | Включены презентации |

`request_id` задач монтажа начинается с `cmp_`, задач презентаций — с `prs_`. Ждать их можно тем же `wait_generation`. У `generate_presentation` и `edit_presentation` параметра `idempotency_key` нет: повтор вызова оплачивается заново.

## App-only helpers [#app-only]

Эти семь помощников обслуживают интерактивные карточки результата, перезапуска и монтажа в клиентах, которые умеют показывать такие карточки. Они скрыты от модели и не расходуют контекст агента. Вызывать их из своего кода не нужно.

| Инструмент | Назначение |
| --- | --- |
| `app_get_generation` | Состояние одной генерации для живой карточки |
| `app_get_generations` | Состояния нескольких карточек одним запросом |
| `app_get_rerun_options` | Параметры для повторного запуска готовой генерации |
| `app_rerun_generation` | Повтор генерации из карточки после явного действия пользователя |
| `app_get_compose_editor` | Состояние редактора монтажа |
| `app_recompose_video` | Пересборка смонтированного видео после явного изменения |
| `app_report_event` | События показа карточки и открытия оригинала |

## Параметр, которого модель не знает [#unsupported-parameters]

`generate_image`, `generate_video`, `generate_audio` и `generate_music` отклоняют вызов до запуска генерации, если в `input` или среди аргументов верхнего уровня есть имя с опечаткой либо параметр, про который известно, что выбранная модель его не применит, — например `seed` или `negative_prompt` у модели, которая их не объявляет. Генерация не создаётся, кредиты не резервируются. Ошибка `invalid_request` называет лишние параметры и перечисляет те, что модель объявляет:

```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.
```

Агенту достаточно убрать названные параметры или посмотреть их точные имена и значения в `get_model` и повторить вызов. Вызов с параметрами из `get_model` и вызов с умолчаниями проходят как раньше; тестовый ключ ведёт себя так же, как боевой. REST API в том же случае запрос принимает и перечисляет такие параметры в `warnings` — см. [«Постановка генерации»](/ru/docs/api-reference/submit#warnings).

## Описания [#details]

**generate_image** — text-to-image и image-to-image по референсам из `image_urls` (до 10 ссылок, лимит задаёт модель). `num_images` до 4 возвращает несколько вариантов одной плиткой. `seed` для повторяемости передавайте только моделям, которые его объявляют (см. `get_model`): модель по умолчанию его не объявляет и отклонит вызов. Одинаковые вызовы в течение примерно 20 секунд объединяются в одну генерацию; чтобы получить варианты отдельными вызовами, задавайте каждому свой `idempotency_key`.

**generate_video** — text-to-video и image-to-video; `image_url` переключает модель по умолчанию на I2V. Один вызов — один клип: для нескольких вариантов делайте отдельные вызовы с разным `idempotency_key` (у моделей, объявляющих `seed`, — например, у модели по умолчанию — подойдёт и разный `seed`). Параметры модели из `get_model` (`input_schema.parameters`) передаются в `input`; часть из них (например, `sound`, `mode`, `speed`, `audio`, `multi_shots`) меняет стоимость вызова. У моделей motion control длину и стоимость задаёт ведущий ролик из `video_url`: его длину измеряет сервер, `duration` на стоимость не влияет. С `reference_video_urls` к длительности результата прибавляются измеренные сервером секунды каждого референса.

**generate_audio** — озвучка текста. Допустимую длину текста для модели возвращает `get_model` в `text_limits`; слишком длинный текст отклоняется с ошибкой 400 до списания, его нужно разбить на части. После `COMPLETED` файл лежит в `output.audio.url`, его формат (mp3 или wav, зависит от модели) — в `output.audio.format`, а `request_id` можно передать как `voiceover_request_id` в `compose_video`.

**generate_music** — музыка по текстовому описанию. По умолчанию без вокала, чтобы её можно было подложить под озвучку; с `lyrics` получится песня на ваш текст. После завершения MP3 доступен в `output.audio.url`; музыка обычно требует опроса через `wait_generation`.

**wait_generation** — ждёт завершения задачи до `wait_seconds` секунд и возвращает текущее состояние. Вызывайте повторно, пока статус не станет финальным. Если при исполнении сервер отступил от запроса, в ответе `wait_generation` и `get_generation` есть массив `warnings` — например `audio_dropped`: звуковая дорожка не прошла проверку безопасности модели, ролик создан без звука, стоимость та же. Когда предупреждать не о чем, поля нет.

**get_generation** — снимок статуса и результата без ожидания: оптимизированное превью и `original_url` для скачивания в полном качестве.

**list_models** / **get_model** — каталог моделей с ценами и возможностями и подробная схема параметров одной модели. Текстовые модели тарифицируются за 1K входных и выходных токенов. `list_models` возвращает одну страницу каталога: `total` — сколько моделей подходит под фильтры, `truncated: true` — на странице не все. Сузьте выборку через `type` или `search` либо запросите следующую страницу, передав `offset` равным `next_offset` из ответа.

**get_balance** — остаток кредитов подключённого аккаунта, число вызовов API и расход за 30 дней. В некоторых клиентских приложениях этот инструмент не показывается.

**search_templates** — гибридный (полнотекстовый и семантический) поиск по библиотеке готовых промптов. У каждого результата есть готовый промпт и рекомендованная модель.

**chat** и **generate_scenario** отвечают в одном вызове, опроса у них нет. Сервер держит вызов до двух минут, поэтому длинный ответ `chat` ограничивайте через `max_tokens` и передавайте `idempotency_key`: после обрыва повтор с тем же ключом вернёт готовый ответ без нового списания. Стоимость считается по токенам ввода и вывода, а списывается в кредитах.

<Callout type="info" title="Подсказки по промптам">
Для видеомоделей лучше работают английские промпты, для изображений подходит и русский. Не вписывайте экранный текст в видеопромпт — он рендерится с артефактами; подписи добавляйте на монтаже через `subtitles`. Для статичной камеры добавьте «static locked camera, no zoom, no pan».
</Callout>

<Callout type="info" title="Песочница">
Ключ с префиксом `clipia_test_` переводит инструменты в тестовый режим: `generate_image` и `generate_video` мгновенно возвращают заготовленный результат, кредиты не списываются. Это удобно для отладки опроса и разбора ответов в CI. Для настоящих генераций используйте ключ `clipia_live_`.
</Callout>

Адрес сервера и настройка клиентов — на странице [Clipia MCP](/ru/docs/mcp).