En esta página

Referencia de la API

StrikeFree API 2.0.0 · https://api.strikefree.video · http://localhost:8787 · openapi.json

Upload a video that carries music you don't own. StrikeFree finds every music cue, separates it from the speech, identifies the song, generates a new instrumental soundalike and lays it under the speech following the original mix, so the editor's ducking carries over. Cues that cannot be matched with enough confidence are removed instead. Every job returns the new video, the final mix, the stems and a cue sheet: what played, what plays now, how sure we are. music: remove skips the replacement and only takes the music out.

One flow: POST /v1/jobs → poll GET /v1/jobs/{id}?wait=25 (or SSE, or a webhook) → download outputs[].url.

Sending the video. Three ways, one endpoint: - multipart/form-data with field file: one request, files up to 50 MB. - JSON {"upload": {"filename", "bytes"}} for anything bigger (up to 4 GiB): the job is created in state uploading with upload.part_size (25 MiB) and upload.parts; send each part with PUT /v1/jobs/{id}/parts/{n} (raw bytes, every part exactly part_size except the last), then POST /v1/jobs/{id}/parts/complete. The job turns queued. - JSON {"source_url": "https://…"}: a direct link the worker downloads itself (presigned S3/GCS links work).

Auth: Authorization: Bearer sf_live_… (or X-API-Key). Create keys in the dashboard. Dashboard sessions use the same header with a Clerk session token.

Errors: JSON {"error": {"type", "code", "message", "param?"}}. Types: invalid_request, authentication, permission, not_found, conflict, insufficient_credits, payload_too_large, server.

Credits: the billing unit is the credit. 1 credit = 1 song generated and placed in your video. A song that comes back later in the same video is generated once and costs one credit. Cues that are only removed, failed jobs and canceled jobs cost nothing. A job holds up to max_songs credits while it runs and gives back what it did not use when it finishes. GET /v1/account has the balance, GET /v1/account/meter the usage. New accounts get 5 free credits. Credits are bought through Stripe Checkout (POST /v1/account/billing/checkout).

Waiting. GET /v1/jobs/{id}?wait=N holds the request for at most 25 s (larger values are accepted and capped), so loop until the status is done, failed or canceled. GET /v1/jobs/{id}/events (SSE) closes after 50 s; reconnect or fall back to ?wait=. Jobs take minutes.

For agents: /llms.txt has a one-page guide. An MCP server is at POST /mcp (streamable HTTP, JSON responses, same Bearer key; submit_job takes a source_url). Pass Idempotency-Key on job creation so retries never create duplicates.

