---
name: calliope
description: Starting point for Calliope (calliopelabs.co) over its REST API or MCP server. Calliope generates finished short-form and long-form videos (script, narration, AI images and clips, captions, SFX, music, render) from a template or references plus a brief, an exact script or an uploaded narration; it also extracts reusable styles from videos, makes code-drawn Graphics videos, cuts long videos into Shorts, makes thumbnails, edits generated videos and reads or transcribes social posts. Covers connecting and authenticating, reading the private docs with read_skill, the job lifecycle and credits, and which doc to read for each task. Use when the user mentions Calliope or Calliope Labs, AI shorts, faceless or YouTube automation, template-based video generation, cloning the style of a video, character-consistent videos, clipping a podcast into Shorts, or automating a video content pipeline.
---

# Calliope

Calliope generates finished videos in the user's Calliope account: Shorts (up to 3 min) and long-form Videos (up to 60 min). A template (or direct references) fixes the look, voice and settings; a brief, an exact script or an uploaded narration fixes the content. Every video lands in the user's Generations on calliopelabs.co, with an editor, and stays editable through the API.

The same account also runs: style extraction into reusable templates, code-drawn Graphics videos, clipping (one long video into up to 10 vertical Shorts), thumbnails, editing tools for generated videos, media tools for social posts, and free writing guides (`free_tools`).

## Connect

### MCP
URL `https://www.calliopelabs.co/api/mcp` (Streamable HTTP). Keep `www`: the apex redirects and the client drops the `Authorization` header. Sign in with OAuth, or send `Authorization: Bearer <api-key>`. Each tool's description is its full usage doc. Claude, ChatGPT and Perplexity: add a custom connector with that URL and sign in. Steps for every client: https://www.calliopelabs.co/mcp.

```bash
# Claude Code: then run /mcp, pick calliope and Authenticate. Or with the API key:
claude mcp add --transport http calliope https://www.calliopelabs.co/api/mcp
claude mcp add --transport http calliope https://www.calliopelabs.co/api/mcp \
  --header "Authorization: Bearer $CALLIOPE_API_KEY"
```

```toml
# Codex ~/.codex/config.toml. OAuth instead: drop the last line and run `codex mcp login calliope`.
[mcp_servers.calliope]
url = "https://www.calliopelabs.co/api/mcp"
bearer_token_env_var = "CALLIOPE_API_KEY"
```

```json
// Cursor ~/.cursor/mcp.json: OAuth runs by itself. Key instead: "headers": { "Authorization": "Bearer clp_live_..." }
{ "mcpServers": { "calliope": { "url": "https://www.calliopelabs.co/api/mcp" } } }
```

```json5
// OpenClaw ~/.openclaw/openclaw.json (OpenClaw >= 2026.5.12), then `openclaw mcp login calliope`; check with `openclaw mcp probe calliope`.
// Key instead: headers: { Authorization: "Bearer ${CALLIOPE_API_KEY}" }
{ mcp: { servers: { calliope: { transport: "streamable-http", url: "https://www.calliopelabs.co/api/mcp", auth: "oauth" } } } }
```

```yaml
# Hermes ~/.hermes/config.yaml, then `hermes mcp login calliope`; check with `hermes mcp test calliope`. Tools appear as mcp__calliope__<tool>.
# Key instead: headers: { Authorization: "Bearer clp_live_..." }
mcp_servers:
  calliope:
    url: "https://www.calliopelabs.co/api/mcp"
    auth: oauth
```

