MCP tools
Reference for 10 core Clipia MCP agent tools plus seven app-only helpers — image, video, speech, music, status, catalog, balance and prompt tools.
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 and generate_presentation are added only when their capabilities are enabled. Every generate call returns its cost in credits; get_balance reports the remaining balance.
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+ ready-made prompts (RU/EN) | query, limit (opt.) |
app_get_generation | App-only (hidden from the model): polls status from the interactive claude.ai card. Alias of get_generation | request_id, include_preview (opt.) |
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 requires 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 on the Clipia MCP page.
Clipia MCP
Connect Clipia to Claude Code, claude.ai, ChatGPT, Cursor, VS Code and Windsurf — 60+ image and video models right inside your agent's chat with a single API key.
TypeScript SDK
The official Clipia TypeScript SDK (npm clipia-ai) — install, initialize the client, submit a job and wait for the generation result.