Worker protocol: the worker tag documents /v1/worker/*, what the GPU box speaks. It needs the worker token, not a customer key.

jobs

Create a job, upload its video, follow it, fetch outputs.

GET/v1/jobsAPI key or session

List jobs

Newest first. Cursor pagination.

parameters

limit (query)integerDefault 20.
cursor (query)stringnext_cursor from the previous page.
status (query)Status
include_deleted (query)'1'Also list jobs you deleted (their files are gone).

responses

200JobListA page of jobs
400ErrorResponseInvalid input (error.param names the field)
401ErrorResponseMissing or invalid credentials
POST/v1/jobsAPI key or session

Create a job

Three request shapes, one endpoint:

1. `multipart/form-data` with the video in field file (video is a legacy alias) and the options as form fields. One request; the file must be ≤ 50 MB (413 file_too_large above). The job starts queued. 2. JSON with `upload` {"filename", "bytes"} (and optional content_type) for files up to 4 GiB. Returns 202 with status: uploading and an upload block: part_size (26214400 = 25 MiB), parts and upload_id. Send the bytes with PUT /v1/jobs/{id}/parts/{n} for n = 1…parts (every part exactly part_size bytes except the last, which carries the remainder), then POST /v1/jobs/{id}/parts/complete with the returned etags. The job turns queued. An upload with no completion for 24 h is canceled (error.code upload_abandoned) and its hold released. 3. JSON with `source_url`: a direct http(s) link (≤ 4 GiB). The job starts queued; the worker downloads the URL when it picks the job up. Links to private or local addresses are refused at that point (source_fetch_failed). Optional filename names the input when the URL has none.

upload and source_url together are rejected (ambiguous_input).

Requires at least one available credit (credits_available on the account). The job places a hold of min(max_songs, credits_available) credits and never generates more songs than that; it is billed when it finishes: one credit per song generated and placed (credits_billed), the rest of the hold is released. Failed and canceled jobs are free. music: remove jobs generate nothing and cost nothing.

parameters

Idempotency-Key (header)stringAny unique string (≤ 200 chars). Repeating it returns the first job (200) instead of creating another.

body · multipart/form-data

file *fileThe video (mp4, mov, mkv, webm, …), ≤ 50 MB in this shape. video is accepted as a legacy alias.
musicMusicreplace: swap each music cue for a new instrumental soundalike (one credit per song); cues that cannot be matched are removed. remove: take the music out and stop there (no credits).
keepKeepWhat stays from the original mix under the new music. speech_fx: speech, crowd, laughter and effects. speech: speech only.
min_similarityMinSimilarityA cue is replaced only when its best candidate's audio similarity (0–1) reaches this value; otherwise it is removed. Raise it to be stricter.
duck_dbDuckDbWhere music is removed rather than replaced and nobody talks, the original is lowered this much (dB) instead of scrubbed, so a music-only stretch does not fall silent.
max_songsMaxSongsThe most songs this job may generate, which is the most credits it can cost. The job holds min(max_songs, credits_available) credits; cues past the cap are removed instead of replaced (cue note says so). Lower it to leave credits free for jobs you run at the same time.
namestringYour label for the job.
metadatastringJSON object (as a string), ≤ 4 KB. Returned untouched.
webhook_urlurlOverrides the account default.

body · application/json

uploadobjectDeclare a file you will send in parts.
content_typestringMIME type of the file, used when upload.filename has no extension.
source_urlurlDirect http(s) link to the video. Presigned S3/GCS links work. Fetched by the worker when the job starts.
filenamestringOptional name when source_url has none.
musicMusicreplace: swap each music cue for a new instrumental soundalike (one credit per song); cues that cannot be matched are removed. remove: take the music out and stop there (no credits).
keepKeepWhat stays from the original mix under the new music. speech_fx: speech, crowd, laughter and effects. speech: speech only.
min_similarityMinSimilarityA cue is replaced only when its best candidate's audio similarity (0–1) reaches this value; otherwise it is removed. Raise it to be stricter.
duck_dbDuckDbWhere music is removed rather than replaced and nobody talks, the original is lowered this much (dB) instead of scrubbed, so a music-only stretch does not fall silent.
max_songsMaxSongsThe most songs this job may generate, which is the most credits it can cost. The job holds min(max_songs, credits_available) credits; cues past the cap are removed instead of replaced (cue note says so). Lower it to leave credits free for jobs you run at the same time.
namestring
metadataobject≤ 4 KB. Returned untouched.
webhook_urlurl

responses

200JobSame Idempotency-Key seen before; the existing job is returned.
202JobJob accepted. status is uploading (JSON upload, with the upload block) or queued (multipart file, source_url).
400ErrorResponseInvalid input (error.param names the field). Codes include invalid_music, invalid_keep, invalid_min_similarity, invalid_duck_db, invalid_max_songs, invalid_name, invalid_metadata, metadata_too_large, invalid_webhook_url, invalid_idempotency_key, missing_input, ambiguous_input, invalid_upload, invalid_source_url, missing_file, multiple_files, empty_file, unsupported_content_type, invalid_json.
401ErrorResponseMissing or invalid credentials
402ErrorResponseNo credit is available to hold (balance used up, or all of it held by jobs in progress). error.type is insufficient_credits.
413ErrorResponsefile_too_large: a one-shot multipart body over 50 MB (use upload), or upload.bytes over 4 GiB.
GET/v1/jobs/{id}API key or session

Get a job

With wait, the server holds the request and returns as soon as the job reaches done, failed or canceled (long-poll). The wait is capped at 25 s server-side whatever you ask for; loop until the status is terminal. While the job is uploading the response carries the upload block.

parameters

id * (path)uuid
wait (query)integerSeconds to wait for a terminal state. Values above 25 are accepted and capped at 25. Default 0.

responses

200JobThe job
400ErrorResponseInvalid input (error.param names the field)
401ErrorResponseMissing or invalid credentials
404ErrorResponseUnknown, deleted, or not yours
DELETE/v1/jobs/{id}API key or session

Delete a job and its files

Removes input and outputs from storage. The job stays in your history as deleted. Uploading and queued jobs are canceled (free); a running job gets cancel_requested and stops at its next step.

parameters

id * (path)uuid

responses

204Deleted
401ErrorResponseMissing or invalid credentials
404ErrorResponseUnknown, deleted, or not yours
PUT/v1/jobs/{id}/parts/{n}API key or session

Upload one part of the video

Raw bytes of part n of a job created with upload. Content-Length must be exactly upload.part_size (26214400) for every part but the last, and bytes − (parts − 1) × part_size for the last one; anything else is 400 part_size. Parts may be sent in any order and in parallel; a part can be re-sent (the last write wins). Keep the returned etag for parts/complete.

parameters

id * (path)uuid
n * (path)integerPart number, 1-based, up to upload.parts.

body · application/octet-stream

responses

200objectPart stored
400ErrorResponseinvalid_part (n out of range) or part_size (wrong Content-Length).
401ErrorResponseMissing or invalid credentials
404ErrorResponseUnknown, deleted, or not yours
409ErrorResponsenot_uploading: the job is not in state uploading (already completed, canceled or deleted).
POST/v1/jobs/{id}/parts/completeAPI key or session

Finish the parts upload

Lists every part with its etag. The parts are assembled into the input and the job turns queued.

parameters

id * (path)uuid

body · application/json

parts *object[]

responses

200JobThe job, now queued
400ErrorResponseinvalid_parts (wrong count or shape) or upload_incomplete (a part is missing or an etag does not match).
401ErrorResponseMissing or invalid credentials
404ErrorResponseUnknown, deleted, or not yours
409ErrorResponsenot_uploading: the job is not in state uploading.
POST/v1/jobs/{id}/cancelAPI key or session

Cancel a job

Uploading and queued jobs cancel immediately. Running jobs stop at the next step boundary (cancel_requested is set). Terminal jobs return 409.

parameters

id * (path)uuid

responses

200JobThe job: status canceled, or still running with cancel_requested set
401ErrorResponseMissing or invalid credentials
404ErrorResponseUnknown, deleted, or not yours
409ErrorResponseState does not allow this
GET/v1/jobs/{id}/eventsAPI key or session

Follow a job (SSE)

text/event-stream. Events: progress (on every change), then one of done, failed, canceled, after which the stream closes. Each data: line is the full Job JSON. A : keepalive comment is sent every 15 s. The stream also closes after 50 s whatever the state: reconnect, or fall back to GET /v1/jobs/{id}?wait=25.

parameters

id * (path)uuid

responses

200Event stream
401ErrorResponseMissing or invalid credentials
404ErrorResponseUnknown, deleted, or not yours
GET/v1/jobs/{id}/outputs/{name}API key, session, or signed link

Download an output

Streams the file from storage. Accepts the normal Authorization header or the pre-signed sig/exp query pair that outputs[].url already includes (valid 24 h) so links can be opened in a browser or handed to another system. Supports Range (206, Content-Range); sends ETag, Last-Modified, Accept-Ranges.

parameters

id * (path)uuid
name * (path)stringOne of outputs[].name, e.g. video.mp4.
sig (query)string
exp (query)integerUnix seconds.
download (query)'1'Adds Content-Disposition: attachment with a friendly filename (<job name>-<output>).

responses

200The file
206Partial content
401ErrorResponseMissing credentials, or invalid_signature: the link is invalid or expired (fetch the job again for a fresh one).
404ErrorResponseNo such job or output, job deleted, or job not done yet
410ErrorResponseoutputs_expired: outputs were deleted after the retention period (7 days, 30 on Studio and Enterprise)

account

Balance, usage, API keys, webhook settings, billing (Stripe).

GET/v1/accountAPI key or session

Account, plan and balance

responses

200AccountThe account
401ErrorResponseMissing or invalid credentials
PATCH/v1/accountAPI key or session

Update settings

body · application/json

webhook_urlurl | nullDefault webhook for new jobs. null clears it.
default_keepKeepWhat stays from the original mix under the new music. speech_fx: speech, crowd, laughter and effects. speech: speech only.

responses

200AccountThe account
400ErrorResponseInvalid input (error.param names the field)
401ErrorResponseMissing or invalid credentials
GET/v1/account/usageAPI key or session

Credit ledger

Every grant, purchase and charge, newest first. Job rows are negative: one credit per song generated.

parameters

limit (query)integerDefault 50.
cursor (query)string

responses

200UsageListA page of ledger entries
400ErrorResponseInvalid input (error.param names the field)
401ErrorResponseMissing or invalid credentials
GET/v1/account/keysAPI key or session

List API keys

Secrets are never returned after creation; only the prefix.

responses

200objectKeys
401ErrorResponseMissing or invalid credentials
POST/v1/account/keysSession only

Create an API key

Session only (dashboard). An API key cannot mint keys. The secret is shown once.

body · application/json

name *string

responses

201ApiKeyCreatedKey with secret
400ErrorResponseInvalid input (error.param names the field)
401ErrorResponseMissing or invalid credentials
403ErrorResponseValid credentials, not allowed (e.g. API key used where a session is required)
DELETE/v1/account/keys/{keyId}API key or session

Revoke an API key

Session only. Immediate; in-flight requests with the key fail with 401.

parameters

keyId * (path)uuid

responses

204Revoked
401ErrorResponseMissing or invalid credentials
403ErrorResponseValid credentials, not allowed (e.g. API key used where a session is required)
404ErrorResponseUnknown, deleted, or not yours
POST/v1/account/webhook-secretAPI key or session

Rotate the webhook signing secret

Session only. Returns the new secret once. Old signatures stop validating immediately.

responses

200objectNew secret
401ErrorResponseMissing or invalid credentials
403ErrorResponseValid credentials, not allowed (e.g. API key used where a session is required)
GET/v1/account/meterAPI key or session

Usage meter

Where the balance stands (balance, holds, available) and what the last days days used, one row per UTC day (zero-filled, oldest first).

parameters

days (query)integerDefault 30.

responses

200MeterThe meter
400ErrorResponseInvalid input (error.param names the field)
401ErrorResponseMissing or invalid credentials
GET/v1/account/billingAPI key or session

Catalog and subscription

What can be bought (Stripe price ids to pass to checkout), the current subscription, and portal_url: a fresh Stripe customer-portal link when the account already has a Stripe customer (null otherwise, and on servers running without Stripe, where mock is true).

responses

200BillingBilling
401ErrorResponseMissing or invalid credentials
POST/v1/account/billing/checkoutAPI key or session

Start a Stripe Checkout session

Creates a hosted Stripe Checkout session for one catalog price (payment mode for packs, subscription for Studio) and returns its url. Navigate the browser there. Stripe sends the customer back to <web>/app/billing?checkout=success&session_id=… or …?checkout=canceled; the credits land when the checkout.session.completed webhook arrives, usually within seconds. An optional X-User-Email header prefills the email for accounts without a Stripe customer yet.

parameters

X-User-Email (header)stringPrefills Checkout for first-time buyers.

body · application/json

price_id *stringA prices[].id from GET /v1/account/billing.
localestringCheckout language, e.g. es; default auto.

responses

200objectSession created
400ErrorResponseunknown_price: not in the catalog.
401ErrorResponseMissing or invalid credentials
404ErrorResponsecheckout_unavailable: this server runs without Stripe (BILLING_MOCK=1); use mock-purchase.
POST/v1/account/billing/portalAPI key or session

Open the Stripe customer portal

Returns a fresh customer-portal link (invoices, payment method, cancel the subscription). The portal returns to <web>/app/billing.

responses

200objectPortal session created
401ErrorResponseMissing or invalid credentials
404ErrorResponseno_customer (nothing bought yet) or portal_unavailable (server without Stripe).
POST/v1/account/billing/mock-purchaseAPI key or session

Dev only — credit a price without Stripe

Exists only when the server runs without Stripe (BILLING_MOCK=1, or no STRIPE_SECRET_KEY). Returns 404 route_not_found otherwise. The mock catalog has price_mock_pack_20, price_mock_pack_100, price_mock_pack_500 and price_mock_studio.

body · application/json

price_id *string

responses

200AccountThe account after crediting
400ErrorResponseInvalid input (error.param names the field)
401ErrorResponseMissing or invalid credentials
404ErrorResponseUnknown, deleted, or not yours

meta

Health, machine-readable docs, MCP, Stripe webhook receiver.

GET/Public

Where things are

responses

200objectLinks to the docs, this document, the agent guide and the MCP endpoint.
GET/healthzPublic

Health

responses

200HealthOK (ok and db true)
503HealthThe database did not answer (ok false)
GET/openapi.jsonPublic

This document (JSON)

responses

200objectOpenAPI 3.1 document
GET/openapi.yamlPublic

This document (YAML)

responses

200OpenAPI 3.1 document
GET/llms.txtPublic

One-page guide for LLM agents

responses

200Plain text
POST/mcpAPI key, session, or signed link

MCP server (streamable HTTP, JSON responses)

Stateless JSON-RPC 2.0 over POST. Methods: initialize, ping, tools/list, tools/call; notifications/* are accepted with 202 and no body. Batches (JSON arrays) are answered as arrays. tools/call needs the same Authorization: Bearer sf_live_… (or X-API-Key) a REST call would; each tool loops back into the REST routes, so validation, billing and errors are identical.

Tools: submit_job (source_url required; music, keep, min_similarity, max_songs, duck_db, name, metadata, webhook_url, idempotency_key), get_job (id, wait_s ≤ 300: the server loops ?wait=25 for you), list_jobs (status, limit), cancel_job (id), get_account. Results carry a one-line text summary and the REST JSON in structuredContent.

GET /mcp answers 405 (no SSE stream: this server speaks JSON only). There is no local stdio binary; the remote endpoint is the MCP server.

body · application/json

jsonrpc *'2.0'
idinteger | string | null
method *string
paramsobject

responses

200objectJSON-RPC response (result or error)
202Notification accepted, no body
400objectNot JSON
POST/webhooks/stripePublic

Stripe webhook receiver

Verifies Stripe-Signature (HMAC-SHA256 of t.body, 5 min tolerance) against STRIPE_WEBHOOK_SECRET. Handles checkout.session.completed (packs: credits; subscriptions: plan + customer), invoice.paid (monthly credit grant, renewal date), customer.subscription.updated / .deleted / .paused / .resumed (plan and status). Idempotent twice over: by Stripe event id (a replayed event answers duplicate: true) and by checkout session / invoice id in the ledger (the same purchase is never credited twice).

body · application/json

responses

200objectProcessed or already seen
400ErrorResponseInvalid input (error.param names the field)
401ErrorResponseinvalid_signature, or webhooks_disabled when the server has no STRIPE_WEBHOOK_SECRET.

worker

The GPU worker's side of the API (python -m cleancc worker). Authenticated with the shared worker token (Authorization: Bearer <WORKER_TOKEN>); customer credentials are refused. The worker claims a job, pulls its input (or fetches source_url itself), reports progress, pushes outputs into storage and finishes. The finish call bills the credits and queues the customer webhook atomically.

POST/v1/worker/claimAPI key or session

Claim the next job

Atomically moves the oldest highest-priority queued job to running (Studio and Enterprise jobs first) and returns it, or 204 when the queue is empty. Poll every few seconds.

body · application/json

workerstringWho is claiming, e.g. vast-1:4312; recorded on the job.

responses

200objectA job to run
204Nothing queued
401ErrorResponseinvalid_worker_token: worker token missing or wrong
GET/v1/worker/jobs/{id}API key or session

Look at a job

parameters

id * (path)uuid

responses

200objectThe worker view and the current status
401ErrorResponseinvalid_worker_token: worker token missing or wrong
404ErrorResponseUnknown, deleted, or not yours
GET/v1/worker/jobs/{id}/inputAPI key or session

Download the input

Streams the uploaded video from storage; Range supported (206) so an interrupted download resumes. Jobs created with source_url have no stored input (404 input_not_found); fetch the URL yourself and refuse private or local hosts.

parameters

id * (path)uuid

responses

200The input
206Partial content
401ErrorResponseinvalid_worker_token: worker token missing or wrong
404ErrorResponseUnknown, deleted, or not yours
POST/v1/worker/jobs/{id}/progressAPI key or session

Report progress, learn about cancellation

Stores progress (only while the job is running), optionally duration_s and input_bytes once the file has been read. Always answers the current status and cancel_requested; the worker polls it between sub-steps and stops when it is true.

parameters

id * (path)uuid

body · application/json

stepstring | nullCurrent step: extract · detect · separate · identify · match · render.
donestring[]Steps finished so far.
elapsed_snumber
duration_snumberLength of the input in seconds.
input_bytesintegerSize of the input (for source_url jobs, unknown until fetched).

responses

200objectCurrent state
401ErrorResponseinvalid_worker_token: worker token missing or wrong
404ErrorResponseUnknown, deleted, or not yours
POST/v1/worker/jobs/{id}/outputs/{name}API key or session

Store an output (one request)

Raw body, Content-Length required, ≤ 50 MB (413 output_too_large above; use the multipart route). Content-Type is stored when sent, otherwise derived from the name.

parameters

id * (path)uuid
name * (path)stringOutput file name: letters, digits, dot, dash, underscore; e.g. video.mp4, cue_sheet.json.

body · */*

