Cliphi Agent API
Ready-to-post clips, one API call
Your agent sends the user's video URL. Cliphi transcribes it, finds the strongest moments, and shows each one as a free preview with captions and branding. The human picks, the agent renders the winners. Processing bills per video minute; previews are always free.
Works from Claude, ChatGPT, or any agent that can call an HTTP API. Please keep a human in the loop before publishing.
Integration surfaces
- REST:
https://www.cliphi.com/api/v1(walkthrough below) - MCP server:
https://www.cliphi.com/api/mcpwith your key as a bearer token (Claude connectors, Cursor, Gemini, n8n's MCP node, and friends) - Machine-readable spec: /cliphi-actions.json (OpenAPI 3.1, also the ChatGPT Actions schema)
Try it right now, no key
One curl, no signup: a real finished job from our house account, in the exact shape your agent will see. The preview page links are live, so you can watch finished-looking clips before you create anything.
curl https://www.cliphi.com/api/v1/demo{
"job_id": "9f2c1b8e-...",
"status": "completed",
"demo": true,
"video": { "title": "A real processed video", "duration_seconds": 1847 },
"moments": [
{
"title": "The strongest moment",
"viral_score": 84,
"preview_page_url": "https://www.cliphi.com/p/...?s=...",
"render_status": "rendered"
}
]
}1. Start a job
curl -X POST https://www.cliphi.com/api/v1/jobs \
-H "X-API-Key: chp_live_..." \
-H "Content-Type: application/json" \
-d '{"video_url": "https://www.youtube.com/watch?v=VIDEO_ID"}'{
"job_id": "9f2c1b8e-...",
"status": "processing",
"status_url": "/api/v1/jobs/9f2c1b8e-...",
"studio_url": "https://www.cliphi.com/studio/project/9f2c1b8e-..."
}2. Preview the strongest moments, free
Jobs run asynchronously and usually finish in a few minutes; live streams record first, up to 1 hour. The finished job lists the strongest detected moments with their scores, transcript excerpts, and a preview page link each. The preview page plays the moment with your captions and branding already applied, so a human can judge the finished look without spending another credit. Previews are free.
curl https://www.cliphi.com/api/v1/jobs/9f2c1b8e-... \
-H "X-API-Key: chp_live_..."{
"job_id": "9f2c1b8e-...",
"status": "completed",
"studio_url": "https://www.cliphi.com/studio/project/9f2c1b8e-...",
"video": { "title": "My podcast ep. 42", "duration_seconds": 3611 },
"clips": [],
"moments": [
{
"moment_id": "m_07",
"title": "The enterprise pricing rant",
"viral_score": 79,
"transcript_excerpt": "and that is why per-seat pricing...",
"preview_url": "https://cdn.cliphi.com/source/....mp4",
"preview_page_url": "https://www.cliphi.com/p/m_07?s=...",
"render_status": "not_rendered",
"render_error": null,
"render_error_code": null,
"rendered_aspect_ratios": []
}
]
}3. Render the winners
Rendering is the purchase: each render call is billed in credits, and the response says how much before the clip exists. Poll the job again and the finished file shows up in clips with the moment marked rendered. Re-rendering the same moment needs an explicit force flag, so an agent cannot double-bill you by accident.
curl -X POST https://www.cliphi.com/api/v1/jobs/9f2c1b8e-.../moments/m_07/render \
-H "X-API-Key: chp_live_..." \
-H "Content-Type: application/json" \
-d '{"aspect_ratio": "9:16"}'{
"job_id": "9f2c1b8e-...",
"moment_id": "m_07",
"status": "rendering",
"aspect_ratio": "9:16",
"estimated_credits": 24.0,
"message": "Render started (9:16). Billed up to 24.0 credits on completion. ...",
"status_url": "/api/v1/jobs/9f2c1b8e-...",
"studio_url": "https://www.cliphi.com/studio/project/9f2c1b8e-..."
}{
"clips": [
{
"clip_id": "m_07_reframed_...",
"moment_id": "m_07",
"title": "The enterprise pricing rant",
"url": "https://cdn.cliphi.com/clips/....mp4",
"aspect_ratio": "9:16",
"created_at": "2026-08-25T10:12:03+00:00"
}
],
"moments": [
{ "moment_id": "m_07", "render_status": "rendered", "rendered_aspect_ratios": ["9:16"] }
]
}When something fails
Every error carries the same three fields: a stable error_code your agent can branch on, a message written to be relayed to a human as is, and a billed flag that says whether money moved (always false on request errors). A failed render shows up as render_status "failed" with render_error inside a normal 200 poll, so agents should branch on fields, not HTTP codes.
{
"detail": {
"error_code": "insufficient_credits",
"message": "Insufficient credits: this render needs about 6.0 credits available (billed up to 4.3), balance is 2.0. Top up at https://www.cliphi.com/pricing.",
"billed": false
}
}Build the GPT in two pastes
In ChatGPT, create a GPT, add an Action, and import the schema from the URL below (or download it and paste the contents). Set authentication to API key with the custom header name X-API-Key, and paste your Cliphi key there. Then paste the instructions block into the GPT's Instructions field. Both artifacts are tested against the live API.
https://www.cliphi.com/cliphi-actions.jsonDownload the Action schema (cliphi-actions.json)
Context:
You are Cliphi Clipper. You turn the user's long videos into ready-to-post vertical clips with captions. Submitting a job bills a small per-minute processing charge; previews are free; rendering is the discretionary spend; every render reports its exact cost and bills only when the clip completes.
Instructions:
1. When the user shares a video link, call createJob with it. Acknowledge right away: processing has started, it takes a few minutes for most videos, and they will also get an email from Cliphi when clips are ready (unless they turned notifications off). Offer the studio_url from the response as the live progress page (it becomes the full editor once clips exist). If the response says already_running, tell the user this video is already being processed and nothing new was charged. If they ask to clip a video that FINISHED earlier, warn that a new job will process and bill again, and confirm before submitting.
2. Poll getJob to track progress. Wait poll_after_seconds between polls. Relay the message field when the user asks how it is going; do not post unprompted status updates every poll.
3. Branch on the status FIELD, not the HTTP code: a response can be HTTP 200 with status "failed". If status is failed, relay message verbatim and stop.
4. When status is completed, present the moments as a numbered list: title, viral score, one line from the transcript, and the preview page link labelled "Watch preview" (free). Mark any moment already rendered in the aspect ratio the user wants (check rendered_aspect_ratios): that clip is already paid for, link it from clips[] instead of re-rendering. A different aspect ratio is a new billable render. Ask which ones to render. Offer studio_url as the place to edit and publish.
5. Only after the user picks, call renderMoment for each pick. State the cost once, from estimated_credits in the response. Never set force without the user explicitly asking to re-render.
6. After rendering starts, poll getJob with wait=40 until the moment's render_status is "rendered" (deliver the clip URL from clips[]) or "failed" (relay render_error verbatim and stop; render_error_code says why; make no claim about whether it was charged). A failed render arrives inside an HTTP 200.
7. On any error response, relay detail.message verbatim. It always says what to do next, and detail.billed says whether anything was charged.
Additional notes:
- If the user says what kind of clips they want ("only the product demo parts", "skip the intro banter"), pass their words as the instructions field on createJob. Detection follows them.
- Mention billing only at decision points (before a render, or when an error says so). Never repeat cost warnings the user has already seen.
- The user picks what gets rendered and published. Never render everything unprompted, and never publish anywhere; hand the user clip links and studio_url instead.
- If the user has no API key yet, show them getDemo (no key needed) so they can see real output first, then point them to https://www.cliphi.com/studio/settings/api-keys.The render action is marked consequential, so ChatGPT asks the user to confirm before each render, exactly where money is spent, and nowhere else. Heads up: choosing "Always allow" in that dialog disables future confirms for renders.
Priced per use, in credits
The API spends the same credits as the Cliphi app: processing is billed per video minute when a job runs, previews are free, and each render is billed per second of finished clip. An agent pays for exactly what it uses. No seats, no separate API plan.
FAQ
How do I get a key?
Sign in and create one in Settings, then API Keys. The key is shown once, is tied to your account and its credit balance, and can be revoked any time.
Can my agent spend all my credits?
Submitting a job reserves processing credits per video minute, charged when it completes; after that, renders are the only billed choice the agent makes. Every render response states its cost before the clip exists, and re-renders need an explicit force flag. Revoking the key stops it instantly.
What about supercuts and threads?
Coming to the same endpoint as new formats. Clips shipped first.
Can the agent publish directly?
Publishing through your connected social accounts is on the roadmap. Today the agent gets clip URLs it can post with any tool you already use.
Not a developer? Use Cliphi from ChatGPT or Claude instead