Clipwright API

One HTTP API that turns a script into a lip-synced UGC video. It is built to be driven by an agent: every call is a single JSON request, every refusal says what to do next, and nothing is published anywhere. Every word of this page is also one markdown file at https://clipwright.io/docs.md, and a short contract for agents at https://clipwright.io/llms.txt.

Authentication

Every call goes to https://api.clipwright.io and carries the key in one header:

Authorization: Bearer cw_your_key_here

• Keys start with cw_ and are shown once, when they are issued. We keep only a digest, so a lost key is replaced, never recovered.
• Issue and revoke keys in the dashboard at https://app.clipwright.io/api-keys. Revocation takes effect on the next request.
• @clipwright/cli and @clipwright/mcp-server read the key from the environment variable CLIPWRIGHT_API_KEY; @clipwright/sdk takes it as an argument.
• A call without a key, or with a revoked one, is refused with 401 before anything is charged.

What it costs

• make_ugc from a plain script: 30 credits for every second of finished video, rounded up to the whole second.
• make_ugc with segments or inserts: 10 credits for every second a face is on screen, and at least 400 credits on a video we delivered. Seconds without a face cost nothing, and a run that delivers no file costs nothing at all, even when the vendor was already paid. Face time is added up across the whole video and rounded up once, not per segment. These fields need long-form qualification on the deployment; where it is off they are refused by name before any charge.
• create_actor at quality medium: 10 credits for the portrait and 10 for each additional format.
• create_actor at quality high: 20 credits for the portrait and 20 for each additional format.
• Credits are bought in packs: 1000 credits for $10.00, one payment, no subscription.

Ask before you spend: the quote endpoint of either skill charges nothing. What its answer is worth differs by skill.

• make_ugc: the quote is an estimate read off the words of the script. The charge follows what was measured in the finished video — its duration on the plain-script meter, its face seconds on the face meter — so the bill can land above or below the quote.
• create_actor: the quote prices every format you asked for, which is the most you can pay. You are charged for the portrait and for the variants actually published; a format that did not come out is named in warnings[] and costs nothing.

What a failed run costs differs by skill too:

• make_ugc from a plain script: a run that failed after the delivering work reached the vendor is charged. One that failed before it costs nothing, and so does one we stopped, lost or refused ourselves, even when the vendor was already paid. On the face meter no failure is charged at all.
• create_actor: a failed run costs nothing at all, even when the vendor was already paid, because no actor reached you.

Endpoints

A run of either skill is read back from the same place, GET /v1/runs/{id}, and moves through these states: queued, generating, scripting, tts, avatar, compositing, uploading, succeeded, failed.

Skills and their input

make_ugc. Start generation of a lip-synced UGC video. Give a script within the selected speech model's text limit; the actor comes from actor_id (a saved actor from list_actors) or image, otherwise the default actor is used. Format and resolution follow the request and the source, defaulting to 1080x1920. Captions are OPT-IN: ask the user first. Fields the renderer does not honor yet carry a NOT HONORED YET note in their own description — read it instead of guessing.

Call quote_ugc before generating and show the cost. This does NOT wait for the video: it starts the run and returns a run_id IMMEDIATELY. You MUST then poll get_run with that run_id until the state is 'succeeded' (video_url) or 'failed'. A 'failed' run whose paid vendor job we still hold can go back to 'queued' and reach 'succeeded' later; whenever that happens it is named in warnings[]. Pass attempt=2,3,… to deliberately start a NEW run for the same input (retry after a failure).

create_actor. Create a personal actor for this account from words describing a fictional adult: a 9:16 portrait with exactly one face, plus the other requested formats edited from it. Returns a run_id immediately; poll get_run until 'succeeded' (created_actor.actor_id, then pass it as actor_id to make_ugc) or 'failed'. Each published image is charged at the price quote shows; refused descriptions and unusable portraits cost nothing. When generation is switched off the call fails with actor_generation_disabled.

