MCP
Инструменты MCP
Параметры 10 базовых и 5 дополнительных инструментов Clipia MCP, модели по умолчанию, slug с косой чертой и семь служебных инструментов карточек.
По API-ключу Clipia MCP даёт AI-агенту 10 базовых инструментов. chat, generate_scenario, compose_video, generate_presentation и edit_presentation добавляются, когда включены соответствующие возможности. При входе через OAuth в claude.ai и ChatGPT набор может быть уже, например без get_balance. Ещё семь служебных инструментов обслуживают интерактивные карточки в приложениях и в контекст модели не попадают. Каждый вызов генерации возвращает стоимость в кредитах, get_balance показывает остаток.
Типичный сценарий
generate_image или generate_video ставит задачу. Если ответ ещё не финальный (статус IN_QUEUE или IN_PROGRESS), вызывайте wait_generation с полученным request_id, пока статус не станет COMPLETED, FAILED или CANCELED. Изображения часто приходят готовыми за один вызов, видео рендерится от одной до десяти минут.
Базовые инструменты
| Инструмент | Назначение | Параметры |
|---|---|---|
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.
Ограничения параметров
| Параметр | Инструмент | Значения |
|---|---|---|
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.
Модели по умолчанию
Если 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 с косой чертой
В 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, — см. «Каталог моделей».
Инструменты, зависящие от возможностей
| Инструмент | Назначение | Параметры | Когда доступен |
|---|---|---|---|
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_get_generation | Состояние одной генерации для живой карточки |
app_get_generations | Состояния нескольких карточек одним запросом |
app_get_rerun_options | Параметры для повторного запуска готовой генерации |
app_rerun_generation | Повтор генерации из карточки после явного действия пользователя |
app_get_compose_editor | Состояние редактора монтажа |
app_recompose_video | Пересборка смонтированного видео после явного изменения |
app_report_event | События показа карточки и открытия оригинала |
Параметр, которого модель не знает
generate_image, generate_video, generate_audio и generate_music отклоняют вызов до запуска генерации, если в input или среди аргументов верхнего уровня есть имя с опечаткой либо параметр, про который известно, что выбранная модель его не применит, — например seed или negative_prompt у модели, которая их не объявляет. Генерация не создаётся, кредиты не резервируются. Ошибка invalid_request называет лишние параметры и перечисляет те, что модель объявляет:
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 — см. «Постановка генерации».
Описания
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: после обрыва повтор с тем же ключом вернёт готовый ответ без нового списания. Стоимость считается по токенам ввода и вывода, а списывается в кредитах.
Подсказки по промптам
Для видеомоделей лучше работают английские промпты, для изображений подходит и русский. Не вписывайте экранный текст в видеопромпт — он рендерится с артефактами; подписи добавляйте на монтаже через subtitles. Для статичной камеры добавьте «static locked camera, no zoom, no pan».
Песочница
Ключ с префиксом clipia_test_ переводит инструменты в тестовый режим: generate_image и generate_video мгновенно возвращают заготовленный результат, кредиты не списываются. Это удобно для отладки опроса и разбора ответов в CI. Для настоящих генераций используйте ключ clipia_live_.
Адрес сервера и настройка клиентов — на странице Clipia MCP.
Clipia для AI-агентов
Подключите Clipia к Claude Code, claude.ai, ChatGPT, Cursor, VS Code, Codex и Gemini CLI — более 60 моделей фото и видео в чате агента по ключу или OAuth.
TypeScript SDK
Официальный TypeScript SDK Clipia (npm clipia-ai 1.5.0) — установка, очередь генераций, каталог и оценка цены, проверка вебхуков, ошибки и CLI clipia.