Clipwright API

One HTTP API that turns a script into a lip-synced UGC video, or a script or a short brief into a faceless video: narration over an opening animated clip and image scenes. 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 for agents that read text. The OpenAPI 3.1 file at https://api.clipwright.io/openapi.json is the machine-readable REST contract, built from the schemas the API validates with.

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 at https://app.clipwright.io/api-keys in the dashboard. 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: 10 credits for every second of finished video, rounded up to the whole second, at least 50 on a video we delivered.
• make_ugc with segments or inserts: 9 credits for every second a face is on screen (22 on a take rendered on OmniHuman), plus 1 for every second of the video and 400 for each live-avatar call still, and at least 50 credits on a video we delivered. A face covered by an insert, overlay, window or template still counts, and a run that delivers no file costs nothing at all. Face time is added up across the whole video and rounded up once, not per segment. These fields need long-form qualification; where it is off they are refused by name before any charge.
• create_actor at quality medium: 4 credits for the portrait (none when it is your own image, passed in portrait; 4 for a view of an existing actor made with from_actor_id) and 8 for each additional format.
• create_actor at quality high: 45 credits for the portrait (none when it is your own image, passed in portrait; 12 for a view of an existing actor made with from_actor_id) and 18 for each additional format.
• make_faceless: 7 credits per picture we generate, 49 for the opening clip and 1 per second of the delivered video, at least 50. The quote for your duration_seconds is the most you pay: 212 at 30 seconds, 356 at 90. Your own pictures are not charged, and captions do not change the price.
• Credits are bought in packs: 1000 credits for $10.00, 2750 credits for $25.00, 6000 credits for $50.00. One pack per payment, no subscription.

Ask before you spend: the quote endpoint of every 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.
• make_faceless: the quote prices the duration_seconds you asked for, which is the most you can pay. The video runs as long as the narration needs, at least 25 seconds (an explainer, just its narration) and usually at most a quarter past that length and 90 seconds; a longer narration runs to its end. You are charged for the length actually delivered, never more than the quote.

What a failed run costs differs by skill too:

• make_ugc from a plain script: a run that failed after the video was ordered is charged. One that failed before it costs nothing, and so does one we stopped, lost or refused ourselves. On the face meter no failure is charged at all.
• create_actor: a failed run costs nothing at all, because no actor reached you.
• make_faceless: a failed run costs nothing, including one we stop ourselves because a step did not meet our checks. A run held for review keeps its credit hold until it is resolved.

Editing prices

A revision of a faceless video is a new run made from an edited document: POST /v1/runs/{id}/revisions/quote prices it for nothing, POST /v1/runs/{id}/revisions starts it.

• A new picture: 7 credits.
• A new opening clip: 49 credits.
• A new opening still and its clip: 56 credits.
• The render of a revision that generates anything: 13 credits, once per revision.
• The render of a revision that generates nothing (a retime, a deletion or your own upload): 13 credits.
• Once paid edits are open, an original can be edited for money for 364 days after it finished.
• Revisions of one original running at once: at most 1. Failed or unfinished: at most 3.
• A revision that delivers is charged its quoted total; one that fails is charged nothing.
• While paid edits are closed, both revision routes answer editing_disabled and charge nothing.

Shot candidate prices

A shot candidate is one picture or clip made for one shot of a faceless video, to keep or discard in a revision: POST /v1/runs/{id}/candidates/quote prices it for nothing, POST /v1/runs/{id}/candidates makes it.

• A candidate picture: 7 credits.
• A candidate opening clip: 49 credits.
• A candidate opening still and its clip: 56 credits.
• Shot candidates of one original running at once: at most 1. Failed or unfinished: at most 3. Revisions are counted apart.
• A delivered candidate is charged its one unit whether it is kept or discarded; one that fails is charged nothing.
• While shot candidates are closed, the three candidate routes answer editing_disabled and charge nothing.

Endpoints

A run of any 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.

GET /v1/runs/{id}?wait_seconds=N (at most 50) holds the answer until the run succeeds or fails, the wait ends or you disconnect, so no sleep is needed between reads. An unfinished run answers in its current state.

Skills and their input

make_ugc. Start generation of a lip-synced UGC video. 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. A field the renderer does not honor yet says NOT HONORED YET in its description.

