API and MCP

Create a key under Settings → API keys. The full key is shown once; we store only a hash of it. Send it with every request:

Authorization: Bearer mc_live_...

A missing, unknown or revoked key answers 401. Revoke a key in Settings and it stops working right away. You can have up to 10 active keys.

• POST /api/v1/projects: create a project from a YouTube link.
• GET /api/v1/projects: your projects, newest first (up to 50).
• GET /api/v1/projects/{id}: status, options and clips of one project.
• GET /api/v1/clips/{id}/download?format=mp4|srt|vtt|thumb: redirects (302) to a download link that is valid for five minutes.

The machine-readable description is at /api/v1/openapi.json (OpenAPI 3.1).

curl -X POST https://clip.devmiro.cloud/api/v1/projects \
  -H "Authorization: Bearer $MIROCLIPS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "source_url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
    "clip_length": "auto",
    "max_clips": 6,
    "rights_confirmed": true
  }'

# 201 Created
{ "id": "3f1c2e4d-5a6b-4c7d-8e9f-0a1b2c3d4e5f" }

• source_url (required): a YouTube video link. Uploads are only possible in the app.
• clip_length (required): auto, 0-1, 1-3 or 3-5 minutes.
• rights_confirmed (required): must be true. You confirm that you own the video or have permission to use it, including the rights of people shown in it.
• focus_prompt: what the AI should look for, up to 300 characters.
• max_clips: 3, 6 or 12 (default 12).
• language: the spoken language as a two-letter code (en, de, es, fr, it, pt, nl, pl, tr, ja, ko), or leave it out to auto-detect.
• caption_style: bold, karaoke (default) or minimal.
• enhance_audio: true for neural speech noise removal (RNNoise) and loudness normalisation.
• aspect_ratio: 9:16 vertical (default), 1:1 square, 4:5 portrait or 16:9 landscape.
• clip_mode: how clips are picked. speech uses the transcript, visual scores sampled frames of the video (sports, gameplay, vlogs without much talking), auto (default) switches to visual when a video has little speech.
• apply_brand_kit: true renders the clips with your brand kit (logo, caption colors and font, intro and outro). Save a brand kit in the settings first; without one the request is refused with 409 no_brand_kit. The kit as it is at render time applies, and an intro or outro makes each clip file (and its duration) that much longer; the SRT and VTT files are shifted to match.
• layout: single is one crop that follows the person who is speaking, estimated from mouth movement. split stacks two people, each crop following its own face; it works with 9:16 only, and clips without two people on screen together get one crop. auto (default) splits when two people are on screen together for most of a 9:16 clip.
• resolution: 1080p (default) or 4k. 4K renders at twice the format size (2160x3840 for 9:16) only when the source is 4K and fits the size limit; otherwise the clip is rendered at 1080p. Each clip in GET /api/v1/projects/{id} reports its real output_width and output_height.

Projects created through the API work exactly like the ones from the app: they hold credits until the video's real length is known and count towards the limit of 10 new projects per hour.

curl https://clip.devmiro.cloud/api/v1/projects/3f1c2e4d-5a6b-4c7d-8e9f-0a1b2c3d4e5f \
  -H "Authorization: Bearer $MIROCLIPS_API_KEY"

{
  "id": "3f1c2e4d-5a6b-4c7d-8e9f-0a1b2c3d4e5f",
  "status": "done",
  "error": null,
  "clips": [
    { "id": "e3a1cc98-...", "title": "Why pricing pages fail", "score": 91,
      "start_s": 312.4, "end_s": 371.9, "status": "ready" }
  ],
  ...
}

status moves from queued to processing to done or failed; a failed project carries an error with a code and a plain-language message. Polling every 30 seconds is enough.

curl -L -o clip.mp4 \
  "https://clip.devmiro.cloud/api/v1/clips/e3a1cc98-e8ff-4040-b807-8d70dc91ca73/download?format=mp4" \
  -H "Authorization: Bearer $MIROCLIPS_API_KEY"

Clips with status ready can be downloaded. srt and vtt return the captions of the clip, thumb its 1280×720 title thumbnail (JPEG). Clips rendered before captions files or thumbnails existed answer 404 with captions_missing or thumbnail_missing until they are re-rendered in the app.

{ "error": { "code": "rate_limited", "message": "At most 10 projects per hour. Try again in 1200 seconds." } }

• 400 invalid_request: the body or a parameter is invalid; the message names the field.
• 401 unauthorized: missing, unknown or revoked key.
• 402 insufficient_credits: not enough credits for the video.
• 404 not_found: no such project or clip, or it belongs to another account.
• 409 no_brand_kit: apply_brand_kit is true but the account has no saved brand kit.
• 429 rate_limited: more than 10 new projects in the last hour; the Retry-After header says how many seconds to wait.
• 503 intake_paused: new projects are paused for a moment.
• 500 internal_error or 502 internal_error (a download could not be signed): something failed on our side; retry shortly.

The MiroClips MCP server lets agents such as Claude use the API as tools: create_project, list_projects, get_project and get_clip_download_url. It is a small Node.js program (Node 22 or newer) that runs on your machine over stdio and calls the API with your key.

It is not published to npm yet; during the beta we send the build on request at hello@clip.devmiro.cloud. Then add it to Claude Desktop (claude_desktop_config.json) or Claude Code (.mcp.json):

{
  "mcpServers": {
    "miroclips": {
      "command": "node",
      "args": ["/path/to/miroclips-mcp/dist/index.js"],
      "env": {
        "MIROCLIPS_API_KEY": "mc_live_...",
        "MIROCLIPS_API_URL": "https://clip.devmiro.cloud"
      }
    }
  }
}