OpusClip AI Producer

Bake the caption layer from the subtitle pattern the caller picks; the service writes compositions/narrator_captions.html and transcript-src.json. On a host's project they land in the ingress staging and the result carries host_div for index.html and files ({path, sha256}): place the div, upload the tree, and commit_workspace, adding those entries when you name expected_files, or they stay staged. position, placement, hide_intervals, emphasis_word_ids, font and accent are optional; one model call fills the pattern and emphasis left out. Billing: paid by source length and lane.

build_captions

Write music, beat timing and a ducked audio mix. Requires sections or direction; direction alone requires a stored timeline. Sound effects use the plan's sfx beats. Takes the project lock and returns task_id; get_task reports completion. Repeats start another billed run. Billing: paid, 5 credits per music cue delivered (up to 3), 5 more when a music direction plans them, and 10 more when sound effects land; get_pricing states the amount.

add_music

Judge every file staged for one project and accept all or refuse all; only this call moves a staged file into the workspace a render reads. A composition is refused for external scripts, inline handlers, javascript: URLs, network calls in executable script code, or more than 64 KiB (4 MiB for compositions/narrator_captions.html), because it is served into the project preview beside the page. A sub-composition is also refused when it carries no <template> (missing_composition_template), when its window.__timelines[id] = tl assignment sits after </template> (timeline_outside_template), when it registers a key no host in the file carries (timeline_id_mismatch) - only template content is cloned, so that timeline never registers and the export blocks on it - or when a script binds a literal [data-composition-id=id] selector with a class the host does not carry or :not(.visual-host), or sends a :scope > child query to that root, because the export mount strips the inner root's data-* attributes and only the host carries the id, so that root reads null and the script throws before it registers. A composition's media, stylesheet and mount references (img, video, audio, source, link, data-composition-src) are read from the project root (public/..., styles/..., compositions/...), never from compositions/, because the editor mounts the template into index.html; a ../ path there names a file above the root and is refused as missing_reference. Only a composition's script src is read from its own file (../public/vendor/gsap.min.js), as the export's page load reads it, and a url() inside a .css file is read from that stylesheet. Every file a document or a live style names must be in the workspace or in the same commit, or the round is refused as missing_reference instead of exporting without it; a @font-face src is the exception, since the browser falls back when a face is absent. data-start, data-duration and data-media-start are seconds, and a value that is not a finite number in range (start and media offset at or above 0, duration above 0) is refused as invalid_timing rather than failing the export later. The caption layer, the composition declaring data-composition-id narrator-captions, is accepted only when its words are one inline JSON array declared as const WORDS = [...];, one object per word with double-quoted keys word, start and end (finite seconds on the cut) and group_id (an integer per phrase), because that array is all the editor and a long export read; any other caption layer is refused as invalid_caption_words, whatever the cut's length, with the accepted form and an example in its repair_hint, and build_captions stages a caption layer in that form. A file already committed under public/, and every committed image, video, audio file or font, is never replaced in place: staging different bytes at its path is refused as immutable_asset, so upload the new bytes under a new name and repoint its references in the same round. A document or stylesheet under compositions/, styles/ or fonts/ is replaced as before, within the stylesheet budget: every export re-copies and re-fingerprints them, so one over 1 MiB is stylesheet_too_large, a project past 16 MiB of them is stylesheet_total_bytes, and one past 512 is stylesheet_file_count. Already over a limit, a project still previews, exports and replaces a stylesheet without growing that dimension. A referenced video or audio file no decoder can open is refused as invalid_media naming the element that plays it, and the export refuses the same bytes before it captures. Where the deployment also boots the candidate, a composition whose setup script throws is refused as composition_setup_failed carrying the thrown message, and one that finishes without throwing and still never registers its timeline as composition_timeline_not_registered. A check the server did not run refuses nothing and says so under warnings.A refused round moves nothing and names each offending file with the rule it broke. Returns task_id, agent_page_url and page_url. page_url opens the full product app and is the durable link to give a person in the final reply. agent_page_url opens the editor view for embedded panels; it is not the final delivery link. get_task on that task_id answers this exact round in result: outcome, accepted, issues (code, path, message, retryable, repair_hint), the digest it left, and next_action; succeeded is that verdict rather than the lifecycle, and a refused round is a done task that accepted nothing. list_workspace.last_promote is the latest round only, which the next commit replaces. Two signed uploads to one path are one staged object and the last write wins, so expected_files binds the round to the staged bytes it claims, yours and the ones a stage result named for you (build_captions files): a named file that is absent or changed refuses the round with workspace_upload_missing or workspace_upload_conflict, and a staged file the batch does not name stays staged. A round that changes a composition also proves each one initializes, and any round proves each changed media file opens as media, unless warnings say a check did not run; it never proves the whole tree renders, which start_export runs. An accepted round also lists warnings ({rule, count, message}) for what the tree does that the editor or the export will not follow: timed elements on the root timeline outside a visual host, which play but are not listed or movable as effects; a speaker lane that plays a different cut from the one the audio mix will bake, so the export desyncs; a root audio the editor's player does not resolve (no audio#speaker-audio and no audio.speaker-clip), so the project opens with no player; and a clip inside a composition whose window never meets its host's (a clip's data-start is the host's absolute clock), which never shows. A warning refuses nothing; re-author and commit again. An accepted round becomes a version (source host, this task_id) capturing index.html and the .html and .css under compositions/ and styles/, not fonts or media. base_digest is a digest from list_workspace or last_promote; a base that no longer matches is refused with nothing moved, as 409 with current_digest when already visible and as an outcome stale_base on the round's own verdict when it landed after this call. No base means no comparison. Takes the project lock. A round hydrates the whole workspace before it judges a file, so it is capped at 8 commits per 5 minutes per caller plus a shared server cap; over the cap the reply is a 429 that moved nothing and left every staged file staged. Billing: free.

commit_workspace

Generate a scene restyle cover for each window and write it into the project workspace; a timeline this server built also gets it placed, one you authored does not. Up to 25 windows per call, each start_ms to end_ms spanning 4-10s of output time, non-overlapping; a window out of bounds is refused unbilled. Covers a submitted visual plan reserved are bought after your windows while the hold has room; the rest stay pending. A window already covered is not bought again; an identical window addresses the one it made. Each verdict in get_task.result carries the cover's workspace path, whether the timeline already carries it, how many generations this call charged for it (generations, billed_generated_seconds), and for a refused window its class, the provider's reason, and whether it could ever differ; that window keeps no cover, plays the raw footage, and is terminal: a re-run never re-attempts it. A content filter refusing a recognizable individual refuses every window of that speaker. Billing: paid, 6 credits per started second of video generated, each window once and twice when the identity check rejects its first try, whether or not it ends with a cover, and never for a generation returned in the wrong frame shape; the hold is twice every window sent, and a window already covered, or refused before generating, costs nothing.

generate_scene_restyles

Read what every capability costs, in credits. Each row carries band (free / negligible / paid / expensive), credits per run, and available; a per_unit row also charges credits_per_unit per unit consumed, up to max_units. On a row without per_unit, credits is the whole price per run; read per_unit before quoting a row that has one, because every such row carries credits 0 and quoting that 0 would call a paid step free. billing.metered says whether credits move here; project_id adds that project's spend. available=false rows are not callable. Billing: free.

get_pricing

List what one project's render-engine workspace holds, one page per call; pass next_cursor back as cursor. Each file carries path, size in bytes, and md5, the base64 MD5 the store holds (null means unknown). The listing is recursive under path_prefix and covers only render-engine/index.html, render-engine/compositions/, render-engine/public/, render-engine/styles/, render-engine/fonts/. digest is one token over the whole face on every page, whatever path_prefix or cursor; it changes on any write under the face, the editor's included, and is what base_digest is compared against. A cursor is bound to the digest it was read under: a continuation after the face changed is refused with 409 workspace_changed and paging restarts from the first page. staged (what you uploaded that no commit has accepted, by destination; in no render, visible to nobody) and last_promote (the latest commit_workspace round, which the next commit replaces; a commit's own verdict is get_task's result, null before any round) come on the first page only. Billing: free.

list_workspace

Read project phase, status, active task, optional preferences, and editable readiness. include_spend adds ledger spend; null means unavailable. page_url opens the full product app and is the durable link to give a person in the final reply. agent_page_url opens the editor view for embedded panels; it is not the final delivery link. Billing: free.

get_project

Read the live state of the exact task a mutation on this surface returned. Terminal exactly when status is one of done | failed | cancelled; settled only then. succeeded is the outcome to branch on and done is only the lifecycle: a commit_workspace round that refused every file is done with succeeded false, and answers that round in result (outcome, accepted, issues, next_action). failed carries error, and a failed export's result names what to repair: result.issues (composition_id, path, code, cause) or result.planner (reason, duration_s, max_duration_s, plus file and check when it could not read the tree). Beside it, failure carries a stable code and a repair hint where one is known, and retryable: false means this edit can only fail the same way, null means nobody classified it. stage, heartbeat_at, attempt and typical_duration_seconds describe progress. deferred is an export parked behind a live turn: it starts when that turn ends. Every reply carries page_url, the durable project page: the link a person can be given. wait_seconds holds the call open until the task settles or its status changes; next_data.poll_args is that held call again: one call per wait, no sleep. A terminal task that took a paid hold also carries billing: credits_held is the ceiling it was quoted, and once settled is true, credits_charged is what it actually took and billable_units what that paid for where the price is per unit. A task turns terminal before its charge settles, so settled false means the amount is not known yet and the next poll carries it; billing absent means no user-paid hold. A project's run_status is not this task's outcome. Billing: free.

get_task

Render the project's current editable preview to a downloadable mp4. A render this call starts passes render-tree admission first: a preview that fails it is refused with the blocking issues and no export is created. Admission is capped at 8 per 5 minutes per caller plus a shared server cap; over it the reply is a 429 with no verdict. An export already running, or still fresh for this preview, is returned without admission, and says so in reuse_reason. status deferred means a live turn owns the project and starts the export when it ends. Every reply that started, reused or parked an export carries task_id, current_workspace_digest (the accepted workspace NOW, the same token list_workspace reports), staged_files_present and warnings, so a refused commit, an upload nobody committed and an unchanged workspace no longer read alike. Those fields describe the workspace, not the returned file: this call does not yet tell you which workspace a given mp4 rendered, and naming the one you want is not supported. current_workspace_digest is null when the workspace could not be read, which does not affect the export. The file comes from get_export_url. page_url opens the full product app and is the durable link to give a person in the final reply. agent_page_url opens the editor view for embedded panels; it is not the final delivery link. Billing: free.

start_export

Create an editable project from uploaded footage. Preparation ingests and transcribes the source and builds a playable draft. Requires uploaded bytes at video_ref and an account credit wallet. Returns project_id, task_id, agent_page_url, and page_url, the project's durable page and the one link here to give a person; get_task reports preparation progress. Your source is measured before the hold, so a short video needs only its own price available. Billing: paid, 1 credit per started 327 seconds of the SOURCE you upload, not of the cut, capped at this row's per_unit max_units.

start_transcribe_project