### REST
- Base URL `https://www.calliopelabs.co/api/v1`, header `Authorization: Bearer <api-key>`, JSON bodies. Bodies and query fields are the MCP tool's arguments, in snake_case.
- API key: Dashboard → API (https://www.calliopelabs.co/tools/api). It starts with `clp_live_` and is shown once; creating a new key revokes the previous one.
- Spec: `GET /api/v1/openapi` (OpenAPI 3, API version 1.11.0); interactive docs `/api/v1/docs`; changelog at https://www.calliopelabs.co/tools/api.

### Plans and auth errors
- MCP connects on every plan. Free accounts run `free_tools`, plus `read_media`, `get_subtitles` and `get_media` with daily limits; every other tool returns 403 until they upgrade.
- REST needs a paid plan (Starter, Pro or Creator), except the free media calls (`POST /posts`, `POST /subtitles`, `GET /media`). Otherwise 403 `A paid plan is required`: upgrade at https://www.calliopelabs.co/pricing, then create the key.
- 401: key missing, invalid or revoked: create or regenerate it at Dashboard → API. 503 `Could not verify your API key`: retry; the key is fine.
- MCP tool calls have an abuse cap per plan: Starter 100/min, 5,000/day, 50,000/month; Pro x2; Creator x4. Over it: `Rate limit exceeded`: slow down.

## Read the docs
This doc and best practices are public. The other docs in the index, and the skills they cite, are private: read them with `read_skill` and the user's account. Over MCP each tool's skill is already its description; these docs add REST shapes and cross-tool rules.
- MCP: `read_skill {"path":"api-v1/create-video/SKILL.md"}`; `{}` returns the index of readable docs.
- REST:

```bash
curl -X POST https://www.calliopelabs.co/api/v1/tools \
  -H "Authorization: Bearer $CALLIOPE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"tool":"read_skill","path":"api-v1/create-video/SKILL.md"}'
# 200 {"content":"<markdown>"}. Without "path": the index. Unknown or ambiguous path: 400 with the error.
```

Read a doc cited inside another with the path written there. One read returns at most 30,000 characters; a longer doc ends with `[TRUNCATED: ... continue with offset N]`: read again with `"offset": N`.

## Every task: jobs, polling, credits
1. Everything that generates is asynchronous: the create call returns `202` and an id. `job_id`: videos, clips, Test Style, character sheet previews. `analysis_job_id`: template style analysis. `batch_id` plus the first clip's `job_id`: clipping. `agent_id`: reviews. `media_id`: media tools.
2. Poll until a final status. REST answers at once: poll `GET /api/v1/jobs/{job_id}` every 30-60 s. MCP status tools (`get_job`, `get_template_analysis`, `list_clipping`, `list_thumbnails`) already wait up to 20 s per call: call again right away. Typical: a Short about 10 min (up to 25), long-form 20-40 min, template analysis, Test Style and thumbnails 1-2 min, a clipping batch 10-20 min. For long jobs, tell the user the expected time and check again when they ask.
3. `status`: `Queued`, `Processing`, `Waiting`, `Completed`, `Failed`. `Waiting` = paused: after the narration with `auto_accept:false`, after the assets with `auto_render:false`, after the voiceover of a Graphics video with `calliope_agent:false`. Continue with `resume_job`; that Graphics video is built and rendered with the `workspace` tool instead. While Processing or Waiting, `phase` is `concept` (script), `audio` (narration), `assets` (images and clips) or `render`.
4. `Completed`: `video_url` opens the MP4 for 90 min (add `&download=1` to download); GET again for a fresh link instead of caching it. `?get_assets=true` adds `assets_urls` (signed, 10 min). `Failed`: `error` is the user-readable reason: relay it and fix its cause; never retry blindly.
5. `assets_expired_at` set: the files were removed after 12 months of account inactivity. `video_url` and `assets_urls` stay null and the video cannot be resumed, edited, rendered or saved as a template: create it again from the same project.

Credits:
- Calliope charges credits to the user's account. Quote only numbers the platform returns. Price a COST action first, tell the user, then run it in the same turn: MCP `estimate_generation_cost` before `create_video`; each other COST tool's skill gives its price call (usually `estimate:true`, then the same call with `confirm:true`; over REST `POST /jobs/{job_id}/tools` requires one of the two).
- `credit_cost` is the estimate at creation (a fixed price for Graphics); the final charge follows actual usage. `GET /jobs/{job_id}` returns the latest `credit_cost` and `credits_charged` `{total, generation, agent_sandbox, agent_gpu_sandbox, fast_render}`.
- `402`: not enough credits: send the user to Dashboard → billing to buy credits or upgrade.
- `429` `API_VIDEO_MONTHLY_LIMIT` or `API_VIDEO_DAILY_LIMIT`: the new-video allowance is used or reserved (see `api-v1/create-video/SKILL.md`). `409 Finish pending jobs first.`: wait for running jobs.
- `404`: unknown id, or one the account does not own.

## Index
Create:
- Required: read_skill `api-v1/create-video/SKILL.md` before creating a video.
- See `api-v1/content-instructions/SKILL.md` for writing the brief and planning a script or storyboard with `free_tools`.
- Required: read_skill `api-v1/templates/SKILL.md` before creating, copying or editing a template, or extracting a style from a video.
- Required: read_skill `api-v1/graphics/SKILL.md` before generating with a Graphics template (`workspace:true`) or using the `workspace` tool.

After a video exists:
- Required: read_skill `api-v1/editing/SKILL.md` before editing a generated video.
- See `api-v1/thumbnails/SKILL.md` for thumbnails of a completed video.

Other products:
- Required: read_skill `api-v1/clipping/SKILL.md` before cutting a long video into Shorts.
- See `creation-resources/read_media/SKILL.md` for what a social post says, without downloading it (free).
- See `creation-resources/get_subtitles/SKILL.md` for the subtitles a post already has (free).
- See `creation-resources/download_media/SKILL.md` for downloading a post's video, audio or images.
- See `creation-resources/transcribe_media/SKILL.md` for a timed transcript with speakers.

Reference:
- See `api-v1/endpoints/SKILL.md` for every REST endpoint and the MCP tool it backs.
- See `api-v1/best-practicies/SKILL.md` (public at https://www.calliopelabs.co/best-practices) for planning formats, narration sources, templates and Motion Graphics.