Returns a run_id at once; poll get_run with its poll.arguments until 'succeeded' (video_url) or 'failed'. A 'failed' run whose video is still being made can go back to 'queued' and succeed later, named in warnings[]. attempt=2,3,… starts a NEW run for the same input. For a video like a reference reel, use analyze_reference, then plan_reference_remake with its analysis_id.

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. from_actor_id keeps the face (checked; a mismatch costs nothing). With style_reference a portrait that looks like a person in the photo is refused at no charge, and the price is the same. portrait (with gender and approximate_age) becomes the 9:16 portrait at no charge, only the other formats are charged; an image without exactly one face, or with the face cut off, too small or too large, is refused at no charge. A brand mascot drawn with generate_image can be that portrait when its face reads as a human face (a cartoon person); an animal or object mascot is refused, so show it in inserts instead.

make_faceless. Start a paid finished faceless video from a script or brief. You select 30–90 seconds; the video ends with its narration, runs at least 25 seconds (an explainer, as long as its narration) and at most a quarter past the selection, never beyond 90. The video has an opening animated clip and image scenes. Captions are on by default and can be turned off.

It answers a run_id at once; poll get_run with its poll.arguments until 'succeeded' (video_url) or 'failed'. attempt=2,3,… starts a NEW run for the same input.

• A faceless video has no on-camera presenter: narration plays over an opening animated clip and image scenes. Send exactly one of script and brief, the one input_mode names.
• duration_seconds is a target, not a length the video is stretched to: the video ends with its narration, which runs at least 25 seconds (an explainer, just its narration) and usually at most a quarter past duration_seconds and 90 seconds; a longer narration runs to its end. A video more than 5 seconds longer says so in warnings[]. The charge never exceeds the quote.
• Captions drop punctuation, keep accents and other diacritics, and show numbers as written. With captions on, the script is checked against the caption font before speech is made; a character the font cannot draw fails the run without a charge.
• The narration language is detected automatically.
• voice names the narration voice: take a name from GET /v1/voices?skill=make_faceless. Without it the narration is read by narrator_en_wise_lady, and an English explainer by the fastest voice. Choose a voice in the language of the narration. An unknown name, a make_ugc voice and voice_id are refused before any charge: make_faceless speaks only the voices listed for it.
• make_faceless always delivers 1080p in 9:16. When faceless generation is switched off on the server, both of its calls answer paid_render_disabled and nothing is charged.
• A failed run whose error begins with story_not_planned stopped at its first step: the narration could not be planned on that attempt. Nothing was charged, and the same input can be run again under a new Idempotency-Key.

For make_ugc and create_actor, output format follows the request and the source. Supported formats are 9:16, 1:1, 16:9 and resolutions 720p, 1080p; silence means 1080p in 9:16.

Workflows

GET /v1/public/workflows lists which methods can run. The native methods are ugc-product-intro, ugc-faq-answer, faceless-explainer and product-image-story. website-proof-demo and kinetic-launch cannot run yet and remain execution_blocked with reasons.

The shortest path with the CLI starts from a method's own example. Only plan-run spends credits; every command before it is free. Edit the brief before creating the plan, and keep the method pins.

clipwright workflow-show faceless-explainer > method.json
jq '{document: {v: 1, method: {method_id: .descriptor.id, version: .descriptor.version, content_digest: .descriptor.content_digest, capability_digest: .capabilities.content_digest}, brief: .descriptor.example.brief, beats: .descriptor.example.beats, claims: [], assets: []}}' method.json > create.json
clipwright plan-create --file create.json > plan.json
jq '{revision, content_digest}' plan.json > approval.json
clipwright plan-approve wfp_example --file approval.json
clipwright plan-quote wfp_example > quote.json
jq '{revision, content_digest, semantic_input_digest, quote_id, idempotency_key: "workflow-example:1"}' quote.json > launch.json
clipwright plan-run wfp_example --file launch.json
clipwright runs run_example

Replace wfp_example with the plan_id from plan.json and run_example with the run id plan-run prints. A quote expires five minutes after it is issued, so run plan-run soon after plan-quote. For product-image-story, upload each photo with clipwright upload --json. The response gives its upload_id and content_digest; copy them directly into the asset. Add one asset per photo. The uploads command returns the same identity for an earlier upload.

