---
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.
---

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.

<Callout type="info" title="Endpoint">
Server address (Streamable HTTP): `https://mcp.clipia.ai/mcp`. Supported auth schemes: `Authorization: Bearer clipia_...` (recommended), `Authorization: Key <key>`, `X-Api-Key: <key>`.
</Callout>

## Choose MCP or REST API

| 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

The full profile contains 15 agent-callable tools. The server card and `tools/list` response are authoritative for the current runtime: 10 core tools are always present, while five tools appear when their product capabilities are enabled.

### 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.

## End-to-end 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

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 mock responses with no charge, handy for debugging agents and CI.

<Callout type="warn" title="The key is a server-side secret">
  A live key is shown only once at creation — it is the equivalent of a password
  to your credit balance. Keep it in an environment variable or a secrets
  manager, and never commit it to a repository.
</Callout>

## Connect a client

<Callout type="info" title="Cards in chat">
  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. Other clients
  return links to the full-quality file.
</Callout>

<Tabs items={['Claude Code', 'claude.ai', 'ChatGPT', 'Cursor', 'VS Code', 'Windsurf']}>

<Tab value="Claude Code">

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_API_KEY"
```

Then ask Claude: "Generate an image of a neon city in Clipia" — the preview lands right in the terminal.

</Tab>

<Tab value="claude.ai">

claude.ai (web, desktop, mobile) connects via sign-in to your Clipia account (OAuth); no key required:

1. Open Settings → 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.

</Tab>

<Tab value="ChatGPT">

1. In ChatGPT (web): Settings → Apps & Connectors → Advanced settings → enable Developer mode (Plus, Pro, Business, Enterprise).
2. Apps & Connectors → Create. Name — Clipia, MCP Server URL `https://mcp.clipia.ai/mcp`.
3. Authentication — OAuth, check "I trust this application" and click Create.
4. Sign in to your Clipia account. In a chat, click "+" → More → Clipia and ask for generations in plain text.

</Tab>

<Tab value="Cursor">

Add the server to `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` in the project, then restart Cursor. Substitute the key from an environment variable in place of the placeholder:

```json
{
  "mcpServers": {
    "clipia": {
      "url": "https://mcp.clipia.ai/mcp",
      "headers": { "Authorization": "Bearer ${CLIPIA_API_KEY}" }
    }
  }
}
```

</Tab>

<Tab value="VS Code">

Create `.vscode/mcp.json` in your workspace (or via the "MCP: Add Server" command). 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 ${CLIPIA_API_KEY}" }
    }
  }
}
```

</Tab>

<Tab value="Windsurf">

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_API_KEY}" }
    }
  }
}
```

</Tab>

</Tabs>

## Jobs, cost and safe retries

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. This prevents an agent loop from charging twice for the same operation.

## Sandbox

Keys prefixed `clipia_test_` return instant mock results with no charge — perfect 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.

## Machine-readable 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 generated from the current runtime flags, so its tool list is the best source for what an agent can call at that moment. See the full [MCP tool reference](/en/docs/mcp/tools) or the [REST API overview](/en/docs/api-reference).