This is the full developer documentation for Clipbeat # Clipbeat developer docs > Turn a song into a music video from your code or your AI agent, with the Clipbeat REST API or the remote MCP server. Clipbeat turns a song into a music video. You send a link to the audio, Clipbeat reads the lyrics, plans the scenes, casts an original AI singer and renders a video that is cut to the beat and lip-synced to the vocal. The same engine that runs [Clipbeat Studio](https://studio.clipbeat.app) is available to developers in two ways: REST API Plain HTTPS and JSON at `https://api.clipbeat.app/v1`. Import a song, start a video, poll its status, download the file. Described by an [OpenAPI 3.1 schema](https://api.clipbeat.app/v1/openapi.json). MCP server A remote Model Context Protocol server at `https://api.clipbeat.app/mcp` (Streamable HTTP). Five tools that let an AI assistant make a music video for its user. ## Who it is for [Section titled “Who it is for”](#who-it-is-for) * **Developers** who want to add music videos to an app, a distribution tool or a workflow (n8n automations, internal tools, release scripts). * **AI agents and assistants** that make a video when a musician asks for one, without the musician leaving the chat. * **Musicians with a technical setup** who want to script their own releases. ## How it works [Section titled “How it works”](#how-it-works) ```text your song link ──▶ POST /v1/songs ──▶ song "ready" ──▶ POST /v1/videos ──▶ poll GET /v1/videos/{id} ──▶ result.video_url (rights_attestation) (lyrics read) (credits reserved) (queued, running, completed) ``` 1. **Import a song** from a direct audio link or a Google Drive or Dropbox share link. You confirm that you own the song or have the rights to use it. 2. **Start a video** in one of four tiers: `preview` (a short lip-synced chorus clip) or a full video in `standard`, `plus` or `premium`. 3. **Poll** until the video is `completed`, then download it from `result.video_url`. Payment comes from the account’s Clipbeat credit balance, at the same prices as Clipbeat Studio. When the balance is too low the API answers `402` with a `topup_url` for the account owner. Card details never go through the API. ## Start here [Section titled “Start here”](#start-here) [Quickstart](/quickstart/)Your first video in five minutes with curl, JavaScript or Python. [Authentication](/authentication/)Create, store and revoke API keys. [Connect an AI client over MCP](/mcp/clients/)Claude, Cursor, VS Code, ChatGPT, n8n and any Streamable HTTP client. [API reference](/api/reference/)Every endpoint, parameter and response, generated from the OpenAPI schema. ## Good to know [Section titled “Good to know”](#good-to-know) * **Base URL:** `https://api.clipbeat.app` (REST under `/v1`, MCP at `/mcp`). * **Auth:** `Authorization: Bearer cb_live_...` personal API key, created in Clipbeat Studio settings. * **Format:** JSON in, JSON out. Field names are `snake_case`, ids are UUIDs, timestamps are ISO 8601 in UTC. * **Long running work:** videos take minutes, not seconds. Start, then poll every 30 to 60 seconds. * **Original AI characters only:** the lead is always an AI character. See the [content policy](/content-policy/). * **For language models:** this site publishes [/llms.txt](/llms.txt) and [/llms-full.txt](/llms-full.txt), and every page is available as Markdown (use **View as Markdown** at the top of each page). # Quickstart > Make your first Clipbeat music video through the API in five minutes, with curl, JavaScript or Python. This guide takes you from zero to a finished preview video: get a key, check the price, import a song, start a preview and poll until the video is ready. Every step has a `curl`, JavaScript (`fetch`, Node 18 or newer) and Python (`requests`) version. Videos cost credits Steps 1 to 3 are free. Step 4 starts a paid video and reserves its price from the account’s credit balance. Read [Pricing & credits](/pricing/) first. ## Before you start [Section titled “Before you start”](#before-you-start) * A Clipbeat account at [studio.clipbeat.app](https://studio.clipbeat.app) with credits. The account makes its first purchase in Studio before previews can be made through the API. * A song you own or have the rights to use, reachable as a **direct audio link** (`.mp3`, `.m4a`, `.wav`) or a **Google Drive** or **Dropbox** share link. The song must be at least 20 seconds long. 1. ### Create an API key [Section titled “Create an API key”](#create-an-api-key) In [Clipbeat Studio](https://studio.clipbeat.app), open **Settings**, go to the **Developers** section and choose **Create key** under **API keys**. Copy the key right away: it starts with `cb_live_` and is shown only once. Put it in an environment variable so it never ends up in your code: ```bash export CLIPBEAT_API_KEY="cb_live_..." ``` More in [Authentication](/authentication/). 2. ### Check the balance and prices [Section titled “Check the balance and prices”](#check-the-balance-and-prices) * curl ```bash curl -s https://api.clipbeat.app/v1/balance \ -H "Authorization: Bearer $CLIPBEAT_API_KEY" curl -s https://api.clipbeat.app/v1/pricing \ -H "Authorization: Bearer $CLIPBEAT_API_KEY" ``` * JavaScript ```js const API = 'https://api.clipbeat.app/v1'; const headers = { Authorization: `Bearer ${process.env.CLIPBEAT_API_KEY}` }; const balance = await fetch(`${API}/balance`, { headers }).then((r) => r.json()); const pricing = await fetch(`${API}/pricing`, { headers }).then((r) => r.json()); console.log(balance.usd, pricing.tiers.map((t) => `${t.tier}: $${t.usd}`)); ``` * Python ```python import os import requests API = "https://api.clipbeat.app/v1" headers = {"Authorization": f"Bearer {os.environ['CLIPBEAT_API_KEY']}"} balance = requests.get(f"{API}/balance", headers=headers, timeout=30).json() pricing = requests.get(f"{API}/pricing", headers=headers, timeout=30).json() print(balance["usd"], [(t["tier"], t["usd"]) for t in pricing["tiers"]]) ``` The balance response looks like this: ```json { "credits": 400, "usd": 20, "credits_per_usd": 20, "topup_url": "https://studio.clipbeat.app/credits" } ``` 3. ### Import the song [Section titled “Import the song”](#import-the-song) Send the link and confirm your rights. `rights_attestation` must be `true` and `rights_version` must be the current version, `2026-11-21` (see [Rights declaration](/concepts/rights/)). * curl ```bash curl -s https://api.clipbeat.app/v1/songs \ -H "Authorization: Bearer $CLIPBEAT_API_KEY" \ -H "Content-Type: application/json" \ -d '{"url":"https://example.com/my-song.mp3","rights_attestation":true,"rights_version":"2026-11-21"}' ``` * JavaScript ```js const API = 'https://api.clipbeat.app/v1'; const headers = { Authorization: `Bearer ${process.env.CLIPBEAT_API_KEY}`, 'Content-Type': 'application/json' }; const song = await fetch(`${API}/songs`, { method: 'POST', headers, body: JSON.stringify({ url: 'https://example.com/my-song.mp3', rights_attestation: true, rights_version: '2026-11-21' }), }).then((r) => r.json()); console.log(song.id, song.status); ``` * Python ```python import os import requests API = "https://api.clipbeat.app/v1" headers = {"Authorization": f"Bearer {os.environ['CLIPBEAT_API_KEY']}"} song = requests.post( f"{API}/songs", headers=headers, json={"url": "https://example.com/my-song.mp3", "rights_attestation": True, "rights_version": "2026-11-21"}, timeout=120, ).json() print(song["id"], song["status"]) ``` The response is the [song object](/concepts/songs/). `201` means a new import, `200` means this account already imported the same audio and you get the existing song back. ```json { "id": "8c5d2f9e-2a51-4f0e-9a43-1f4f3b0d6a21", "title": "My Song", "duration_sec": 184.3, "status": "processing", "lyrics_status": "processing", "created_at": "2026-11-22T09:14:03.000Z" } ``` Lyrics are read in the background. Poll `GET /v1/songs/{id}` until `status` is `ready` (usually under a minute). 4. ### Start a preview [Section titled “Start a preview”](#start-a-preview) A preview is a short lip-synced clip of the chorus with an original AI singer. `style` and `character` are optional and describe the world of the video and the lead. * curl ```bash curl -s https://api.clipbeat.app/v1/videos \ -H "Authorization: Bearer $CLIPBEAT_API_KEY" \ -H "Content-Type: application/json" \ -d '{"song_id":"SONG_ID","tier":"preview","aspect":"9:16","style":"neon-lit rooftop at night, light rain"}' ``` * JavaScript ```js const API = 'https://api.clipbeat.app/v1'; const headers = { Authorization: `Bearer ${process.env.CLIPBEAT_API_KEY}`, 'Content-Type': 'application/json' }; const res = await fetch(`${API}/videos`, { method: 'POST', headers, body: JSON.stringify({ song_id: 'SONG_ID', tier: 'preview', aspect: '9:16', style: 'neon-lit rooftop at night, light rain' }), }); const video = await res.json(); if (res.status === 402) console.log('Add credits:', video.topup_url); else console.log(video.id, video.status); ``` * Python ```python import os import requests API = "https://api.clipbeat.app/v1" headers = {"Authorization": f"Bearer {os.environ['CLIPBEAT_API_KEY']}"} res = requests.post( f"{API}/videos", headers=headers, json={"song_id": "SONG_ID", "tier": "preview", "aspect": "9:16", "style": "neon-lit rooftop at night, light rain"}, timeout=60, ) video = res.json() if res.status_code == 402: print("Add credits:", video["topup_url"]) else: print(video["id"], video["status"]) ``` A started video returns `202 Accepted` with the [video object](/concepts/video-jobs/) in status `queued`. 5. ### Poll until it is ready [Section titled “Poll until it is ready”](#poll-until-it-is-ready) Check every 30 to 60 seconds. When `status` is `completed`, `result.video_url` is a download link that stays valid for `result.expires_in_sec` seconds (24 hours by default). You can always get a fresh link by calling the endpoint again. * curl ```bash curl -s https://api.clipbeat.app/v1/videos/VIDEO_ID \ -H "Authorization: Bearer $CLIPBEAT_API_KEY" ``` * JavaScript ```js const API = 'https://api.clipbeat.app/v1'; const headers = { Authorization: `Bearer ${process.env.CLIPBEAT_API_KEY}` }; const sleep = (ms) => new Promise((r) => setTimeout(r, ms)); let video; do { await sleep(45_000); video = await fetch(`${API}/videos/VIDEO_ID`, { headers }).then((r) => r.json()); console.log(video.status, video.progress?.percent ?? 0, '%'); } while (video.status === 'queued' || video.status === 'running'); console.log(video.result?.video_url ?? video.error); ``` * Python ```python import os import time import requests API = "https://api.clipbeat.app/v1" headers = {"Authorization": f"Bearer {os.environ['CLIPBEAT_API_KEY']}"} while True: time.sleep(45) video = requests.get(f"{API}/videos/VIDEO_ID", headers=headers, timeout=30).json() print(video["status"], (video.get("progress") or {}).get("percent", 0), "%") if video["status"] not in ("queued", "running"): break print((video.get("result") or {}).get("video_url") or video.get("error")) ``` ```json { "id": "f1e2d3c4-b5a6-4789-8abc-def012345678", "status": "completed", "tier": "preview", "title": "My Song", "aspect": "9:16", "created_at": "2026-11-22T09:16:40.000Z", "progress": { "stage": "done", "done": 3, "total": 3, "percent": 100 }, "cost": { "credits_reserved": 100, "credits_charged": 100, "credits_refunded": 0, "usd": 5 }, "result": { "video_url": "https://...", "poster_url": "https://...", "expires_in_sec": 86400 }, "studio_url": "https://studio.clipbeat.app/" } ``` ## Next steps [Section titled “Next steps”](#next-steps) * Make the full video: start a new video with `tier` set to `standard`, `plus` or `premium`. Prices depend on song length; read them with `GET /v1/pricing?song_id=...`. * Handle every response code your integration can meet: [Errors](/errors/). * Give an AI assistant the same powers: [Connect over MCP](/mcp/clients/). * See every field: [API reference](/api/reference/). # Authentication > Create, use, store and revoke Clipbeat API keys, and the scopes each key carries. The REST API and the MCP server authenticate with a **personal API key**. A key acts as the Clipbeat account that created it: it reads that account’s songs and videos and spends that account’s credits. Tip MCP clients will also be able to connect with a one click sign-in (OAuth) instead of a key. That is **available soon**; see [MCP authentication](/mcp/authentication/). The REST API keeps using API keys. ## Create a key [Section titled “Create a key”](#create-a-key) 1. Sign in to [Clipbeat Studio](https://studio.clipbeat.app). 2. Open **Settings** and go to the **Developers** section. 3. Under **API keys**, choose **Create key** and give it a name you will recognize later, for example `n8n production` or `Agent on my laptop` (up to 60 characters). 4. Copy the key. It is shown **only once**. Keys look like this: ```text cb_live_3q2Xr8... (cb_live_ followed by 43 random characters) ``` An account can have up to **5 active keys** at a time. Revoke one to create another. ## Use a key [Section titled “Use a key”](#use-a-key) Send the key in the `Authorization` header with the `Bearer` scheme on every request: ```bash curl -s https://api.clipbeat.app/v1/balance \ -H "Authorization: Bearer $CLIPBEAT_API_KEY" ``` The same header works for the MCP server at `https://api.clipbeat.app/mcp`. All traffic is HTTPS only. If the key is missing, malformed, revoked, or belongs to a deleted account, the API answers `401`: ```http HTTP/1.1 401 Unauthorized WWW-Authenticate: Bearer realm="clipbeat" Content-Type: application/json { "error": "unauthorized", "message": "Send a Clipbeat API key: Authorization: Bearer cb_live_... (create one in Clipbeat Studio settings)." } ``` `GET /v1/openapi.json` is the only endpoint that works without a key. ## Scopes [Section titled “Scopes”](#scopes) Every key carries four scopes today. Each endpoint and MCP tool checks one of them; a key without the scope gets `403 insufficient_scope`. | Scope | REST endpoints | MCP tools | | -------------- | ------------------------------------------------------------- | -------------------------------------------- | | `songs:write` | `POST /v1/songs` | `create_video_from_song_url` with `song_url` | | `videos:write` | `POST /v1/videos` | `create_video_from_song_url` | | `videos:read` | `GET /v1/songs/{id}`, `GET /v1/videos`, `GET /v1/videos/{id}` | `get_video_status`, `list_my_videos` | | `account:read` | `GET /v1/pricing`, `GET /v1/balance` | `get_pricing`, `get_balance` | ## Store keys safely [Section titled “Store keys safely”](#store-keys-safely) A key can spend the account’s credits, so treat it like a password. * Keep it in an environment variable or a secret manager, never in source code or a public repository. * Do not put it in a browser, a mobile app or any other client that end users can inspect. Call Clipbeat from your server. * Use one key per integration or machine. If one leaks you revoke only that one. * Clipbeat stores only a hash of the key and its first characters (shown in Studio as the key prefix), so a lost key cannot be shown again. Create a new one. ## See when a key was used [Section titled “See when a key was used”](#see-when-a-key-was-used) The **API keys** list in Studio shows each key’s name, prefix, creation date and when it was last used. Last used is updated at most once a minute. ## Revoke a key [Section titled “Revoke a key”](#revoke-a-key) In **Settings**, **Developers**, **API keys**, choose **Revoke** next to the key and confirm. Revocation is immediate: the next request with that key gets `401`. Revoked keys cannot be restored. If you think a key has leaked, revoke it first, then create a new one and write to [hello@clipbeat.app](mailto:hello@clipbeat.app?subject=API%20key%20leak) if you see spending you do not recognize. # REST API overview > Base URL, request and response format, versioning and the full list of Clipbeat REST endpoints. The Clipbeat REST API is a small JSON over HTTPS API. It is described by an OpenAPI 3.1 document that tools such as n8n, Postman, Insomnia, ChatGPT actions and code generators can import: ```text https://api.clipbeat.app/v1/openapi.json ``` The [API reference](/api/reference/) on this site is generated from that document at every build. ## Base URL [Section titled “Base URL”](#base-url) ```text https://api.clipbeat.app ``` All endpoints are under `/v1`. HTTPS only. ## Endpoints [Section titled “Endpoints”](#endpoints) | Method | Path | Scope | What it does | | ------ | ------------------ | -------------- | --------------------------------------------------------------- | | `POST` | `/v1/songs` | `songs:write` | Import a song from a link. | | `GET` | `/v1/songs/{id}` | `videos:read` | Song status. Wait for `ready` before starting a video. | | `POST` | `/v1/videos` | `videos:write` | Start a video. Credits are reserved. | | `GET` | `/v1/videos/{id}` | `videos:read` | Status, progress, cost and the download link when done. | | `GET` | `/v1/videos` | `videos:read` | The account’s latest videos (`limit` 1 to 50, default 20). | | `GET` | `/v1/pricing` | `account:read` | Price per tier. Add `song_id` for the price of a specific song. | | `GET` | `/v1/balance` | `account:read` | Credit balance and the link to add credits. | | `GET` | `/v1/openapi.json` | none | The OpenAPI document. No key needed. | ## Requests [Section titled “Requests”](#requests) * Authenticate every request with `Authorization: Bearer cb_live_...`. See [Authentication](/authentication/). * Send bodies as JSON with `Content-Type: application/json`. The body must be a JSON object; anything else returns `400 invalid_body`. * Unknown body fields are ignored. * Text fields are trimmed, control characters are removed and long values are cut to the documented maximum. ## Responses [Section titled “Responses”](#responses) * Always JSON, with `Cache-Control: no-store`. * Field names are `snake_case`. Ids are UUIDs. Timestamps are ISO 8601 strings in UTC. * Success codes: `200 OK`, `201 Created` (new song), `202 Accepted` (video started). * Errors share one shape, see [Errors](/errors/): ```json { "error": "insufficient_credits", "message": "Not enough credits. Ask the account owner to add credits in Clipbeat Studio, then retry." } ``` Branch on `error` (a stable machine code), show `message` to people. ## Versioning [Section titled “Versioning”](#versioning) * The version is in the path: `/v1`. Within `v1` changes are additive: new endpoints, new optional fields, new response fields, new `error` codes and new enum values. Write clients that ignore unknown fields and treat unknown statuses as “not final”. * Anything that would break a `v1` client ships as a new version, announced in the [Changelog](/changelog/) first. ## CORS and where to call from [Section titled “CORS and where to call from”](#cors-and-where-to-call-from) Only `GET /v1/openapi.json` allows calls from any browser origin. Call the other endpoints from your server, never from a browser or app where users could read your key. ## Limits [Section titled “Limits”](#limits) 60 requests per minute per key, 10 song imports and 4 new videos per hour per account. See [Rate limits](/rate-limits/). # Rights declaration > What rights_attestation and rights_version mean, and what you confirm when you import a song. Clipbeat only makes videos for songs the user owns or has the rights to use. Every song import carries a rights declaration. ## What you confirm [Section titled “What you confirm”](#what-you-confirm) By sending a song you confirm: > By sending a song you confirm you own it or have the rights to use it. Finished videos can appear on your Clipbeat page. You can hide any video anytime. This text is also in the OpenAPI schema (`rights_attestation` description) and in the MCP tool description, so an agent can show it to its user before importing. ## Fields [Section titled “Fields”](#fields) | Field | Value | Where | | -------------------- | ------------ | -------------------------------------------------- | | `rights_attestation` | `true` | `POST /v1/songs`, MCP `create_video_from_song_url` | | `rights_version` | `2026-11-21` | `POST /v1/songs` (the MCP server sends it for you) | * Missing or not `true` → `400 rights_attestation_required`. * Missing or unknown version → `400 rights_version_required`. The message tells you the current version. When the wording changes, the version changes and this page says so in the [Changelog](/changelog/). ## If you build for other people [Section titled “If you build for other people”](#if-you-build-for-other-people) If your app or agent imports songs on behalf of its users, show them the declaration above and only send `rights_attestation: true` after they have agreed. Do not set it automatically for songs you have not checked. ## Your Clipbeat page [Section titled “Your Clipbeat page”](#your-clipbeat-page) Finished videos can appear on the account’s public Clipbeat page. The account owner can hide any video at any time in Clipbeat Studio. ## Reports [Section titled “Reports”](#reports) To report a video that uses your music without permission, write to [hello@clipbeat.app](mailto:hello@clipbeat.app?subject=Rights%20report) with the link to the video. # Songs > How a song gets into Clipbeat, which links are accepted, and the song object. A **song** is an audio file imported into the account. Every video starts from a song. Import it once and start as many videos from it as you like. ## Accepted links [Section titled “Accepted links”](#accepted-links) `POST /v1/songs` takes a public `https` link in `url`: | Source | Example | | ----------------- | ------------------------------------------------------------------------------------- | | Direct audio file | `https://example.com/my-song.mp3` (the path must end in `.mp3`, `.m4a` or `.wav`) | | Google Drive | A file share link (`drive.google.com/file/d/...`), shared with “Anyone with the link” | | Dropbox | A share link to the file | Not accepted: * **Suno page links** (`suno.com/...`). Download the audio from Suno and send a direct link to the file instead. The API answers `400 suno_link_not_supported`. * Streaming pages (YouTube, Spotify, SoundCloud and similar), private links, links that need a login, and anything that is not an audio file (`400 unsupported_link` or `400 invalid_audio`). * Files larger than 100 MB (`413 too_large`). Links are followed through at most 3 redirects. The song must be at least **20 seconds** long to make a video. Songs up to about 20 minutes are supported. ## Rights [Section titled “Rights”](#rights) Every import must include `"rights_attestation": true` and the current `rights_version`. See [Rights declaration](/concepts/rights/). ## Processing [Section titled “Processing”](#processing) After import Clipbeat reads the lyrics and their timing in the background. While that runs the song has `status: "processing"`. When it is done the song is `ready` and you can start a video. * Poll `GET /v1/songs/{id}` every few seconds, usually ready in under a minute. * `POST /v1/videos` also waits up to 20 seconds for a song that is still processing. If it is still not ready, you get `409 song_processing` with `retry_after_sec: 30`. * A song whose lyrics could not be read (an instrumental, for example) is still `ready`, with `lyrics_status: "failed"`. You can still make a video from it. Importing the same audio again into the same account returns the existing song with `200` instead of `201`. ## The song object [Section titled “The song object”](#the-song-object) ```json { "id": "8c5d2f9e-2a51-4f0e-9a43-1f4f3b0d6a21", "title": "My Song", "duration_sec": 184.3, "status": "ready", "lyrics_status": "ready", "created_at": "2026-11-22T09:14:03.000Z" } ``` | Field | Type | Description | | --------------- | ------------------------------- | ------------------------------------------------------------------------ | | `id` | string (UUID) | Song id. Use it as `song_id` in `POST /v1/videos` and `GET /v1/pricing`. | | `title` | string or null | Title read from the file or link. | | `duration_sec` | number or null | Length in seconds. Full video prices depend on it. | | `status` | `processing`, `ready` | Whether a video can be started. | | `lyrics_status` | `processing`, `ready`, `failed` | Lyrics and timing detection. | | `created_at` | string (ISO 8601) or null | When the song was imported. | ## Limits [Section titled “Limits”](#limits) * 10 song imports per account per hour (`429 rate_limited`, `retry_after_sec: 360`). Failed imports do not count. * See [Rate limits](/rate-limits/). # Tiers > The four video tiers available through the API, what each one delivers and how to choose. Every video is made in a **tier**. The tier sets how much of the song is covered, how much lip-sync there is and how much of the video moves. Tiers are the same as in Clipbeat Studio and cost the same. | Tier | What you get | Priced by | | ---------- | ---------------------------------------------------------------------------------------------------- | ----------- | | `preview` | A short lip-synced clip of your chorus with an original AI singer. The quickest way to see the look. | Fixed price | | `standard` | A full music video for the whole song. | Song length | | `plus` | A full music video, and the singer lip-syncs the chorus. | Song length | | `premium` | Lip-sync on the singing shots, Clipbeat’s highest quality images and motion, every scene moving. | Song length | Prices are on [Pricing & credits](/pricing/). ## The promise for your song [Section titled “The promise for your song”](#the-promise-for-your-song) The exact promise depends on the song (its length, how many scenes it needs). Read it from `GET /v1/pricing?song_id=...`. Each entry in `tiers` has: | Field | Description | | ---------------- | -------------------------------------------------------------- | | `tier` | `preview`, `standard`, `plus` or `premium`. | | `name` | Display name. | | `usd`, `credits` | Price for this song. | | `available` | Whether this tier can be started for this song and account. | | `lip_sync` | Whether the tier includes lip-sync. | | `outcome` | One sentence describing what this tier delivers for this song. | Show `outcome` to your users as it is. It is the same sentence Clipbeat Studio shows. ## Choosing a tier [Section titled “Choosing a tier”](#choosing-a-tier) * **Not sure yet?** Start with `preview`. It is a low-cost way to check the singer, the world and the lip-sync before you pay for the whole song. * **Demos, social posts, first releases:** `standard`. * **A release where the singer should sing the hook:** `plus`. * **The main video for a single:** `premium`. ## Availability [Section titled “Availability”](#availability) A tier can be unavailable for a song or account, shown as `"available": false` in the pricing response. For example, `premium` for songs longer than 10 minutes is on request and cannot be started through the API. Previews also need the account’s first purchase in Clipbeat Studio. Before that, starting a preview returns `402 payment_required` with a `topup_url`. Starting a tier that cannot be made returns an error (see [Errors](/errors/)) and nothing is charged. ## Aspect ratio [Section titled “Aspect ratio”](#aspect-ratio) Every tier can be made in `16:9` (YouTube, landscape) or `9:16` (Reels, TikTok, Shorts). Set `aspect` when you start the video. # Video jobs > The life of a Clipbeat video from start to download, its statuses, progress, cost fields and the video object. A **video job** is one music video being made from one song. You start it with `POST /v1/videos` (or the MCP tool `create_video_from_song_url`) and follow it with `GET /v1/videos/{id}` (or `get_video_status`). Making a video takes minutes, so the API is asynchronous: starting returns at once with `202 Accepted`, the work happens in the background. ## Lifecycle [Section titled “Lifecycle”](#lifecycle) ```text POST /v1/videos │ 202 Accepted, credits reserved ▼ ┌──────────┐ │ queued │ waiting for a free slot └────┬─────┘ ▼ ┌──────────┐ progress.stage: plan → images → motion → render │ running │ (polishing: a final quality pass) └────┬─────┘ ┌──────────┼───────────────┐ ▼ ▼ ▼ ┌───────────┐ ┌────────┐ ┌──────────┐ │ completed │ │ failed │ │ canceled │ └───────────┘ └────────┘ └──────────┘ result.video_url error stopped early credits charged credits unused credits (partial refund returned returned if shots missed) ``` | Status | Final | Meaning | What to do | | ----------- | ----- | ---------------------------------------------------------------------------------- | -------------------------------- | | `queued` | no | Accepted and waiting to start. | Poll. | | `running` | no | Being made. `progress` shows the step. | Poll. | | `completed` | yes | Done. `result.video_url` has the file. | Download or share the link. | | `failed` | yes | Could not be made. `error` says why. Reserved credits are returned. | Start again, or contact support. | | `canceled` | yes | Stopped before it finished (for example from Studio). Unused credits are returned. | Nothing. | Treat any status you do not recognize as “not final yet” and keep polling. ## One video at a time [Section titled “One video at a time”](#one-video-at-a-time) An account makes **one video at a time**. Starting another while one is `queued` or `running` returns `409 video_in_progress` with the current video in `video`. Wait for it to finish, then start the next one. ## Polling [Section titled “Polling”](#polling) * Poll every **30 to 60 seconds**. Faster polling does not make the video faster and uses your [rate limit](/rate-limits/). * A preview takes minutes. A full video takes longer, depending on tier and song length. * There are no webhooks yet. Polling is the way to know when a video is done. ## Progress [Section titled “Progress”](#progress) ```json "progress": { "stage": "motion", "done": 4, "total": 12, "percent": 33 } ``` | Field | Description | | --------------- | ----------------------------------------------------------------------------------------------------------------------- | | `stage` | The current step: `plan`, `images`, `motion`, `render`, `polishing` or `done`. For display only; new values can appear. | | `done`, `total` | Units finished out of the total for the current job. | | `percent` | `done / total` as a whole number from 0 to 100. | `progress` is `null` until the job has started. ## Cost fields [Section titled “Cost fields”](#cost-fields) ```json "cost": { "credits_reserved": 280, "credits_charged": 280, "credits_refunded": 0, "usd": 14 } ``` | Field | Description | | ------------------ | -------------------------------------------------------------------------------------------------- | | `credits_reserved` | Taken from the balance when the job started. | | `credits_charged` | Final charge, set when the job finishes. | | `credits_refunded` | Returned to the balance. | | `usd` | Reserved amount while the job runs; charged amount once it is `completed`, `failed` or `canceled`. | See [Pricing & credits](/pricing/). ## Result and download links [Section titled “Result and download links”](#result-and-download-links) When `status` is `completed`: ```json "result": { "video_url": "https://...", "poster_url": "https://...", "expires_in_sec": 86400 } ``` * `video_url` is a signed download link to the video file. It expires after `expires_in_sec` seconds. Call `GET /v1/videos/{id}` again for a fresh link; do not store the link itself. * `poster_url` is a still image for the video, or `null`. * The video is also in the account’s library in [Clipbeat Studio](https://studio.clipbeat.app) (`studio_url`), where the owner can edit it or reshoot scenes. ## The video object [Section titled “The video object”](#the-video-object) ```json { "id": "f1e2d3c4-b5a6-4789-8abc-def012345678", "status": "running", "tier": "standard", "title": "My Song", "aspect": "16:9", "created_at": "2026-11-22T09:16:40.000Z", "progress": { "stage": "images", "done": 3, "total": 12, "percent": 25 }, "cost": { "credits_reserved": 280, "credits_charged": 0, "credits_refunded": 0, "usd": 14 }, "result": null, "studio_url": "https://studio.clipbeat.app/" } ``` | Field | Type | Description | | ------------ | ---------------------------------------- | ------------------------------------------------------ | | `id` | string (UUID) | Video id. | | `status` | string | See [Lifecycle](#lifecycle). | | `tier` | `preview`, `standard`, `plus`, `premium` | See [Tiers](/concepts/tiers/). | | `title` | string or null | Title shown on the video. | | `aspect` | `16:9`, `9:16` or null | Frame shape. | | `created_at` | string (ISO 8601) or null | When the job was created. | | `progress` | object or null | See [Progress](#progress). | | `cost` | object | See [Cost fields](#cost-fields). | | `result` | object or null | Set only when `completed`. | | `error` | string | Present only when the job failed. | | `studio_url` | string | Where the owner can open the video in Clipbeat Studio. | ## Start parameters [Section titled “Start parameters”](#start-parameters) | Field | Required | Description | | ----------- | -------- | ---------------------------------------------------------------------------- | | `song_id` | yes | A song of this account in status `ready`. | | `tier` | no | `preview` (default), `standard`, `plus` or `premium`. | | `style` | no | World, place and look of the video, up to 600 characters. | | `character` | no | The original AI lead singer, up to 300 characters. No real or famous people. | | `aspect` | no | `16:9` or `9:16`. | | `title` | no | Up to 120 characters. Defaults to the song title. | `style`, `character` and `title` are checked before the job starts. A brief that names a real person, a celebrity, a protected character or a brand, or asks for unsafe content, is rejected with `422 brief_rejected` and nothing is charged. See [Content policy](/content-policy/). ## Listing videos [Section titled “Listing videos”](#listing-videos) `GET /v1/videos?limit=20` returns the account’s latest videos, newest first, as `{ "videos": [ ... ] }`. `limit` is 1 to 50, default 20. It includes videos made in Studio, not only through the API. # Content policy > What the Clipbeat API makes and what it refuses, for every request made through the REST API or the MCP server. These rules apply to every video started through the API or the MCP server. Requests that break them are refused before any credits are spent. ## Original AI characters only [Section titled “Original AI characters only”](#original-ai-characters-only) * The lead singer is always an **original AI character**. The API has no way to upload a face, a selfie or a photo of a person, and it does not make videos of real people. * Describe the character in `character` (for example “a young woman with a silver bob and a red leather jacket”). If you leave it out, Clipbeat casts an AI singer that fits the song. * Making a video with your own face is only possible in Clipbeat Studio, with the person’s consent. ## No real or famous people, no protected characters, no brands [Section titled “No real or famous people, no protected characters, no brands”](#no-real-or-famous-people-no-protected-characters-no-brands) The `style`, `character` and `title` fields are checked before a video starts. The request is refused with `422 brief_rejected` when the brief: * names a real person or a celebrity (“in the style of” a named artist included), * names a protected character from films, games, comics or cartoons, * names or depicts a brand, * asks for unsafe content. The response includes a `reason` when one is available, for example `"reason": "protected_name"`. Rewrite the brief with an original description and try again. A refused brief is not charged. ## Children [Section titled “Children”](#children) No sexual or suggestive content involving minors, ever. Songs for children (nursery rhymes, lullabies, learning songs) are welcome. ## Unsafe content [Section titled “Unsafe content”](#unsafe-content) No sexual content, graphic violence, hate, harassment, self-harm or illegal activity. Requests that ask for it are refused. ## Songs and rights [Section titled “Songs and rights”](#songs-and-rights) Only import songs you own or have the rights to use. Every import requires `rights_attestation: true`. See [Rights declaration](/concepts/rights/). ## AI disclosure [Section titled “AI disclosure”](#ai-disclosure) Videos made with Clipbeat are AI-generated. If you publish them, follow the rules of the platform you publish on for labeling AI content. ## Questions [Section titled “Questions”](#questions) Questions about the policy: [hello@clipbeat.app](mailto:hello@clipbeat.app?subject=Content%20policy). # Errors > Every error code the Clipbeat REST API and MCP server return, with status codes, response bodies and what to do. Errors use standard HTTP status codes and one JSON shape: ```json { "error": "song_processing", "message": "The song is still being processed. Try again in 30 seconds.", "retry_after_sec": 30 } ``` | Field | Always | Description | | ----------------- | ------ | ------------------------------------------------------------- | | `error` | yes | Stable machine code. Branch on this. | | `message` | yes | Human readable English sentence. Can change; do not parse it. | | `retry_after_sec` | no | Seconds to wait before retrying. | | `topup_url` | no | On `402`: where the account owner adds credits. | | other fields | no | Some codes add context, listed below. | New codes can be added within `v1`. Handle unknown codes by their HTTP status. ## 400 Bad Request [Section titled “400 Bad Request”](#400-bad-request) The request is invalid. Fix it before retrying. | `error` | Endpoint | Cause | | ----------------------------- | -------------------------------- | ---------------------------------------------------------------------------------- | | `invalid_body` | `POST` endpoints | The body is not a JSON object. | | `invalid_url` | `POST /v1/songs` | `url` is missing or empty. | | `suno_link_not_supported` | `POST /v1/songs` | A Suno page link. Send a direct link to the audio file. | | `unsupported_link` | `POST /v1/songs` | Not an `https` direct audio, Google Drive or Dropbox link, or not public. | | `too_many_redirects` | `POST /v1/songs` | The link redirects more than 3 times. | | `invalid_audio` | `POST /v1/songs` | The link did not return a playable audio file. | | `rights_attestation_required` | `POST /v1/songs`, MCP | `rights_attestation` is not `true`. | | `rights_version_required` | `POST /v1/songs` | `rights_version` is missing or not current. The message names the current version. | | `invalid_tier` | `POST /v1/videos` | `tier` is not `preview`, `standard`, `plus` or `premium`. | | `invalid_aspect` | `POST /v1/videos` | `aspect` is not `16:9` or `9:16`. | | `song_required` | MCP `create_video_from_song_url` | Neither `song_url` nor `song_id` was sent. | ## 401 Unauthorized [Section titled “401 Unauthorized”](#401-unauthorized) | `error` | Cause | | -------------- | -------------------------------------------------------------------------------------------------------------------------- | | `unauthorized` | No key, a malformed key, a revoked key or a deleted account. The response has `WWW-Authenticate: Bearer realm="clipbeat"`. | ## 402 Payment Required [Section titled “402 Payment Required”](#402-payment-required) The account does not have enough credits. Nothing was started or charged. The agent or app shows `topup_url` to the account owner, who adds credits in Clipbeat Studio. Never ask for card details. ```json { "error": "insufficient_credits", "message": "Not enough credits. Ask the account owner to add credits in Clipbeat Studio, then retry.", "available_credits": 40, "available_usd": 2, "required_credits": 280, "required_usd": 14, "topup_url": "https://studio.clipbeat.app/credits" } ``` | `error` | Cause | | ---------------------- | ---------------------------------------------------------------------------------------- | | `insufficient_credits` | Balance is lower than the tier’s price. `required_*` is present when known. | | `payment_required` | The account has not made its first purchase in Clipbeat Studio yet, which previews need. | ## 403 Forbidden [Section titled “403 Forbidden”](#403-forbidden) | `error` | Cause | | -------------------- | -------------------------------------------------------------------------------------------------------------------------------- | | `insufficient_scope` | The key does not have the scope this endpoint or tool needs. The message names the scope. See [Scopes](/authentication/#scopes). | ## 404 Not Found [Section titled “404 Not Found”](#404-not-found) | `error` | Endpoint | Cause | | ---------------- | ------------------------------------------- | ------------------------------------------------------------------------------------------ | | `not_found` | `GET /v1/songs/{id}`, `GET /v1/videos/{id}` | No such id in this account (ids of other accounts look the same as ids that do not exist). | | `song_not_found` | `POST /v1/videos`, `GET /v1/pricing` | `song_id` does not exist in this account. Import it first. | ## 409 Conflict [Section titled “409 Conflict”](#409-conflict) The request is valid but cannot run right now. | `error` | Extra fields | Cause and what to do | | --------------------- | ---------------------------------------------- | ---------------------------------------------------------------------------------------- | | `song_processing` | `retry_after_sec: 30` (MCP: `song_id`, `next`) | Lyrics are still being read. Retry after 30 seconds. | | `video_in_progress` | `video` (the running video) | The account already has a video `queued` or `running`. Poll it, then start the next one. | | `preview_unavailable` | | Previews are not available for this account through the API. Use a full video tier. | Other `409` codes can come from the video engine (for example `engine_off` when video making is not enabled for the account), with the message “The video could not be started.” Nothing is charged. Retry later. ## 413 Payload Too Large [Section titled “413 Payload Too Large”](#413-payload-too-large) | `error` | Cause | | ----------- | -------------------------------------- | | `too_large` | The linked file is larger than 100 MB. | ## 422 Unprocessable Content [Section titled “422 Unprocessable Content”](#422-unprocessable-content) The request is understood but refused. Nothing is charged. | `error` | Extra fields | Cause | | ---------------- | --------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `brief_rejected` | `reason` (for example `protected_name`) | `style`, `character` or `title` names a real person, a celebrity, a protected character or a brand, or asks for unsafe content. See [Content policy](/content-policy/). | | `song_too_short` | | The song is shorter than 20 seconds. | ## 429 Too Many Requests [Section titled “429 Too Many Requests”](#429-too-many-requests) | `error` | Extra fields | Cause | | -------------- | ----------------------------------------------------------------- | ------------------------------------------------------ | | `rate_limited` | `retry_after_sec` (and `Retry-After` header on the per-key limit) | A [rate limit](/rate-limits/) was hit. Wait and retry. | ## 5xx Server errors [Section titled “5xx Server errors”](#5xx-server-errors) Temporary problems on Clipbeat’s side. Retry with exponential backoff. If one persists for more than a few minutes, write to [hello@clipbeat.app](mailto:hello@clipbeat.app?subject=API%20error) with the time and the endpoint. | Status | `error` | Cause | | ------ | ------------------------------------ | ----------------------------------------------------------------------------------------------- | | `500` | `internal_error` | Unexpected error. The video was not started. | | `502` | `import_failed`, `link_fetch_failed` | The song could not be downloaded from the link or saved. Check that the link works, then retry. | | `503` | `check_failed` | The brief could not be checked right now. Retry. | | `503` | `storage_unavailable` | Storage is briefly unavailable. Retry. | Other `5xx` codes are possible. Treat any `5xx` as temporary. ## Errors inside MCP tools [Section titled “Errors inside MCP tools”](#errors-inside-mcp-tools) MCP tool errors are not JSON-RPC errors. The tool call succeeds at the protocol level and returns a result with `isError: true`; the error body above is in `structuredContent` and, as JSON text, in `content[0].text`: ```json { "jsonrpc": "2.0", "id": 3, "result": { "content": [{ "type": "text", "text": "{\"error\":\"insufficient_credits\",\"message\":\"Not enough credits...\",\"topup_url\":\"https://studio.clipbeat.app/credits\"}" }], "structuredContent": { "error": "insufficient_credits", "message": "Not enough credits...", "topup_url": "https://studio.clipbeat.app/credits" }, "isError": true } } ``` JSON-RPC errors are used only for protocol problems: | Code | Message | Cause | | -------- | ---------------- | -------------------------------------------------- | | `-32700` | Parse error | The body is not JSON (HTTP `400`). | | `-32600` | Invalid Request | Not a JSON-RPC 2.0 message, or an empty batch. | | `-32601` | Method not found | A method the server does not implement. | | `-32602` | Unknown tool | `tools/call` with a tool name that does not exist. | Authentication and rate limit errors on `/mcp` are plain HTTP `401` and `429` responses, as for REST. # MCP server > Clipbeat's remote Model Context Protocol server lets an AI assistant make a music video for its user. The [Model Context Protocol](https://modelcontextprotocol.io) (MCP) is an open standard that lets AI assistants call tools. Clipbeat runs a **remote MCP server**, so an assistant that supports MCP can import a song, check prices, start a video and hand back the download link, all inside the conversation. ## Server [Section titled “Server”](#server) | | | | ----------------- | -------------------------------------------------------------------------------------------------- | | URL | `https://api.clipbeat.app/mcp` | | Transport | Streamable HTTP. Each message is a `POST`; responses are plain JSON (no server-sent event stream). | | Sessions | Stateless. No `Mcp-Session-Id`, nothing to clean up. `GET` and `DELETE` return `405`. | | Protocol versions | `2025-06-18` (preferred), `2025-03-26`, `2024-11-05` | | Auth today | `Authorization: Bearer cb_live_...` API key. See [MCP authentication](/mcp/authentication/). | | Capabilities | `tools`. No resources or prompts (`resources/list` and `prompts/list` return empty lists). | | Batching | JSON-RPC batches (arrays) are accepted. | ## Tools [Section titled “Tools”](#tools) | Tool | Read only | What it does | | ---------------------------------------------------------------------- | --------- | -------------------------------------------------------------- | | [`create_video_from_song_url`](/mcp/tools/#create_video_from_song_url) | no | Import a song (or reuse one) and start a video. Costs credits. | | [`get_video_status`](/mcp/tools/#get_video_status) | yes | Status, progress, cost and the download link when done. | | [`list_my_videos`](/mcp/tools/#list_my_videos) | yes | The account’s latest videos. | | [`get_pricing`](/mcp/tools/#get_pricing) | yes | Price per tier, optionally for a specific song. | | [`get_balance`](/mcp/tools/#get_balance) | yes | Credit balance and the link to add credits. | ## How an assistant uses it [Section titled “How an assistant uses it”](#how-an-assistant-uses-it) The server sends these instructions to the client when it connects: > Clipbeat turns a song into a music video for the signed-in account. Typical flow: get_pricing, then create_video_from_song_url (start with tier preview), then poll get_video_status every 30 to 60 seconds until status is completed and share result.video_url. Payment comes from the account’s credit balance; on insufficient_credits give the user topup_url (never ask for card details). The lead is always an original AI character; do not describe real or famous people. A typical conversation: 1. The user shares a song link and asks for a video. 2. The assistant calls `get_pricing` and tells the user the price. 3. The user confirms they own the song. The assistant calls `create_video_from_song_url` with `rights_attestation: true` and `tier: "preview"`. 4. The assistant calls `get_video_status` every 30 to 60 seconds and shares `result.video_url` when the status is `completed`. ## MCP or REST? [Section titled “MCP or REST?”](#mcp-or-rest) | | MCP server | REST API | | ----------------------------- | ---------------------------------- | ------------------------------------------------------- | | Best for | AI assistants and agent frameworks | Your own code, automations, backends | | Song import and video start | One tool call | Two requests (`POST /v1/songs`, then `POST /v1/videos`) | | Same prices, limits and rules | yes | yes | Both use the same account, credits, [rate limits](/rate-limits/) and [content policy](/content-policy/). ## Next [Section titled “Next”](#next) * [Tools reference](/mcp/tools/): inputs, outputs and example calls. * [Connect a client](/mcp/clients/): Claude, Cursor, VS Code, ChatGPT, n8n and others. # MCP authentication > How MCP clients authenticate with Clipbeat today (API key) and the OAuth 2.1 sign-in that is available soon. ## Today: API key Live [Section titled “Today: API key ”](#today-api-key-) The MCP server accepts the same personal API key as the REST API: ```text Authorization: Bearer cb_live_... ``` Create the key in Clipbeat Studio, **Settings**, **Developers**, **API keys**. The key’s [scopes](/authentication/#scopes) decide which tools it can call. Setups for each client are in [Connect an MCP client](/mcp/clients/). ## Soon: one click sign-in with OAuth Available soon [Section titled “Soon: one click sign-in with OAuth ”](#soon-one-click-sign-in-with-oauth-) Not live yet Everything in this section describes a feature that is **not available yet**. Endpoints, scopes and limits can change before launch. Use the API key method above until this page says otherwise. Launch will be announced in the [Changelog](/changelog/). With OAuth, a user connects an AI client to Clipbeat by signing in and approving the connection, without copying a key. This is how clients that only offer a sign-in screen (for example Claude and ChatGPT connectors) will connect. When it launches, MCP connections move to OAuth and API keys remain the way to use the REST API. ### How connecting will work [Section titled “How connecting will work”](#how-connecting-will-work) 1. The user adds `https://api.clipbeat.app/mcp` to their AI client. 2. The client discovers Clipbeat’s authorization server and opens a Clipbeat sign-in page. 3. The user signs in and sees which client is asking, what it may do and how much it may spend per day. 4. The user approves. The client receives tokens and the tools appear. The user sees and controls every connection in Clipbeat Studio (connected apps): the daily credit limit can be changed and the connection revoked at any time. ### Planned details for client developers [Section titled “Planned details for client developers”](#planned-details-for-client-developers) The design follows the MCP authorization specification and OAuth 2.1: | Item | Plan | | ----------------------------- | --------------------------------------------------------------------------------------------------------------------- | | Protected resource metadata | `GET https://api.clipbeat.app/.well-known/oauth-protected-resource/mcp` (RFC 9728) | | Authorization server metadata | `GET https://api.clipbeat.app/.well-known/oauth-authorization-server` (RFC 8414) | | Authorization endpoint | `https://api.clipbeat.app/oauth/authorize` | | Token endpoint | `https://api.clipbeat.app/oauth/token` | | Client registration | Client ID metadata documents, and dynamic client registration at `https://api.clipbeat.app/oauth/register` (RFC 7591) | | Revocation | `https://api.clipbeat.app/oauth/revoke` (RFC 7009) | | PKCE | Required, `S256` only | | Resource indicator | `resource=https://api.clipbeat.app/mcp` (RFC 8707); tokens are only valid for the MCP server | | Scopes | `create:video`, `read:video`, `read:balance` | | Access token lifetime | 1 hour | | Refresh tokens | Rotated on every use, valid for 30 days | | Spending limit | A daily credit limit per connection, set by the user when approving | A request to `/mcp` without valid credentials will return `401` with a `WWW-Authenticate` header that points to the protected resource metadata, so standard MCP clients can start the flow on their own. ### What will not change [Section titled “What will not change”](#what-will-not-change) * Prices, [rate limits](/rate-limits/), the [content policy](/content-policy/) and the tools themselves stay the same. * Payment still comes from the account’s credit balance; card details never go through the client. * The REST API keeps using API keys. Questions about the OAuth rollout: [hello@clipbeat.app](mailto:hello@clipbeat.app?subject=MCP%20OAuth). # Connect an MCP client > Set up the Clipbeat MCP server in Claude Code, Claude Desktop, Cursor, VS Code, ChatGPT, n8n or any Streamable HTTP client. Every client needs two things: the server URL and your API key in an `Authorization` header. ```text URL: https://api.clipbeat.app/mcp Header: Authorization: Bearer cb_live_... ``` Create the key in Clipbeat Studio, **Settings**, **Developers**, **API keys** ([Authentication](/authentication/)). Replace `cb_live_...` below with your key, or better, keep the key in an environment variable or the client’s secret store. One click sign-in is coming Clients that connect with a sign-in screen instead of a key (Claude and ChatGPT connectors, for example) need OAuth, which is **available soon**. Until then use the key based setups on this page. See [MCP authentication](/mcp/authentication/). ## Claude Code [Section titled “Claude Code”](#claude-code) ```bash claude mcp add --transport http clipbeat https://api.clipbeat.app/mcp \ --header "Authorization: Bearer $CLIPBEAT_API_KEY" ``` Check it with `claude mcp list`, then ask: “Make a preview music video for `https://example.com/my-song.mp3`”. ## Claude Desktop [Section titled “Claude Desktop”](#claude-desktop) Claude Desktop starts local servers from `claude_desktop_config.json` (Settings, Developer, Edit Config). Use the [`mcp-remote`](https://www.npmjs.com/package/mcp-remote) bridge to reach the remote server with your key (needs Node.js): ```json { "mcpServers": { "clipbeat": { "command": "npx", "args": ["-y", "mcp-remote", "https://api.clipbeat.app/mcp", "--header", "Authorization:${CLIPBEAT_AUTH}"], "env": { "CLIPBEAT_AUTH": "Bearer cb_live_..." } } } } ``` Restart Claude Desktop after saving. The header is passed through `env` so the space in `Bearer cb_live_...` survives on every operating system. ## Cursor [Section titled “Cursor”](#cursor) Add to `~/.cursor/mcp.json` (all projects) or `.cursor/mcp.json` (one project): ```json { "mcpServers": { "clipbeat": { "url": "https://api.clipbeat.app/mcp", "headers": { "Authorization": "Bearer cb_live_..." } } } } ``` ## VS Code [Section titled “VS Code”](#vs-code) Add to `.vscode/mcp.json`. VS Code asks for the key once and stores it securely: ```json { "inputs": [ { "type": "promptString", "id": "clipbeat-key", "description": "Clipbeat API key", "password": true } ], "servers": { "clipbeat": { "type": "http", "url": "https://api.clipbeat.app/mcp", "headers": { "Authorization": "Bearer ${input:clipbeat-key}" } } } } ``` The tools appear in Copilot Chat in agent mode. ## ChatGPT [Section titled “ChatGPT”](#chatgpt) ChatGPT connects to MCP servers through a sign-in flow (OAuth), which Clipbeat will support soon. Today, add Clipbeat to a custom GPT as an **Action** using the REST API: 1. In the GPT editor, open **Configure**, then **Create new action**. 2. Choose **Import from URL** and enter `https://api.clipbeat.app/v1/openapi.json`. 3. Under **Authentication**, choose **API Key**, auth type **Bearer**, and paste your key. The GPT can then import songs, start videos and poll their status with the same rules as the MCP tools. ## n8n [Section titled “n8n”](#n8n) Use the **MCP Client Tool** node with an AI Agent node: | Setting | Value | | ---------------- | --------------------------------------- | | Endpoint | `https://api.clipbeat.app/mcp` | | Server Transport | HTTP Streamable | | Authentication | Bearer Auth, with your key as the token | | Tools to Include | All, or pick the tools you need | For fixed workflows without an agent, the **HTTP Request** node calling the [REST API](/api/) is often simpler. ## Any Streamable HTTP client [Section titled “Any Streamable HTTP client”](#any-streamable-http-client) The server speaks plain JSON-RPC 2.0 over `POST`. You can talk to it with nothing more than `curl`: ```bash curl -s https://api.clipbeat.app/mcp \ -H "Authorization: Bearer $CLIPBEAT_API_KEY" \ -H "Content-Type: application/json" \ -H "Accept: application/json, text/event-stream" \ -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"my-client","version":"1.0.0"}}}' ``` With the official SDKs: * TypeScript ```js // npm install @modelcontextprotocol/sdk import { Client } from '@modelcontextprotocol/sdk/client/index.js'; import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js'; const transport = new StreamableHTTPClientTransport(new URL('https://api.clipbeat.app/mcp'), { requestInit: { headers: { Authorization: `Bearer ${process.env.CLIPBEAT_API_KEY}` } }, }); const client = new Client({ name: 'my-app', version: '1.0.0' }); await client.connect(transport); const { tools } = await client.listTools(); console.log(tools.map((t) => t.name)); const balance = await client.callTool({ name: 'get_balance', arguments: {} }); console.log(balance.structuredContent); await client.close(); ``` * Python ```python # pip install mcp import asyncio import os from mcp import ClientSession from mcp.client.streamable_http import streamablehttp_client async def main(): headers = {"Authorization": f"Bearer {os.environ['CLIPBEAT_API_KEY']}"} async with streamablehttp_client("https://api.clipbeat.app/mcp", headers=headers) as (read, write, _): async with ClientSession(read, write) as session: await session.initialize() tools = await session.list_tools() print([t.name for t in tools.tools]) balance = await session.call_tool("get_balance", {}) print(balance.structuredContent) asyncio.run(main()) ``` ## Troubleshooting [Section titled “Troubleshooting”](#troubleshooting) | Symptom | Cause and fix | | -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | | `401` on connect | The key is missing, mistyped or revoked. Check the header is exactly `Authorization: Bearer cb_live_...`. | | Client tries `GET /mcp` and gets `405` | The server does not offer a server-sent event stream. Streamable HTTP clients fall back to `POST` only; older SSE-only clients are not supported. | | `insufficient_credits` from a tool | The account needs credits. Open the `topup_url` from the result. | | `429` | Too many requests for this key. See [Rate limits](/rate-limits/). | | Tools do not appear | Restart the client after editing its config. Some clients only load MCP tools in agent mode. | # MCP tools > Input schema, output and example call for each of the five Clipbeat MCP tools. Every tool returns its result twice: as `structuredContent` (a JSON object) and as `content[0].text` (the same object as a JSON string) for clients that only read text. Errors come back with `isError: true` and the [error body](/errors/) in the same places. The outputs are the same objects the REST API returns, so the [video object](/concepts/video-jobs/#the-video-object) and [song object](/concepts/songs/#the-song-object) docs apply. ## `create_video_from_song_url` [Section titled “create_video_from_song_url”](#create_video_from_song_url) Imports a song and starts a music video in one call, or starts a video from a song imported earlier. **Costs credits.** **Scopes:** `videos:write`, plus `songs:write` when `song_url` is used. **Annotations:** `readOnlyHint: false`, `destructiveHint: false`, `idempotentHint: false`, `openWorldHint: true`. | Argument | Type | Required | Description | | -------------------- | ---------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------ | | `rights_attestation` | boolean | yes | Must be `true`: the user owns the song or has the rights to use it. | | `song_url` | string | one of | Link to the audio: direct `.mp3`, `.m4a`, `.wav`, or a Google Drive or Dropbox share link. Suno links are not supported. | | `song_id` | string | one of | Song id from an earlier call, instead of `song_url`. | | `tier` | `preview`, `standard`, `plus`, `premium` | no | Default `preview`. | | `style` | string | no | World, place and look of the video. | | `character` | string | no | The original AI lead singer. | | `aspect` | `16:9`, `9:16` | no | Frame shape. | | `title` | string | no | Title of the video. | The server sends the current `rights_version` for you. Example call: ```json { "jsonrpc": "2.0", "id": 3, "method": "tools/call", "params": { "name": "create_video_from_song_url", "arguments": { "song_url": "https://example.com/my-song.mp3", "rights_attestation": true, "tier": "preview", "aspect": "9:16", "style": "desert highway at golden hour" } } } ``` Result (`structuredContent`): the [video object](/concepts/video-jobs/#the-video-object) plus `song_id` and a `next` hint. ```json { "id": "f1e2d3c4-b5a6-4789-8abc-def012345678", "status": "queued", "tier": "preview", "title": "My Song", "aspect": "9:16", "created_at": "2026-11-22T09:16:40.000Z", "progress": null, "cost": { "credits_reserved": 100, "credits_charged": 0, "credits_refunded": 0, "usd": 5 }, "result": null, "studio_url": "https://studio.clipbeat.app/", "song_id": "8c5d2f9e-2a51-4f0e-9a43-1f4f3b0d6a21", "next": "Poll get_video_status every 30 to 60 seconds." } ``` If the song was imported but is still being processed, the result is an error with `error: "song_processing"`, the `song_id`, and `next: "Call create_video_from_song_url again with this song_id in about 30 seconds."` Call again with `song_id` (not `song_url`) so the song is not imported twice. ## `get_video_status` [Section titled “get_video_status”](#get_video_status) Status, progress, cost and, when completed, the download link of a video. **Scope:** `videos:read`. **Annotations:** `readOnlyHint: true`. | Argument | Type | Required | Description | | ---------- | ------ | -------- | -------------------------------------------------- | | `video_id` | string | yes | The `id` returned by `create_video_from_song_url`. | ```json { "jsonrpc": "2.0", "id": 4, "method": "tools/call", "params": { "name": "get_video_status", "arguments": { "video_id": "f1e2d3c4-b5a6-4789-8abc-def012345678" } } } ``` Result: the [video object](/concepts/video-jobs/#the-video-object). When `status` is `completed`, share `result.video_url` with the user. The link expires after `result.expires_in_sec` seconds; call the tool again for a fresh one. ## `list_my_videos` [Section titled “list_my_videos”](#list_my_videos) The account’s latest videos with their status, newest first. **Scope:** `videos:read`. **Annotations:** `readOnlyHint: true`. | Argument | Type | Required | Description | | -------- | ---------------- | -------- | ----------- | | `limit` | integer, 1 to 50 | no | Default 20. | Result: `{ "videos": [ ... ] }`, an array of video objects. ## `get_pricing` [Section titled “get_pricing”](#get_pricing) Price per tier in USD and credits. Pass `song_id` for prices by song length. **Scope:** `account:read`. **Annotations:** `readOnlyHint: true`. | Argument | Type | Required | Description | | --------- | ------ | -------- | ----------------------- | | `song_id` | string | no | A song of this account. | Result: the same object as [`GET /v1/pricing`](/pricing/#reading-prices-in-code): `currency`, `credits_per_usd`, `tiers` (each with `tier`, `name`, `usd`, `credits`, `available`, `lip_sync`, `outcome`), `topup_url` and `note`. ## `get_balance` [Section titled “get_balance”](#get_balance) The account’s credit balance and the link to add credits. **Scope:** `account:read`. **Annotations:** `readOnlyHint: true`. No arguments. ```json { "jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": { "name": "get_balance", "arguments": {} } } ``` Result: ```json { "credits": 400, "usd": 20, "credits_per_usd": 20, "topup_url": "https://studio.clipbeat.app/credits" } ``` ## Discovering tools [Section titled “Discovering tools”](#discovering-tools) `tools/list` returns the tools with their full JSON Schemas, titles and annotations. The list does not change while connected (`listChanged: false`). ```bash curl -s https://api.clipbeat.app/mcp \ -H "Authorization: Bearer $CLIPBEAT_API_KEY" \ -H "Content-Type: application/json" \ -H "Accept: application/json, text/event-stream" \ -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' ``` # Pricing & credits > What each Clipbeat API tier costs, how credits work and how to read prices for a specific song. Every video made through the API is paid from the Clipbeat account’s **credit balance**. The API and MCP server use the same prices as Clipbeat Studio. There is no separate API plan and no subscription. Prices on this page are generated This page is built from the same price table that Clipbeat Studio uses, on 2026-11-22. For the exact price of a specific song, always call [`GET /v1/pricing?song_id=...`](/api/reference/operations/getpricing/). That response is what you will be charged. ## Credits [Section titled “Credits”](#credits) | | | | ----------------------- | ------------------------------------------------------------------------------------------------ | | Exchange rate | **1 USD = 20 credits** (`credits_per_usd` in every pricing and balance response) | | Where credits come from | Credit packs bought by the account owner in Clipbeat Studio | | Who pays | The account that owns the API key | | Card details | Never sent through the API. When the balance is too low the API answers `402` with a `topup_url` | Read the balance with [`GET /v1/balance`](/api/reference/operations/getbalance/) or the `get_balance` MCP tool. ## Preview [Section titled “Preview”](#preview) | Tier | Price | Credits | What you get | | --------- | ----- | ------- | ----------------------------------------------------------------- | | `preview` | $5 | 100 | A short lip-synced clip of your chorus with an original AI singer | The account makes its first purchase in Clipbeat Studio before previews can be made through the API (see [`payment_required`](/errors/#402-payment-required)). ## Full videos [Section titled “Full videos”](#full-videos) Full videos are priced by **song length** and **tier**: Standard from $5, Plus from $19, Premium from $39. Song length is rounded up to whole minutes, with a 15 second tolerance (a 4:15 song is priced as 4 minutes). Songs can be up to 20 minutes long. | Song length | Standard | Plus | Premium | | ----------- | ------------------ | ------------------- | ------------------- | | 1 min | $5 (100 credits) | $19 (380 credits) | $39 (780 credits) | | 2 min | $5 (100 credits) | $20 (400 credits) | $39 (780 credits) | | 3 min | $11 (220 credits) | $25 (500 credits) | $53 (1060 credits) | | 4 min | $14 (280 credits) | $30 (600 credits) | $69 (1380 credits) | | 5 min | $17 (340 credits) | $35 (700 credits) | $84 (1680 credits) | | 6 min | $21 (420 credits) | $39 (780 credits) | $100 (2000 credits) | | 8 min | $29 (580 credits) | $49 (980 credits) | $131 (2620 credits) | | 10 min | $37 (740 credits) | $59 (1180 credits) | $162 (3240 credits) | | 15 min | $57 (1140 credits) | $84 (1680 credits) | On request | | 20 min | $77 (1540 credits) | $109 (2180 credits) | On request | Premium for songs longer than 10 minutes is on request and cannot be started through the API. In `GET /v1/pricing` such a tier shows `"available": false`. ## How a charge works [Section titled “How a charge works”](#how-a-charge-works) 1. When you start a video, its price is **reserved** from the balance (`cost.credits_reserved`). 2. When the video finishes, the final amount is **charged** (`cost.credits_charged`). 3. Anything not charged is **returned** to the balance (`cost.credits_refunded`). If a video fails, the reserved credits are returned in full. If a delivered video has fewer moving shots than planned, part of the price is returned automatically. `cost.usd` shows the reserved amount while the video is running and the charged amount once it has finished. See [Video jobs](/concepts/video-jobs/#cost-fields). ## Reading prices in code [Section titled “Reading prices in code”](#reading-prices-in-code) ```bash curl -s "https://api.clipbeat.app/v1/pricing?song_id=$SONG_ID" \ -H "Authorization: Bearer $CLIPBEAT_API_KEY" ``` ```json { "currency": "USD", "credits_per_usd": 20, "song_id": "8c5d2f9e-2a51-4f0e-9a43-1f4f3b0d6a21", "tiers": [ { "tier": "preview", "name": "Preview", "usd": 5, "credits": 100, "available": true, "lip_sync": true, "outcome": "A short lip-synced preview of your chorus with an AI singer" }, { "tier": "standard", "name": "Standard", "usd": 14, "credits": 280, "available": true, "lip_sync": true, "outcome": "..." } ], "topup_url": "https://studio.clipbeat.app/credits", "note": "Payment is taken from the account's credit balance. Same prices as Clipbeat Studio." } ``` Without `song_id` the response lists the tiers with their starting prices. The `outcome` text describes what each tier delivers and can change; show it to your users as is. ## Refunds and money questions [Section titled “Refunds and money questions”](#refunds-and-money-questions) Questions about a charge go to [hello@clipbeat.app](mailto:hello@clipbeat.app?subject=Clipbeat%20API%20billing). # Rate limits > Request, import and video limits of the Clipbeat API, the 429 response and how to retry. Limits protect the service and your credits from runaway loops. They are generous for normal use: a video takes minutes, so a well behaved client makes few requests. ## Limits [Section titled “Limits”](#limits) | Limit | Applies to | Scope | On limit | | ------------------------ | -------------------------------------------------------------- | ------------------------------------------- | --------------------------------------------- | | 60 requests per minute | Every REST and MCP request | Per API key (REST and MCP share one budget) | `429`, `retry_after_sec: 5`, `Retry-After: 5` | | 10 song imports per hour | `POST /v1/songs`, `create_video_from_song_url` with `song_url` | Per account | `429`, `retry_after_sec: 360` | | 4 new videos per hour | `POST /v1/videos`, `create_video_from_song_url` | Per account | `429`, `retry_after_sec: 900` | | 1 video in progress | `POST /v1/videos`, `create_video_from_song_url` | Per account | `409 video_in_progress` | | 5 active API keys | Key creation in Studio | Per account | Revoke a key first | The per-key limit refills continuously (one request per second), so short bursts are fine. Imports and videos that fail before they start (for example a rejected brief or a bad link) do not count toward the hourly limits. ## The 429 response [Section titled “The 429 response”](#the-429-response) ```http HTTP/1.1 429 Too Many Requests Retry-After: 5 Content-Type: application/json { "error": "rate_limited", "message": "Too many requests for this key.", "retry_after_sec": 5 } ``` ## Retrying [Section titled “Retrying”](#retrying) * Wait at least `retry_after_sec` seconds (or the `Retry-After` header when present) before retrying. * For other temporary errors (`502`, `503`) retry with exponential backoff: 2, 4, 8, 16 seconds, then give up and show the error. * Do not retry `400`, `401`, `402`, `403`, `404` or `422` without changing the request. * `POST /v1/videos` is not idempotent. If a start request times out on your side, call `GET /v1/videos?limit=1` before starting again: the video may already be running, and a second start returns `409 video_in_progress`. ## Polling budget [Section titled “Polling budget”](#polling-budget) Polling one video every 30 seconds uses 2 requests per minute. The per-key limit leaves plenty of room for several integrations on one key, but one key per integration makes problems easier to trace. Need higher limits? Write to [hello@clipbeat.app](mailto:hello@clipbeat.app?subject=API%20rate%20limits) with your use case. # Changelog > Changes to the Clipbeat REST API, the MCP server and these docs. Changes within `v1` are additive. Anything that could break a client is announced here first. For product updates see [clipbeat.app](https://clipbeat.app). ## 2026-11-22 [Section titled “2026-11-22”](#2026-11-22) * **Docs:** this developer documentation site launched at `docs.clipbeat.app`, with the API reference generated from the OpenAPI schema, per page Markdown, `llms.txt` and `llms-full.txt`. * **MCP:** OAuth 2.1 sign-in for MCP clients announced as available soon. See [MCP authentication](/mcp/authentication/). ## 2026-11-21 [Section titled “2026-11-21”](#2026-11-21) * **REST API v1** released: `POST /v1/songs`, `GET /v1/songs/{id}`, `POST /v1/videos`, `GET /v1/videos`, `GET /v1/videos/{id}`, `GET /v1/pricing`, `GET /v1/balance` and the OpenAPI 3.1 document at `GET /v1/openapi.json`. * **MCP server** released at `https://api.clipbeat.app/mcp` (Streamable HTTP) with five tools: `create_video_from_song_url`, `get_video_status`, `list_my_videos`, `get_pricing`, `get_balance`. * **API keys** in Clipbeat Studio settings, up to 5 active keys per account. * Rights declaration version `2026-11-21`. * Prices are the same as Clipbeat Studio and come from the Studio tier menu; previews use the Studio preview price. * Suno page links are not accepted for song import; send a direct link to the audio file. # Support > How to get help with the Clipbeat API and MCP server, report a problem or a mistake in these docs. ## Contact [Section titled “Contact”](#contact) Write to **[hello@clipbeat.app](mailto:hello@clipbeat.app?subject=Clipbeat%20API)**. To get an answer faster, include: * what you tried to do, * the endpoint or MCP tool, and the time of the request (with time zone), * the full error body (`error` and `message`), * the song id or video id if there is one. **Never send your API key.** The first characters of the key (its prefix, as shown in Studio) are enough to identify it. ## Billing and credits [Section titled “Billing and credits”](#billing-and-credits) Questions about a charge, a refund or credits: [hello@clipbeat.app](mailto:hello@clipbeat.app?subject=API%20billing) with the video id. The `cost` fields of the video object show what was reserved, charged and returned. ## Security [Section titled “Security”](#security) If you find a security problem, write to [hello@clipbeat.app](mailto:hello@clipbeat.app?subject=Security) with “Security” in the subject. Please do not test against other people’s accounts. If your key leaked, [revoke it](/authentication/#revoke-a-key) first. ## Mistakes in these docs [Section titled “Mistakes in these docs”](#mistakes-in-these-docs) Every page has a link at the bottom to report a question or a mistake by email. You can also copy any page as Markdown with **Copy page as Markdown** at the top, which is handy for pasting into an AI assistant or a ticket. ## Status [Section titled “Status”](#status) When something is wrong on Clipbeat’s side the API answers with `5xx` codes. See [Errors](/errors/#5xx-server-errors) for how to retry.