clipwright upload mug-front.jpg --json > upload.json
jq '{instance_id: "mug-front", asset_id: .upload_id, content_digest, anchor: {quote: "overall shape"}, provenance: "owner_supplied", rights: "owner_authorized", purpose: "product_proof"}' upload.json > asset.json

{
  "instance_id": "mug-front",
  "asset_id": "upl_00000000000000000000000000000000",
  "content_digest": "cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc",
  "anchor": {
    "quote": "overall shape"
  },
  "provenance": "owner_supplied",
  "rights": "owner_authorized",
  "purpose": "product_proof"
}

• Create an account-owned plan, save revisions and approve the exact revision and content_digest. Planning and approval charge nothing and start no render. An edited revision needs new approval.
• For an approved plan, POST an empty body to /v1/workflow-plans/{id}/quote. Use its quote_id, revision, content_digest and semantic_input_digest in the run request. Check expires_at before starting a new purchase; it is quote metadata. Idempotency-Key must equal the body's idempotency_key.
• UGC workflow quotes disclose in native_quote.quote.warnings that duration_estimate_sec and credits_estimate are estimates, not a fixed price. Delivered short UGC is charged by its price_lines on the measured video, each rounded up to whole seconds, so a video longer than estimated is charged more than the estimate. Read credits_charged on the completed run. A native quote with long_form_pricing instead uses verified delivered face intervals and its tariff frozen at admission, not total video seconds. Native failure terms still apply.
• The native tariff and failure rules still apply. Faceless duration_seconds selects the duration whose quote caps the charge; measured narration determines delivered duration. Voice, captions and the exact accepted script keep their native settings.
• Bind each supplied image with a distinct instance_id, stable owned upload asset_id, content_digest, rights, provenance, purpose and a nonoverlapping word range or unambiguous quote. Reuse one upload through several instances; temporary signed URLs are resolved at quote and launch.
• Original product proof occupies supported IMAGE shots. The generated opener is illustrative. An exact still-only slideshow, a customer-only opener and arbitrary scene layouts are unavailable when required.
• A protected_area is a rectangle in source fractions. Preflight must preserve it through crop, PAN motion and captions. Unproven image orientation or placement is refused; a generated image never replaces required original proof.
• Protected PNGs with animation or EXIF chunks and JPEGs with any APP1 (EXIF/XMP) segment are refused. Export an upright static copy without that metadata. Coverage uses the native measured 25 fps frame clock.
• Upload retention and the 24-hour signed URL are independent limits; a quote extends neither. Sources and signatures must remain available for rendering and recovery. Accepted replay retains its original sources and signatures.
• A successful launch returns the receipt and its existing native Run. Retry the same accepted request to retrieve that purchase, including after quote expiry or source signing becomes unavailable. Read progress and the delivered video through GET /v1/runs/{id}.
• Private plans belong to the token's account.
• For product-image-story, generated scenes and the opener image use the first two distinct eligible product_proof originals in accepted asset order. The first anchors the product's shape; the second supplies another view. Plan readiness and the native quote disclose the selected count and that generated illustrations may differ. Additional originals keep their exact bound image placements. Recovery of an older paid checkpoint reuses its existing scenes with an explicit warning when original-product conditioning cannot be verified. Revisions and candidates, including kept candidates and later revisions, retain that known conditioning limitation without promising that the old scenes or placements survive the edit.
• Writes reject unknown fields and documents over 256000 JSON bytes. Reads accept future fields and enum values; unknown fields inside a read document are preserved, so an older client refuses an unsupported save instead of erasing intent. Keep accepted raw narration unchanged.
• After a lost save answer, repeat the same explicit base_version/document request. If it already became the current document, the backend returns that revision without resetting approval; a different current document produces workflow_conflict. SDK, MCP and CLI never approve, quote or buy as a side effect of saving.
• GET /v1/runs/{id} may include workflow: its immutable receipt, approved_plan, native state/warnings, actual_output, asset_placements, advisory beat_dispositions, validation_issues and creative_acceptance=not_reviewed. approved_plan leaves out brief.reference_profile, so a poll does not repeat it; what the plan does not reproduce from the reference is in warnings, and GET /v1/workflow-plans/{id} returns the full current revision. The run keeps the purchased revision even after the draft changes. A revision or shot candidate never inherits its ancestor's receipt.
• Verified faceless settlement supplies the artifact digest, format and measured duration even if later optional geometry is missing. Placements require an intact account/run/request-bound checkpoint; missing proof is null with a validation issue. A verified empty placement list is []. Verified UGC delivery supplies the measured final-file format, duration and digest; format comes from measured dimensions, not the request. UGC without byte/format proof, including older runs, has actual_output=null with output_evidence_unavailable; its native video_url remains the result. Historical evidence does not renew an expired download URL or prove human creative acceptance.
• SDK methods are listWorkflows, getWorkflow, createWorkflowPlan, planReferenceRemake, getWorkflowPlan, saveWorkflowPlan, approveWorkflowPlan, quoteWorkflowPlan and runWorkflowPlan; getRun preserves workflow evidence. CLI commands are workflows, workflow-show, plan-create --file, plan-show, plan-save --file, plan-approve --file, plan-quote and plan-run --file. These workflow commands print JSON; files are bounded to 1 MiB before parsing. A plan-show file can be edited and passed to plan-save for the same plan.