responses

200OutputMetaStored
400ErrorResponseinvalid_output_name or length_required.
401ErrorResponseinvalid_worker_token: worker token missing or wrong
404ErrorResponseUnknown, deleted, or not yours
413ErrorResponseoutput_too_large: over 50 MB.
POST/v1/worker/jobs/{id}/outputs/{name}/multipartAPI key or session

Start a multipart output upload

For outputs over 50 MB. Returns an upload_id; then PUT …/parts/{n}?upload_id= (5 MiB ≤ part ≤ 50 MB, the worker uses 25 MiB) and POST …/complete. Content-Type on this request is stored on the object.

parameters

id * (path)uuid
name * (path)stringOutput file name: letters, digits, dot, dash, underscore; e.g. video.mp4, cue_sheet.json.

responses

200objectUpload opened
400ErrorResponseInvalid input (error.param names the field)
401ErrorResponseinvalid_worker_token: worker token missing or wrong
404ErrorResponseUnknown, deleted, or not yours
PUT/v1/worker/jobs/{id}/outputs/{name}/parts/{n}API key or session

Upload one part of an output

Raw body with Content-Length, ≤ 50 MB (413 part_too_large). Keep the etag.

parameters

id * (path)uuid
name * (path)stringOutput file name: letters, digits, dot, dash, underscore; e.g. video.mp4, cue_sheet.json.
n * (path)integer
upload_id * (query)string

