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.
/v1/jobsAPI key or sessionList jobs
Newest first. Cursor pagination.
parameters
| limit (query) | integer | Default 20. |
| cursor (query) | string | next_cursor from the previous page. |
| status (query) | Status | |
| include_deleted (query) | '1' | Also list jobs you deleted (their files are gone). |
responses
| 200 | JobList | A page of jobs |
| 400 | ErrorResponse | Invalid input (error.param names the field) |
| 401 | ErrorResponse | Missing or invalid credentials |
/v1/jobsAPI key or sessionCreate 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) | string | Any unique string (≤ 200 chars). Repeating it returns the first job (200) instead of creating another. |
body · multipart/form-data
| file * | file | The video (mp4, mov, mkv, webm, …), ≤ 50 MB in this shape. video is accepted as a legacy alias. |
| music | 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). |
| keep | Keep | What stays from the original mix under the new music. speech_fx: speech, crowd, laughter and effects. speech: speech only. |
| min_similarity | 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. |
| duck_db | 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. |
| max_songs | 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. |
| name | string | Your label for the job. |
| metadata | string | JSON object (as a string), ≤ 4 KB. Returned untouched. |
| webhook_url | url | Overrides the account default. |
body · application/json
| upload | object | Declare a file you will send in parts. |
| content_type | string | MIME type of the file, used when upload.filename has no extension. |
| source_url | url | Direct http(s) link to the video. Presigned S3/GCS links work. Fetched by the worker when the job starts. |
| filename | string | Optional name when source_url has none. |
| music | 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). |
| keep | Keep | What stays from the original mix under the new music. speech_fx: speech, crowd, laughter and effects. speech: speech only. |
| min_similarity | 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. |
| duck_db | 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. |
| max_songs | 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. |
| name | string | |
| metadata | object | ≤ 4 KB. Returned untouched. |
| webhook_url | url |
responses
| 200 | Job | Same Idempotency-Key seen before; the existing job is returned. |
| 202 | Job | Job accepted. status is uploading (JSON upload, with the upload block) or queued (multipart file, source_url). |
| 400 | ErrorResponse | Invalid 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. |
| 401 | ErrorResponse | Missing or invalid credentials |
| 402 | ErrorResponse | No credit is available to hold (balance used up, or all of it held by jobs in progress). error.type is insufficient_credits. |
| 413 | ErrorResponse | file_too_large: a one-shot multipart body over 50 MB (use upload), or upload.bytes over 4 GiB. |
/v1/jobs/{id}API key or sessionGet 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) | integer | Seconds to wait for a terminal state. Values above 25 are accepted and capped at 25. Default 0. |
responses
| 200 | Job | The job |
| 400 | ErrorResponse | Invalid input (error.param names the field) |
| 401 | ErrorResponse | Missing or invalid credentials |
| 404 | ErrorResponse | Unknown, deleted, or not yours |
/v1/jobs/{id}API key or sessionDelete 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
| 204 | Deleted | |
| 401 | ErrorResponse | Missing or invalid credentials |
| 404 | ErrorResponse | Unknown, deleted, or not yours |
/v1/jobs/{id}/parts/{n}API key or sessionUpload 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) | integer | Part number, 1-based, up to upload.parts. |
body · application/octet-stream
responses
| 200 | object | Part stored |
| 400 | ErrorResponse | invalid_part (n out of range) or part_size (wrong Content-Length). |
| 401 | ErrorResponse | Missing or invalid credentials |
| 404 | ErrorResponse | Unknown, deleted, or not yours |
| 409 | ErrorResponse | not_uploading: the job is not in state uploading (already completed, canceled or deleted). |
/v1/jobs/{id}/parts/completeAPI key or sessionFinish 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
| 200 | Job | The job, now queued |
| 400 | ErrorResponse | invalid_parts (wrong count or shape) or upload_incomplete (a part is missing or an etag does not match). |
| 401 | ErrorResponse | Missing or invalid credentials |
| 404 | ErrorResponse | Unknown, deleted, or not yours |
| 409 | ErrorResponse | not_uploading: the job is not in state uploading. |
/v1/jobs/{id}/cancelAPI key or sessionCancel 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
| 200 | Job | The job: status canceled, or still running with cancel_requested set |
| 401 | ErrorResponse | Missing or invalid credentials |
| 404 | ErrorResponse | Unknown, deleted, or not yours |
| 409 | ErrorResponse | State does not allow this |
/v1/jobs/{id}/eventsAPI key or sessionFollow 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
| 200 | Event stream | |
| 401 | ErrorResponse | Missing or invalid credentials |
| 404 | ErrorResponse | Unknown, deleted, or not yours |
/v1/jobs/{id}/outputs/{name}API key, session, or signed linkDownload 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) | string | One of outputs[].name, e.g. video.mp4. |
| sig (query) | string | |
| exp (query) | integer | Unix seconds. |
| download (query) | '1' | Adds Content-Disposition: attachment with a friendly filename (<job name>-<output>). |
responses
| 200 | The file | |
| 206 | Partial content | |
| 401 | ErrorResponse | Missing credentials, or invalid_signature: the link is invalid or expired (fetch the job again for a fresh one). |
| 404 | ErrorResponse | No such job or output, job deleted, or job not done yet |
| 410 | ErrorResponse | outputs_expired: outputs were deleted after the retention period (7 days, 30 on Studio and Enterprise) |
account
Balance, usage, API keys, webhook settings, billing (Stripe).
/v1/accountAPI key or sessionAccount, plan and balance
responses
| 200 | Account | The account |
| 401 | ErrorResponse | Missing or invalid credentials |
/v1/accountAPI key or sessionUpdate settings
body · application/json
| webhook_url | url | null | Default webhook for new jobs. null clears it. |
| default_keep | Keep | What stays from the original mix under the new music. speech_fx: speech, crowd, laughter and effects. speech: speech only. |
responses
| 200 | Account | The account |
| 400 | ErrorResponse | Invalid input (error.param names the field) |
| 401 | ErrorResponse | Missing or invalid credentials |
/v1/account/usageAPI key or sessionCredit ledger
Every grant, purchase and charge, newest first. Job rows are negative: one credit per song generated.
parameters
| limit (query) | integer | Default 50. |
| cursor (query) | string |
responses
| 200 | UsageList | A page of ledger entries |
| 400 | ErrorResponse | Invalid input (error.param names the field) |
| 401 | ErrorResponse | Missing or invalid credentials |
/v1/account/keysAPI key or sessionList API keys
Secrets are never returned after creation; only the prefix.
responses
| 200 | object | Keys |
| 401 | ErrorResponse | Missing or invalid credentials |
/v1/account/keysSession onlyCreate an API key
Session only (dashboard). An API key cannot mint keys. The secret is shown once.
body · application/json
| name * | string |
responses
| 201 | ApiKeyCreated | Key with secret |
| 400 | ErrorResponse | Invalid input (error.param names the field) |
| 401 | ErrorResponse | Missing or invalid credentials |
| 403 | ErrorResponse | Valid credentials, not allowed (e.g. API key used where a session is required) |
/v1/account/keys/{keyId}API key or sessionRevoke an API key
Session only. Immediate; in-flight requests with the key fail with 401.
parameters
| keyId * (path) | uuid |
responses
| 204 | Revoked | |
| 401 | ErrorResponse | Missing or invalid credentials |
| 403 | ErrorResponse | Valid credentials, not allowed (e.g. API key used where a session is required) |
| 404 | ErrorResponse | Unknown, deleted, or not yours |
/v1/account/webhook-secretAPI key or sessionRotate the webhook signing secret
Session only. Returns the new secret once. Old signatures stop validating immediately.
responses
| 200 | object | New secret |
| 401 | ErrorResponse | Missing or invalid credentials |
| 403 | ErrorResponse | Valid credentials, not allowed (e.g. API key used where a session is required) |
/v1/account/meterAPI key or sessionUsage 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) | integer | Default 30. |
responses
| 200 | Meter | The meter |
| 400 | ErrorResponse | Invalid input (error.param names the field) |
| 401 | ErrorResponse | Missing or invalid credentials |
/v1/account/billingAPI key or sessionCatalog 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
| 200 | Billing | Billing |
| 401 | ErrorResponse | Missing or invalid credentials |
/v1/account/billing/checkoutAPI key or sessionStart 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) | string | Prefills Checkout for first-time buyers. |
body · application/json
| price_id * | string | A prices[].id from GET /v1/account/billing. |
| locale | string | Checkout language, e.g. es; default auto. |
responses
| 200 | object | Session created |
| 400 | ErrorResponse | unknown_price: not in the catalog. |
| 401 | ErrorResponse | Missing or invalid credentials |
| 404 | ErrorResponse | checkout_unavailable: this server runs without Stripe (BILLING_MOCK=1); use mock-purchase. |
/v1/account/billing/portalAPI key or sessionOpen the Stripe customer portal
Returns a fresh customer-portal link (invoices, payment method, cancel the subscription). The portal returns to <web>/app/billing.
responses
| 200 | object | Portal session created |
| 401 | ErrorResponse | Missing or invalid credentials |
| 404 | ErrorResponse | no_customer (nothing bought yet) or portal_unavailable (server without Stripe). |
/v1/account/billing/mock-purchaseAPI key or sessionDev 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
| 200 | Account | The account after crediting |
| 400 | ErrorResponse | Invalid input (error.param names the field) |
| 401 | ErrorResponse | Missing or invalid credentials |
| 404 | ErrorResponse | Unknown, deleted, or not yours |
meta
Health, machine-readable docs, MCP, Stripe webhook receiver.
/PublicWhere things are
responses
| 200 | object | Links to the docs, this document, the agent guide and the MCP endpoint. |
/healthzPublicHealth
responses
| 200 | Health | OK (ok and db true) |
| 503 | Health | The database did not answer (ok false) |
/openapi.jsonPublicThis document (JSON)
responses
| 200 | object | OpenAPI 3.1 document |
/openapi.yamlPublicThis document (YAML)
responses
| 200 | OpenAPI 3.1 document |
/llms.txtPublicOne-page guide for LLM agents
responses
| 200 | Plain text |
/mcpAPI key, session, or signed linkMCP 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' | |
| id | integer | string | null | |
| method * | string | |
| params | object |
responses
| 200 | object | JSON-RPC response (result or error) |
| 202 | Notification accepted, no body | |
| 400 | object | Not JSON |
/webhooks/stripePublicStripe 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
| 200 | object | Processed or already seen |
| 400 | ErrorResponse | Invalid input (error.param names the field) |
| 401 | ErrorResponse | invalid_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.
/v1/worker/claimAPI key or sessionClaim 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
| worker | string | Who is claiming, e.g. vast-1:4312; recorded on the job. |
responses
| 200 | object | A job to run |
| 204 | Nothing queued | |
| 401 | ErrorResponse | invalid_worker_token: worker token missing or wrong |
/v1/worker/jobs/{id}API key or sessionLook at a job
parameters
| id * (path) | uuid |
responses
| 200 | object | The worker view and the current status |
| 401 | ErrorResponse | invalid_worker_token: worker token missing or wrong |
| 404 | ErrorResponse | Unknown, deleted, or not yours |
/v1/worker/jobs/{id}/inputAPI key or sessionDownload 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
| 200 | The input | |
| 206 | Partial content | |
| 401 | ErrorResponse | invalid_worker_token: worker token missing or wrong |
| 404 | ErrorResponse | Unknown, deleted, or not yours |
/v1/worker/jobs/{id}/progressAPI key or sessionReport 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
| step | string | null | Current step: extract · detect · separate · identify · match · render. |
| done | string[] | Steps finished so far. |
| elapsed_s | number | |
| duration_s | number | Length of the input in seconds. |
| input_bytes | integer | Size of the input (for source_url jobs, unknown until fetched). |
responses
| 200 | object | Current state |
| 401 | ErrorResponse | invalid_worker_token: worker token missing or wrong |
| 404 | ErrorResponse | Unknown, deleted, or not yours |
/v1/worker/jobs/{id}/outputs/{name}API key or sessionStore 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) | string | Output file name: letters, digits, dot, dash, underscore; e.g. video.mp4, cue_sheet.json. |
body · */*
responses
| 200 | OutputMeta | Stored |
| 400 | ErrorResponse | invalid_output_name or length_required. |
| 401 | ErrorResponse | invalid_worker_token: worker token missing or wrong |
| 404 | ErrorResponse | Unknown, deleted, or not yours |
| 413 | ErrorResponse | output_too_large: over 50 MB. |
/v1/worker/jobs/{id}/outputs/{name}/multipartAPI key or sessionStart 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) | string | Output file name: letters, digits, dot, dash, underscore; e.g. video.mp4, cue_sheet.json. |
responses
| 200 | object | Upload opened |
| 400 | ErrorResponse | Invalid input (error.param names the field) |
| 401 | ErrorResponse | invalid_worker_token: worker token missing or wrong |
| 404 | ErrorResponse | Unknown, deleted, or not yours |
/v1/worker/jobs/{id}/outputs/{name}/parts/{n}API key or sessionUpload 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) | string | Output 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
| 200 | object | Part stored |
| 400 | ErrorResponse | Invalid input (error.param names the field) |
| 401 | ErrorResponse | invalid_worker_token: worker token missing or wrong |
| 404 | ErrorResponse | Unknown, deleted, or not yours |
| 413 | ErrorResponse | part_too_large |
/v1/worker/jobs/{id}/outputs/{name}/completeAPI key or sessionFinish a multipart output upload
parameters
| id * (path) | uuid | |
| name * (path) | string | Output file name: letters, digits, dot, dash, underscore; e.g. video.mp4, cue_sheet.json. |
body · application/json
| upload_id * | string | |
| parts * | object[] |
responses
| 200 | OutputMeta | Stored |
| 400 | ErrorResponse | Invalid input (error.param names the field) |
| 401 | ErrorResponse | invalid_worker_token: worker token missing or wrong |
| 404 | ErrorResponse | Unknown, deleted, or not yours |
/v1/worker/jobs/{id}/finishAPI key or sessionFinish 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' | |
| error | string | <code>: <message>; known codes source_fetch_failed, processing_failed, replace_unavailable, canceled, worker_lost become error.code on the job. |
| result | Result | Written by the worker when the job is done. The same rows are delivered as cue_sheet.json and cue_sheet.csv. |
| outputs | OutputMeta[] | |
| progress | Progress |
responses
| 200 | object | Finished |
| 400 | ErrorResponse | Invalid input (error.param names the field) |
| 401 | ErrorResponse | invalid_worker_token: worker token missing or wrong |
| 404 | ErrorResponse | Unknown, deleted, or not yours |
| 409 | ErrorResponse | already_finished |
/v1/worker/jobs/{id}/resumeAPI key or sessionTake 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
| worker | string |
responses
| 200 | object | The job, running again |
| 401 | ErrorResponse | invalid_worker_token: worker token missing or wrong |
| 404 | ErrorResponse | Unknown, deleted, or not yours |
| 409 | ErrorResponse | not_resumable |
Webhook payload
(your webhook_url)PublicJob 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
| 200 | Acknowledged |
Schemas
Health
| ok * | boolean | |
| db * | boolean | The 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 * | integer | Number of parts: ceil(bytes / part_size). |
| upload_id * | string | Storage upload id; informational, the API tracks it for you. |
Job
| object * | 'job' | |
| id * | uuid | |
| status * | Status | uploading (parts still expected) → queued → running → done | failed | canceled. |
| cancel_requested * | boolean | A cancel arrived while running; the worker stops at its next step. |
| music * | 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). |
| keep * | Keep | What 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 | |
| name | string | null | |
| metadata * | object | |
| input * | object | |
| progress * | Progress | |
| result | Result | null | |
| outputs | Output[] | Present when done (empty after expiry). |
| error | JobError | null | |
| max_songs | integer | null | The 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_billed | integer | null | Set 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_url | string | null | |
| upload | Upload | Present while status is uploading. |
| created_at * | datetime | |
| started_at | datetime | null | |
| finished_at | datetime | null | |
| expires_at | datetime | null | When outputs are deleted (7 days after finishing; 30 on Studio and Enterprise). |
| deleted_at | datetime | Only on deleted jobs. |
Progress
| step | string | null | extract · detect · separate · identify · match · render · done |
| done | string[] | |
| elapsed_s | number | |
| percent | integer | Estimate 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_s | number | |
| music_s | number | Seconds of music found in the input. |
| replaced_s | number | Seconds now covered by replacement music. |
| removed_s | number | Seconds 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 * | number | Seconds into the input. |
| end * | number | |
| action * | 'replaced' | 'removed' | |
| original * | object | |
| replacement | object | null | The track now playing in this cue. null when the cue was removed. |
| level | object | null | How 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. |
| note | string | null | Why 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 * | string | video.<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 * | url | Pre-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_cursor | string | null |
WorkerJob
What the worker needs to run a job (the customer-facing shape is Job).
| id * | uuid | |
| music * | 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). |
| keep * | Keep | What 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 * | string | Stored object name, input.<ext>; the extension tells the container. |
| input_bytes * | integer | |
| source_url * | string | null | When set, there is no stored input; the worker fetches this URL. |
| max_songs * | integer | null | Never place more distinct songs than this (the credit hold). |
| priority * | integer | 1 for Studio and Enterprise accounts. |
| created_at * | datetime |
Account
| object * | 'account' | |
| id * | string | Clerk organization id or user id. |
| plan * | 'free' | 'studio' | 'enterprise' | |
| credits_balance * | integer | Credits owned. 1 credit = 1 song generated. Never negative: a job cannot be billed more than it holds. |
| credits_held * | integer | Held by jobs that are uploading, queued, running or waiting to be billed (sum of their max_songs). |
| credits_available * | integer | credits_balance − credits_held: what a new job can hold. New jobs need at least 1. |
| webhook_url | string | null | |
| webhook_secret_hint * | string | Last 4 chars of the signing secret, e.g. …ab12. |
| default_keep * | Keep | What stays from the original mix under the new music. speech_fx: speech, crowd, laughter and effects. speech: speech only. |
| subscription | Subscription | null | |
| created_at * | datetime |
Subscription
| id | string | Stripe subscription id. |
| status | 'active' | 'trialing' | 'past_due' | 'paused' | 'canceled' | |
| renews_at | datetime | null |
UsageEntry
| id * | uuid | |
| kind * | 'free_grant' | 'purchase' | 'subscription_grant' | 'job' | 'adjustment' | |
| credits * | integer | Positive for grants and purchases, negative for jobs (one per song generated). |
| job_id | uuid | null | |
| note | string | null | |
| created_at * | datetime |
UsageList
| object * | 'list' | |
| data * | UsageEntry[] | |
| has_more * | boolean | |
| next_cursor | string | null |
ApiKey
| id * | uuid | |
| name * | string | |
| prefix * | string | |
| created_at * | datetime | |
| last_used_at | datetime | null |
ApiKeyCreated
| id * | uuid | |
| name * | string | |
| prefix * | string | |
| created_at * | datetime | |
| last_used_at | datetime | null | |
| secret * | string | Full key. Shown once. |
Price
| id * | string | Stripe price id (price_…). Pass to checkout. |
| kind * | 'pack' | 'subscription' | |
| credits * | integer | Credits added per purchase (pack) or per billing period (subscription). |
| plan * | string | null | Plan 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 * | integer | Credits charged to jobs in the period (= songs generated). |
| credits_added * | integer | Grants and purchases in the period. |
| jobs * | integer | Jobs 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 | null | Stripe customer portal link when the account has a Stripe customer; short-lived, fetch again when needed. |
| mock * | boolean | True 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 |