MCP tools
Reference for the 9 Clipia MCP tools — image and video generation, wait, status, model catalog, balance and prompt-template search.
Clipia MCP exposes 8 tools for the AI agent plus one helper (app-only). The schemas are compact, so connecting Clipia barely touches the agent's context. 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 |
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.
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.
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 — 50+ 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.