body · application/octet-stream

responses

200objectPart stored
400ErrorResponseInvalid input (error.param names the field)
401ErrorResponseinvalid_worker_token: worker token missing or wrong
404ErrorResponseUnknown, deleted, or not yours
413ErrorResponsepart_too_large
POST/v1/worker/jobs/{id}/outputs/{name}/completeAPI key or session

Finish a multipart output upload

parameters

id * (path)uuid
name * (path)stringOutput file name: letters, digits, dot, dash, underscore; e.g. video.mp4, cue_sheet.json.

body · application/json

upload_id *string
parts *object[]

responses

200OutputMetaStored
400ErrorResponseInvalid input (error.param names the field)
401ErrorResponseinvalid_worker_token: worker token missing or wrong
404ErrorResponseUnknown, deleted, or not yours
POST/v1/worker/jobs/{id}/finishAPI key or session

Finish a job (bills and notifies atomically)

Moves the job to done, failed or canceled and, in the same database batch: counts the songs in result.cues (distinct replacement.track_id among replaced cues), bills min(songs, max_songs) credits (CREDITS_REMOVE_JOB, 0, for music: remove; nothing for failed / canceled), writes the ledger row, sets expires_at (7 days, 30 on Studio and Enterprise) and queues the customer webhook. When outputs is omitted on done, the objects under the job's output prefix are listed and recorded. progress defaults to the stored progress with step: done. A job already terminal answers 409 already_finished; a replayed finish never double-charges.