Example body for POST /v1/workflow-plans/{id}/run: replace the quote fields with your approved plan's quote and send Idempotency-Key: workflow-example:1.

{
  "quote_id": "wq_example",
  "revision": 1,
  "content_digest": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "semantic_input_digest": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
  "idempotency_key": "workflow-example:1"
}

Starting a run

A paid call carries one header besides the key: Idempotency-Key. POST /v1/skills/make_faceless/run and POST /v1/runs/{id}/revisions and POST /v1/runs/{id}/candidates and POST /v1/skills/make_ugc/run and POST /v1/skills/create_actor/run and POST /v1/workflow-plans/{id}/run and POST /v1/skills/generate_image/run and POST /v1/skills/generate_video/run and POST /v1/reference-analyses and POST /v1/creator-profiles and POST /v1/trend-searches 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
• analysis_enqueue_failed
• aspect_conflict
• asset_cap_exceeded
• asset_ingest_cap_exceeded
• asset_not_found
• asset_not_ready
• assets_disabled
• creator_profile_limited
• creator_profile_not_found
• creator_url_unsupported
• debt_outstanding
• deletion_held
• edit_ceiling_reached
• edit_conflict
• edit_invalid
• editing_disabled
• editing_not_priced
• editing_window_not_set
• feedback_limited
• generations_disabled
• generations_marking_pending
• idempotency_key_required
• idempotency_key_reused
• ingest_enqueue_failed
• insufficient_credits
• insufficient_scope
• internal_error
• invalid_image
• invalid_request
• malformed_body
• no_changes
• not_found
• paid_render_disabled
• payload_too_large
• rate_limited
• reference_analysis_disabled
• reference_analysis_limited
• reference_analysis_not_found
• reference_not_analyzable
• reference_not_usable
• reference_url_unsupported
• rejected_field
• revision_needs_generated_unit
• rights_not_confirmed
• run_media_in_use
• run_not_editable
• run_not_finished
• run_not_found
• script_encoding_lost
• source_aspect_mismatch
• source_not_usable
• trend_search_limited
• trend_search_not_found
• trends_unavailable
• unauthorized
• unknown_field
• unsupported_combination
• unsupported_media_type
• unusable_source
• upload_cap_exceeded
• upload_digest_mismatch
• upload_expired
• upload_in_use
• upload_not_finished
• upload_size_mismatch
• upstream_error
• url_fetch_busy
• url_fetch_failed
• url_fetch_rate_limited
• url_fetch_refused
• url_import_disabled
• workflow_conflict
• workflow_invalid
• workflow_not_ready

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 videos with a presenter and 2 faceless videos are made at once per account; the rest queue and are not refused. When many accounts render at once, a run may also wait its turn behind theirs.
• A refusal by rate limit names the seconds to wait in Retry-After and in the body. Honour the larger of the two.
• 99 inserts per clip, and at most 16 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% delivers about 16 to 22; a shorter script scatters wider, and a different voice moves it.
• 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 adds to the price. 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.
• Accept these make_ugc fields: character, broll_url, disclosure_overlay, 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.