Output format follows the request and the source. Supported formats are 9:16, 1:1, 16:9 and resolutions 720p, 1080p, 4k; silence means 1080p in 9:16.

Starting a run

A paid call carries one header besides the key: Idempotency-Key. POST /v1/skills/make_ugc/run and POST /v1/skills/create_actor/run require it, and a call without it is refused with 400 idempotency_key_required before anything is charged.

• You choose the key, and it is the only thing that tells a retry from a second order. Any unique string will do; keep it for as long as you might resend the call.
• The same key with the same body returns the run it already started and charges nothing a second time. That is what makes an ordinary retry safe.
• The same key with a different body is refused with 409 idempotency_key_reused. Take a new key for a new request instead of editing a request under a key already spent.
• To start a deliberately new run on the same input — a retry after a failure — send a new key. The run you already paid for stays where it is.
• @clipwright/sdk and @clipwright/mcp-server build the key for you out of the client and the input, and turn attempt=2, 3 … into a new one. Over plain HTTP the key is yours to pick.

When a call fails

Every refusal carries an error object with a code and a message. What to do with it follows from the kind of refusal, not from the text:

These are all the codes the API puts in error.code. A code you have not seen before still follows its row above, because the row is chosen by the status:

• account_not_admitted
• actor_creation_limited
• actor_format_unavailable
• actor_generation_disabled
• actor_in_use
• actor_storage_unavailable
• actor_unavailable
• aspect_conflict
• debt_outstanding
• idempotency_key_required
• idempotency_key_reused
• insufficient_credits
• internal_error
• invalid_image
• invalid_request
• malformed_body
• not_found
• paid_render_disabled
• payload_too_large
• rate_limited
• rejected_field
• script_encoding_lost
• unauthorized
• unknown_field
• unsupported_media_type
• unusable_source
• upload_cap_exceeded
• upstream_error

Limits

• 60 paid requests and 300 free ones per 60 seconds. The window is counted per account, not per key, so extra keys buy no extra throughput.
• 3 renders run at once per account; the rest queue and are not refused.
• A refusal by rate limit names the seconds to wait in Retry-After and in the body. Honour the larger of the two.
• 49 inserts per clip, and at most 6 appearances of the actor between them. Both are counted from the word indexes you send, so an input that asks for more is refused before anything is paid for.
• cover_words says how many spoken words an insert covers, counted from the first word of its anchor. The insert ends where the first uncovered word begins, so two inserts whose coverage meets are adjacent and leave no actor shot between them.
• The share of words you leave uncovered decides the share of the clip that shows a face, and it does not move with the voice's speed. Word length does vary: at a 560-word script, asking for 19% delivered 16 to 22 in nine hundred and ninety-seven simulated runs out of a thousand, and stayed inside 15 to 24 in fifty thousand. Those numbers were measured on this profile's voice and at that length; a shorter script scatters wider, and a different voice moves them.
• Two single-word choices change the price, not just the look. An insert anchored at word 0 owns the silence before the first word; anchored at word 1 it leaves an extra appearance of the actor, and every appearance is a separate paid job. Coverage that reaches the last word takes the clip to its end and removes the closing appearance the same way.
• A quote reports the share as estimatedFaceWordShare. Read that field; do not divide estimatedFaceSeconds by estimatedTotalDurationSec. Those two answer different questions — the first is the reserve we hold at the slow end of the speaking range, the second is how long the clip is expected to run — and their ratio is not the share of anything.

What this API will never do

• Publish anything. We return a file and a signed link; where it goes is yours to decide.
• Cancel a started run. There is no endpoint for it: once the vendor has the work, stopping it on our side would not unspend it.
• Accept these fields: character, broll_url, webhook_url. They are refused by name before any charge, not accepted and quietly ignored.
• Change the format or the resolution you asked for without saying so. A mismatch is either snapped with a warning or refused before the paid call.
• Call you back. There are no webhooks: read the run with GET /v1/runs/{id}.
• Show a key a second time, or recover one from a backup.