parameters

id * (path)uuid

body · application/json

status *'done' | 'failed' | 'canceled'
errorstring<code>: <message>; known codes source_fetch_failed, processing_failed, replace_unavailable, canceled, worker_lost become error.code on the job.
resultResultWritten by the worker when the job is done. The same rows are delivered as cue_sheet.json and cue_sheet.csv.
outputsOutputMeta[]
progressProgress

responses

200objectFinished
400ErrorResponseInvalid input (error.param names the field)
401ErrorResponseinvalid_worker_token: worker token missing or wrong
404ErrorResponseUnknown, deleted, or not yours
409ErrorResponsealready_finished
POST/v1/worker/jobs/{id}/resumeAPI key or session

Take a job over (operator use)

Puts a failed, running (lost worker) or queued job back into running under this worker, clearing its error and billing; python -m cleancc worker --resume <id> reuses the steps already on disk. Terminal done / canceled jobs answer 409 not_resumable.

parameters

id * (path)uuid

body · application/json

workerstring

responses

200objectThe job, running again
401ErrorResponseinvalid_worker_token: worker token missing or wrong
404ErrorResponseUnknown, deleted, or not yours
409ErrorResponsenot_resumable

Webhook payload

POST(your webhook_url)Public

Job finished

Sent to the job's webhook_url (or the account default) when a job reaches done, failed or canceled. Headers: StrikeFree-Event (job.completed | job.failed | job.canceled), StrikeFree-Delivery (unique id), StrikeFree-Signature: t=<unix>,v1=<hex hmac-sha256(secret, t + "." + body)>, User-Agent: strikefree-webhooks/1. Delivered within a minute of finishing (a cron runs every minute); on non-2xx or a 10 s timeout it retries at 1 m, 5 m, 30 m, 2 h and 12 h (5 attempts over ~15 h), then gives up. Reply 2xx fast; fetch outputs afterwards.

