--- title: Use Clipia with AI agents description: Give AI agents video, image, speech, music and presentation tools through Clipia MCP, or automate image and video generation with the REST API. icon: Plug --- Clipia is an AI media generation platform that agents can operate directly across a catalog of 60+ image and video models. Through the remote MCP server at `https://mcp.clipia.ai/mcp`, an agent can generate video from text or a start image, create or edit images, produce speech and music, assemble multi-scene videos, create presentations, inspect available models, track jobs and return finished files to the conversation. For application-owned image and video workflows, call the REST API or an official SDK. Server address (Streamable HTTP): `https://mcp.clipia.ai/mcp`. Sign in with a Clipia API key or with your Clipia account over OAuth. A key can be sent as `Authorization: Bearer clipia_...` (recommended), `Authorization: Key ` or `X-Api-Key: `. ## MCP or REST API: which one? [#mcp-or-rest] | Use | Best when | What you get | | --- | --- | --- | | **Remote MCP server** | An AI agent should discover tools and decide which generation step to run | Streamable HTTP, tool schemas, OAuth or API-key auth, interactive result cards in supported clients | | **REST API + SDK** | Your backend, product or automation owns an image or video workflow | Image/video queue endpoints, webhooks, OpenAPI, and official TypeScript and Python SDKs | MCP and REST use the same Clipia account, credit balance and generation history where their capabilities overlap. There is no separate MCP markup. ## Tools available to AI agents [#tools] The full profile, available with an API key, contains 15 agent-callable tools: 10 core tools plus five that appear when their product capabilities are enabled. Over OAuth in claude.ai and ChatGPT the set can be narrower, for example without `get_balance`. The `tools/list` response is authoritative for your connection. ### 10 core tools - `generate_image` — generate or edit images from a prompt and optional references - `generate_video` — create video from text or a start image - `generate_audio` — convert text to speech - `generate_music` — create background music or a soundtrack - `wait_generation` — long-poll an asynchronous job until it finishes - `get_generation` — read status and finished file URLs without waiting - `list_models` — discover active models, capabilities and credit prices - `get_model` — inspect one model's input schema and price - `get_balance` — read the connected account's credit balance and recent usage - `search_templates` — find ready-to-use image and video prompts ### 5 capability-dependent tools - `chat` — call a text model - `generate_scenario` — turn a video brief into structured scenes and prompts - `compose_video` — combine generated scenes, narration, music and subtitles - `generate_presentation` — create an editable PPTX, PDF and slide previews - `edit_presentation` — revise an existing deck while reusing unchanged illustrations Seven app-only helpers drive live result, rerun and composition cards. They remain outside the model context and do not increase the AI agent's tool list. See [MCP tools](/en/docs/mcp/tools) for parameters and availability details. ## Ready-made prompts [#prompts] Besides tools, the server exposes four ready-made workflows through `prompts/list`. Claude Code shows them as slash commands; other clients list them in their prompt menu. A prompt inserts step-by-step instructions for the agent into the conversation; the generations themselves run through the regular tools and are paid in credits. | Prompt | What it does | Arguments | | --- | --- | --- | | `product_shot` | Turns one product photo into a marketplace set: several backgrounds plus a short rotation video | `image_url` (required), `product`, `variants` (default 4) | | `blog_covers` | Generates consistent cover images for a list of article headlines | `titles` (required, one per line), `style`, `aspect_ratio` (default `16:9`) | | `campaign_storyboard` | Turns a campaign brief into scene stills, animates the approved ones and adds a voiceover | `brief` (required), `scenes` (default 6), `voiceover` | | `animate_photo` | Turns a still photo into a short clip with a chosen camera move | `image_url` (required), `motion`, `duration` (default 5 seconds) | ## End-to-end video workflow [#video-workflow] An agent can complete a full video rather than stopping at a single generated clip: 1. Call `generate_scenario` to split a brief into scenes when scenario planning is enabled. 2. Call `generate_video` for each scene. Pass `image_url` when a start frame or visual reference should guide the shot. 3. Call `generate_audio` for narration and `generate_music` for the soundtrack when needed. 4. Call `compose_video` to assemble 2–20 completed scenes, optional voiceover, music and subtitles. 5. Call `wait_generation` until the final job is `COMPLETED`, then return `output.video.url`. For a single clip, start with `generate_video` and poll the returned `request_id`; the planning and composition tools are optional. ## Getting a key [#key] Create an API key in the [Developer Console](/en/developer). Keys prefixed `clipia_live_` are live (they charge credits); keys prefixed `clipia_test_` run in the sandbox: instant test results with no charge, handy for debugging agents and CI. A live key is shown only once at creation — it's the password to your credit balance. Keep it in an environment variable such as `CLIPIA_KEY` or in a secrets manager, and never commit it to a repository. ## Connect a client [#connect] In claude.ai the result is shown as an interactive card with live progress and media. In Claude Code an inline preview lands in the terminal. Clients without card support get links to the full-quality file. One command in the terminal and the Clipia tools are available in any session, including headless and CI. Pull the key from an environment variable rather than hard-coding it: ```bash claude mcp add --transport http clipia https://mcp.clipia.ai/mcp \ --header "Authorization: Bearer $CLIPIA_KEY" ``` Then ask Claude: "Generate an image of a neon city in Clipia" — the preview lands right in the terminal. claude.ai (web, desktop, mobile) connects via sign-in to your Clipia account (OAuth); no key required: 1. Open Settings → Connectors (in the new interface: Customize → Connectors). 2. Click "Add custom connector" and paste the URL `https://mcp.clipia.ai/mcp`. 3. Click Connect and sign in to your Clipia account. 4. In a new chat, ask for an image or a video — a live Clipia card with progress and an "Original" button appears in the message. Credits are charged to the connected Clipia account. The Claude Free plan allows one custom connector; on Team and Enterprise plans the organization owner adds it. ChatGPT adds third-party MCP servers as plugins, signing in to your Clipia account (OAuth); no key required: 1. Open the plugins page at `chatgpt.com/plugins`, click "+" → "Add custom MCP server". 2. Enter a name and a description; under Connection, enter the server URL `https://mcp.clipia.ai/mcp`. 3. Choose OAuth authentication, read the warning and confirm "I understand and want to continue", then click "Create as a plugin". 4. Review the discovered tools, install the plugin and sign in to your Clipia account. In a new chat, type `@`, pick Clipia and ask for generations in plain text. Whether you can add custom MCP servers depends on your ChatGPT account and workspace policies. If you don't have the plugins page, the earlier path applies: Settings → Apps & Connectors → Advanced settings → Developer mode, then Apps & Connectors → Create. Menu names vary between ChatGPT versions. Add the server to `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` in the project, then restart Cursor — the Clipia tools show up in Agent mode. Cursor substitutes the key from an environment variable through `${env:…}`: ```json { "mcpServers": { "clipia": { "url": "https://mcp.clipia.ai/mcp", "headers": { "Authorization": "Bearer ${env:CLIPIA_KEY}" } } } } ``` Create `.vscode/mcp.json` in your workspace (or via the "MCP: Add Server" command). On the first run VS Code prompts for the key and stores it securely; open Copilot Chat in Agent mode and the Clipia tools appear in the list: ```json { "servers": { "clipia": { "type": "http", "url": "https://mcp.clipia.ai/mcp", "headers": { "Authorization": "Bearer ${input:clipia_api_key}" } } }, "inputs": [ { "type": "promptString", "id": "clipia_api_key", "description": "Clipia API Key", "password": true } ] } ``` Add the server to `~/.codeium/windsurf/mcp_config.json` (the `serverUrl` field is a Windsurf quirk), then refresh the server list in Cascade → MCPs: ```json { "mcpServers": { "clipia": { "serverUrl": "https://mcp.clipia.ai/mcp", "headers": { "Authorization": "Bearer clipia_live_..." } } } } ``` The Windsurf documentation now points to the Devin site: on a newer build the config lives in `~/.config/devin/mcp_config.json` (per project: `.devin/mcp_config.json`), and the server address goes in a `url` field. Add a block to `~/.codex/config.toml` and export the key into your environment — Codex injects the `Authorization: Bearer` header from the `CLIPIA_API_KEY` variable automatically: ```toml [mcp_servers.clipia] url = "https://mcp.clipia.ai/mcp" bearer_token_env_var = "CLIPIA_API_KEY" ``` ```bash export CLIPIA_API_KEY="clipia_live_..." ``` One command (or an `httpUrl` block with headers in `~/.gemini/settings.json`); verify the connection with `gemini mcp list`: ```bash gemini mcp add --transport http clipia https://mcp.clipia.ai/mcp \ --header "Authorization: Bearer $CLIPIA_KEY" ``` OAuth sign-in (claude.ai, ChatGPT and other clients with a consent screen) stays valid for 180 days from the moment you click "Allow": after that the client asks you to sign in to Clipia and confirm access again. You can revoke access earlier in the [Developer Console](/en/developer), "Connected apps" tab — the app loses access to the account immediately. Changing your password in the settings pauses these connections until your next sign-in to your Clipia account, and resetting it through the email link revokes them. ## Jobs, cost and safe retries [#jobs] Image calls often finish in one request. Video, audio, music, composition and presentation jobs are asynchronous: 1. The generation tool returns a `request_id`, current status and the credit cost. 2. Call `wait_generation` repeatedly until the status is `COMPLETED`, `FAILED` or `CANCELED`. 3. On completion, read the media or document URLs from `output`. Use a stable `idempotency_key` only when retrying the same unchanged paid request after a transport or ambiguous failure. Use a new key after changing the prompt, files or settings: the same key with different input, including a different `num_images` or a switch between a single run and a batch, returns `idempotency_key_reuse`. A key is up to 255 characters and is accepted by `generate_image`, `generate_video`, `generate_audio`, `generate_music`, `generate_scenario` and `chat`. This prevents an agent loop from charging twice for the same operation. ## Sandbox [#sandbox] Keys prefixed `clipia_test_` return instant test results with no charge — useful for debugging response parsing, polling and pipelines. Live keys return the exact cost of each generation, and the `get_balance` tool reports the remaining credit balance. ## Agent workflow questions [#faq] In Claude Code, Cursor, VS Code, Codex and Gemini CLI — with an API key from the developer console in the `Authorization: Bearer clipia_...` header (`Authorization: Key` and `X-Api-Key` work too). claude.ai and ChatGPT sign in to your Clipia account over OAuth; no key is needed. `clipia_live_` keys charge credits, `clipia_test_` keys run in the sandbox with no charge. MCP and the REST API share one account and one balance. Generation tools spend the connected account's credits at the same prices as the website; there is no separate MCP markup. `list_models` and `get_model` show a model's reference price, the tool result shows the actual cost of the call, and `get_balance` shows what's left (over OAuth in claude.ai and ChatGPT this tool may be absent). Credits are reserved when a job starts and charged once the result is ready; a failed generation returns the reservation. Generation with a live key or over OAuth works only while the account has an active subscription on clipia.ai: without one the tool returns a refusal, even if the balance has credits. A `clipia_test_` key works without payment. `generate_image` waits up to 25 seconds and usually returns the finished image right away. Video, speech, music, composition and presentations return a `request_id` immediately: then call `wait_generation` (up to 30 seconds per call) or `get_generation` until the status is `COMPLETED`, `FAILED` or `CANCELED`. Video renders take one to ten minutes. `chat` and `generate_scenario` answer in a single call, and the server holds a call for up to two minutes: cap long `chat` answers with `max_tokens`. The generation job keeps running on the server, and the result stays available by `request_id` through `get_generation`. Repeating the same paid call with the same `idempotency_key` does not create a second generation: the key is kept for 24 hours, and identical calls within about 20 seconds are merged into one even without a key. `chat` and `generate_scenario` with the same key return the stored answer without a new charge. `generate_presentation` and `edit_presentation` have no such key, so repeating them is billed again. A job that has already started cannot be canceled. 120 requests per minute per API key and 600 across all of the account's keys; an OAuth connection gets 60 requests per minute. Above that the server returns `429` with a `Retry-After` header: wait for that time and repeat the call. Details are on the [Rate limits](/en/docs/api-reference/rate-limits) page. ## Machine-readable discovery [#discovery] Agents and crawlers can discover the same contract without parsing the marketing site: - [LLM product facts and tool inventory](https://clipia.ai/llms.txt) - [Developer documentation index](https://clipia.ai/en/docs/llms.txt) - [MCP server card](https://clipia.ai/.well-known/mcp/server-card.json) - [Agent skills index](https://clipia.ai/.well-known/agent-skills/index.json) - [OpenAPI 3.1 specification](https://clipia.ai/openapi/clipia-v1.json) - [Authentication guide](https://clipia.ai/auth.md) The server card is built from the current configuration and shows the full profile for an API key; `tools/list` returns the exact set for your connection. See the full [MCP tools](/en/docs/mcp/tools) reference or the [REST API overview](/en/docs/api-reference).