MCP tools
Reference for 10 core and 5 capability-dependent Clipia MCP tools for AI agents, plus 7 app-only helpers for interactive result cards.
Clipia MCP always exposes 10 core tools to the AI agent plus seven app-only helpers that stay outside the model context. chat, generate_scenario, compose_video, generate_presentation and edit_presentation are added only when their capabilities are enabled. Every generate call returns its cost in credits; get_balance reports the remaining balance. Check the live MCP server card for the current runtime tool list.
Typical flow
generate_image / generate_video submits the job. If the response is non-terminal (status IN_QUEUE / IN_PROGRESS), call wait_generation with the request_id until status COMPLETED. Images often come back ready in a single call; video renders in 1–10 minutes.
Reference
| Tool | Purpose | Key parameters |
|---|---|---|
generate_image | Image from text or editing by reference. Usually returns a finished result in a single call, with a preview | prompt, model (opt.), image_url (opt., I2I), num_images (1–4), seed |
generate_video | Video from text or a start frame (image-to-video). Returns request_id and cost immediately | prompt, model (opt.), image_url (opt., switches to I2V), seed |
generate_audio | Text-to-speech with a selected voice and language. Returns an MP3 when complete | text, model (opt.), voice (opt.), language (opt.) |
generate_music | Background music or a soundtrack from a mood, genre and tempo description | prompt, model (opt.), instrumental (opt.) |
wait_generation | Long-poll until a terminal status (≤30s per call) | request_id |
get_generation | Instant status and result: webp preview + full-quality original_url | request_id, include_preview (opt.) |
list_models | Model catalog: slug, type, capabilities, price in credits | type (opt.), search (opt.) |
get_model | A model's parameters (input_schema) and price | model |
get_balance | Credit balance and 30-day usage for the key | — |
search_templates | Hybrid search over 3500+ prompts exposed to MCP from the wider template library (RU/EN) | query, limit (opt.) |
Capability-dependent agent tools
| Tool | Purpose | Availability |
|---|---|---|
chat | Chat with a text model and return reply text, usage and credit cost | LLM gateway enabled |
generate_scenario | Turn a video brief into structured scenes, English generation prompts and a soundtrack prompt | LLM gateway enabled |
compose_video | Join 2–20 finished video scenes with optional narration, music and subtitles | Server-side composition enabled |
generate_presentation | Create a new editable PPTX, PDF and PNG previews from a deck specification | Presentation generation enabled |
edit_presentation | Edit an existing deck and reuse illustrations that did not change | Presentation generation enabled |
App-only helpers
These seven helpers power interactive result, rerun and composition cards. They are hidden from the model and do not consume the AI agent's tool context.
| Tool | Purpose |
|---|---|
app_get_generation | Poll one generation from a live result card |
app_get_generations | Poll several generation cards in one request |
app_get_rerun_options | Load safe rerun settings for a finished generation |
app_rerun_generation | Rerun from an interactive card after explicit user action |
app_get_compose_editor | Load the composition editor state |
app_recompose_video | Rebuild a composed video after an explicit edit |
app_report_event | Report card lifecycle and interaction events |
Descriptions
generate_image — text-to-image and image-to-image by reference (image_url). The num_images parameter (1–4) returns several variants as a single tiled result. Set seed for reproducibility.
generate_video — text-to-video and image-to-video; passing image_url switches the default to an I2V model. Video has no batch — for multiple variants make separate calls with a different seed each.
generate_audio — text-to-speech with a selected voice and language. When status reaches COMPLETED, the MP3 is available at output.audio.url; its request_id can be used as voiceover_request_id in compose_video when that tool is enabled.
generate_music — creates background music or a soundtrack from a text description. It is instrumental by default; the completed MP3 is available at output.audio.url.
wait_generation — waits for an active generation to finish; call it between other work until the status becomes terminal.
get_generation — an instant snapshot of status and result with no waiting: an optimized webp preview plus an original_url for downloading full quality.
list_models / get_model — the model catalog with prices and capabilities, and the detailed parameter schema of a specific model.
get_balance — remaining credits and 30-day usage for the current key.
search_templates — hybrid (full-text + semantic) search over the library of ready-made prompts in Russian and English.
Additional tools
chat and generate_scenario are available when the LLM gateway is enabled; compose_video requires server-side composition; generate_presentation and edit_presentation require Presentation Agent. They are not part of the 10 core tools.
Prompt tips
Video models work best with English prompts (Russian is fine for images). Don't bake on-screen text into a video prompt — it renders with artifacts; overlay captions in post instead. For a static camera add "static locked camera, no zoom, no pan".
Sandbox
A key prefixed clipia_test_ puts every tool in test mode: generate_image / generate_video return a deterministic mock result instantly and charge no credits. It is handy for debugging polling and response parsing in CI; use a clipia_live_ key for real generations.
The server address and client setup are in Use Clipia with AI agents.
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) — install, initialize the client, submit a job and wait for the generation result.