body · application/json

id *string
type *'job.completed' | 'job.failed' | 'job.canceled'
created_at *datetime
data *Job

responses

200Acknowledged

Schemas

Health

ok *boolean
db *booleanThe database answered.
time *datetime

Music

replace: swap each music cue for a new instrumental soundalike (one credit per song); cues that cannot be matched are removed. remove: take the music out and stop there (no credits).

'replace' | 'remove'

Keep

What stays from the original mix under the new music. speech_fx: speech, crowd, laughter and effects. speech: speech only.

'speech_fx' | 'speech'

MaxSongs

The most songs this job may generate, which is the most credits it can cost. The job holds min(max_songs, credits_available) credits; cues past the cap are removed instead of replaced (cue note says so). Lower it to leave credits free for jobs you run at the same time.

integer

MinSimilarity

A cue is replaced only when its best candidate's audio similarity (0–1) reaches this value; otherwise it is removed. Raise it to be stricter.

number

DuckDb

Where music is removed rather than replaced and nobody talks, the original is lowered this much (dB) instead of scrubbed, so a music-only stretch does not fall silent.

number

Status

uploading (parts still expected) → queued → running → done | failed | canceled.

'uploading' | 'queued' | 'running' | 'done' | 'failed' | 'canceled'

Upload

Present while status is uploading.

