Getting started with the API

The ClipHeat API is the one the app uses: everything you do from the screen — estimating a video, starting a generation, following its progress, fetching the clips — can also be done from a script.

Base URL: https://clipheat.app/api · Format: JSON in and out (except file uploads, sent as multipart/form-data).

1. Create a key

In the app: Settings → API keys → Create a key.

The key starts with ch_.
It is shown only once. Copy it straight away into a secrets manager: ClipHeat does not keep it in clear text and cannot show it to you again. If you lose it, revoke it and create a new one.
On the free plan, the account’s email address must be verified before you can create a key. Otherwise creation returns 403 with a detail starting with email_not_verified:. The verification link is in the welcome email and can be sent again from the settings.

2. Authenticate

Every request carries the key in one of these headers:

curl https://clipheat.app/api/credits \
  -H "X-API-Key: ch_your_key"

# equivalent
curl https://clipheat.app/api/credits \
  -H "Authorization: Bearer ch_your_key"

No other header is needed. The key acts on behalf of your account: same credits, same projects, same limits as in the app.

3. Check that everything is connected

curl -s https://clipheat.app/api/credits -H "X-API-Key: ch_your_key"

{
  "balance": 1960,
  "allocated": 2000,
  "used": 40,
  "unlimited": false,
  "plan": "studio",
  "email_verifie": true,
  "period_end": "2026-10-26T13:54:07+00:00"
}

A 200: the key is good. A 401 or 403: the key is missing, mistyped, expired or revoked.

4. A generation end to end

Estimate (optional, nothing is debited)

curl -s https://clipheat.app/api/estimate \
  -H "X-API-Key: ch_your_key" -H "Content-Type: application/json" \
  -d '{"url": "https://www.youtube.com/watch?v=VIDEO_ID", "start": 600, "end": 1500}'

The response gives the source’s duration, the billed minutes (those of the portion if you pass start/end, in seconds) and the estimated amount. The range actually kept comes back in range: that is the one to display.

Start

curl -s https://clipheat.app/api/process \
  -H "X-API-Key: ch_your_key" -H "Content-Type: application/json" \
  -d '{"url": "https://www.youtube.com/watch?v=VIDEO_ID",
       "language": "fr", "max_clips": 5, "aspect": "9:16"}'

The response carries a job_id. max_clips is a ceiling (1 to 20), not an order: a quiet video may yield fewer clips. To send a file rather than a URL, post it as multipart/form-data.

Follow

curl -s https://clipheat.app/api/status/JOB_ID -H "X-API-Key: ch_your_key"

Returns the current step, the progress and, once the generation is finished, the list of clips with their title, score, boundaries, video_url and, when there is one, a thumbnail (cover_url). Poll every few seconds, no faster: the clips are delivered together, at the end.

curl -s -X POST https://clipheat.app/api/media/JOB_ID/0/link \
  -H "X-API-Key: ch_your_key"

Returns {"url": "…", "expires_at": 1790000000}: a signed download URL, readable without an account, valid for one hour. The 0 is the clip’s index in the list returned by status.

The details of each route — every field, the history, brand templates — are in The routes.

5. Errors

Every error returns JSON with a detail field.

Code	What it means
`400`	malformed request
`401` / `403`	key missing, invalid or revoked — or action not included in the plan (`detail` then starts with `plan_feature_required:`)
`402`	not enough credits for this duration
`404`	resource not found for this account — an identifier belonging to another account answers the same way
`409`	conflict: the resource’s state does not allow the action (already running, already published…)
`422`	a field is out of bounds; `detail` says which
`429`	rate limit reached — try again later
`5xx`	an incident on our side or at a provider — retry with an increasing delay

When a detail starts with a code followed by : (email_not_verified:, plan_feature_required:…), that code is what a script should read; the sentence after it is meant for a human and may change.

A value ClipHeat cannot determine is returned as null, never as 0: check for null before displaying an amount or a duration.

6. Rate limits

Each route has its own allowance of requests, per client. Beyond it: 429.

Route	Allowance	Refill
`POST /api/process`	20	20 / min
`POST /api/batch`	10	10 / min
`POST /api/estimate`	20	20 / min
`POST /api/compose`	30	30 / min
`POST /api/publish`	30	30 / min
`POST /api/smartcut`, `/api/reframe`, `/api/edit-ai`	20	20 / min
`POST /api/media/{job_id}/{index}/link`	60	1 / s
`POST /api/auth/keys`	10	10 / min

POST /api/estimate queries the source platform on every call: estimate once per video, then do your calculations locally with the pricing fields returned. On /api/edit-ai, a 429 means the daily quota is reached.

7. Good practices

Keep the key server-side. Never in a mobile app, a web page or a code repository: anyone who reads it acts on your behalf.
One key per use (a script, an integration): you can revoke one without breaking the others.
Retry with an increasing delay on 429 and 5xx, never in a tight loop.
Don’t restart a generation when in doubt: check its status first. Restarting the same video uses new credits.

The routes — every route, its fields and its responses.
Key security — scope, lifetime, revocation.
MCP server — drive ClipHeat from an assistant (Claude, Cursor…).