part_size *'26214400'Bytes per part (25 MiB). Every part but the last must be exactly this size.
parts *integerNumber of parts: ceil(bytes / part_size).
upload_id *stringStorage upload id; informational, the API tracks it for you.

Job

object *'job'
id *uuid
status *Statusuploading (parts still expected) → queued → running → done | failed | canceled.
cancel_requested *booleanA cancel arrived while running; the worker stops at its next step.
music *Musicreplace: swap each music cue for a new instrumental soundalike (one credit per song); cues that cannot be matched are removed. remove: take the music out and stop there (no credits).
keep *KeepWhat stays from the original mix under the new music. speech_fx: speech, crowd, laughter and effects. speech: speech only.
min_similarity *number
duck_db *number
namestring | null
metadata *object
input *object
progress *Progress
resultResult | null
outputsOutput[]Present when done (empty after expiry).
errorJobError | null
max_songsinteger | nullThe job's credit hold: the most songs it may generate. Set at creation to min(requested max_songs, credits_available); 0 for music: remove.
credits_billedinteger | nullSet when the job is done: songs generated and placed (distinct replacement.track_id among the replaced cues), never above max_songs. null until billed and for failed or canceled jobs.
webhook_urlstring | null
uploadUploadPresent while status is uploading.
created_at *datetime
started_atdatetime | null
finished_atdatetime | null
expires_atdatetime | nullWhen outputs are deleted (7 days after finishing; 30 on Studio and Enterprise).
deleted_atdatetimeOnly on deleted jobs.

Progress

stepstring | nullextract · detect · separate · identify · match · render · done
donestring[]
elapsed_snumber
percentintegerEstimate from the step weights (extract 5, detect 10, separate 35, identify 10, match 15, render 25).

Result

Written by the worker when the job is done. The same rows are delivered as cue_sheet.json and cue_sheet.csv.

elapsed_snumber
music_snumberSeconds of music found in the input.
replaced_snumberSeconds now covered by replacement music.
removed_snumberSeconds where the music was removed instead.
cues *Cue[]

Cue

One stretch of music in the input and what happened to it. The cue sheet is the list of these.

start *numberSeconds into the input.
end *number
action *'replaced' | 'removed'
original *object
replacementobject | nullThe track now playing in this cue. null when the cue was removed.
levelobject | nullHow the replacement was placed. null when the cue was removed.
flags *('speech_buried' | 'possible_singing')[]speech_buried: music was ≥ 10 dB over the speech; expect damaged voice there. possible_singing: someone sings on camera; the cue is never replaced.
notestring | nullWhy a cue was removed: similarity 0.07 below 0.25, no candidate, singing, music: remove.

OutputMeta

One stored output, as the worker reports it.

name *string
bytes *integer
content_type *string

Output

name *stringvideo.<ext> (new soundtrack, picture copied) · audio.mp3 (the final mix) · cue_sheet.json · cue_sheet.csv · speech_fx.mp3 or speech.mp3 (what was kept, music removed) · original_music.mp3 (what was taken out) · replacement_music.mp3 (the new music alone; music: replace only) · music_timeline.csv (music probability per second)
bytes *integer
content_type *string
url *urlPre-signed, absolute, valid 24 h. No auth header needed. Fetch the job again for a fresh one.

JobError

code *string
message *string

JobList

object *'list'
data *Job[]
has_more *boolean
next_cursorstring | null

WorkerJob

What the worker needs to run a job (the customer-facing shape is Job).

id *uuid
music *Musicreplace: swap each music cue for a new instrumental soundalike (one credit per song); cues that cannot be matched are removed. remove: take the music out and stop there (no credits).
keep *KeepWhat stays from the original mix under the new music. speech_fx: speech, crowd, laughter and effects. speech: speech only.
min_similarity *number
duck_db *number
input_name *stringStored object name, input.<ext>; the extension tells the container.
input_bytes *integer
source_url *string | nullWhen set, there is no stored input; the worker fetches this URL.
max_songs *integer | nullNever place more distinct songs than this (the credit hold).
priority *integer1 for Studio and Enterprise accounts.
created_at *datetime

Account

object *'account'
id *stringClerk organization id or user id.
plan *'free' | 'studio' | 'enterprise'
credits_balance *integerCredits owned. 1 credit = 1 song generated. Never negative: a job cannot be billed more than it holds.
credits_held *integerHeld by jobs that are uploading, queued, running or waiting to be billed (sum of their max_songs).
credits_available *integercredits_balance − credits_held: what a new job can hold. New jobs need at least 1.
webhook_urlstring | null
webhook_secret_hint *stringLast 4 chars of the signing secret, e.g. …ab12.
default_keep *KeepWhat stays from the original mix under the new music. speech_fx: speech, crowd, laughter and effects. speech: speech only.
subscriptionSubscription | null
created_at *datetime

Subscription

idstringStripe subscription id.
status'active' | 'trialing' | 'past_due' | 'paused' | 'canceled'
renews_atdatetime | null

UsageEntry

id *uuid
kind *'free_grant' | 'purchase' | 'subscription_grant' | 'job' | 'adjustment'
credits *integerPositive for grants and purchases, negative for jobs (one per song generated).
job_iduuid | null
notestring | null
created_at *datetime

UsageList

object *'list'
data *UsageEntry[]
has_more *boolean
next_cursorstring | null

ApiKey

id *uuid
name *string
prefix *string
created_at *datetime
last_used_atdatetime | null

ApiKeyCreated

id *uuid
name *string
prefix *string
created_at *datetime
last_used_atdatetime | null
secret *stringFull key. Shown once.

Price

id *stringStripe price id (price_…). Pass to checkout.
kind *'pack' | 'subscription'
credits *integerCredits added per purchase (pack) or per billing period (subscription).
plan *string | nullPlan granted by a subscription price (studio); null for packs.

Meter

object *'meter'
credits_balance *integer
credits_held *integer
credits_available *integer
period_days *integer
credits_used *integerCredits charged to jobs in the period (= songs generated).
credits_added *integerGrants and purchases in the period.
jobs *integerJobs billed in the period, including the ones that cost nothing.
daily *object[]

Billing

plan *string
prices *Price[]Packs first, then subscriptions, cheapest first.
subscription *Subscription | null
portal_url *url | nullStripe customer portal link when the account has a Stripe customer; short-lived, fetch again when needed.
mock *booleanTrue when the server runs without Stripe (mock-purchase is available, checkout is not).

WebhookEvent

id *string
type *'job.completed' | 'job.failed' | 'job.canceled'
created_at *datetime
data *Job

ErrorResponse

error *object