On this page

API reference

StrikeFree API 1.0.0-rc.1 · https://api.strikefree.video · http://localhost:8080 · 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} (or ?wait=120, or SSE, or a webhook) → download outputs[].url.

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, rate_limited, 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.

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

jobs

Create a job, 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
401ErrorResponseMissing or invalid credentials
POST/v1/jobsAPI key or session

Create a job

Send the video as multipart/form-data (field file) or as JSON with a source_url the server can download (direct http(s) link, ≤ 4 GiB). Returns 202 with the job in queued state.

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 within 24 h returns the first job instead of creating another.

body · multipart/form-data

file *fileThe video (mp4, mov, mkv, webm, …). 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)
webhook_urlurlOverrides the account default.

body · application/json

source_url *urlDirect http(s) link to the video. Presigned S3/GCS links work. Downloaded server-side before queueing.
filenamestringOptional name when the 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
400ErrorResponseInvalid input (error.param names the field). Codes include invalid_music, invalid_keep, invalid_min_similarity, invalid_duck_db, invalid_max_songs, missing_file, empty_file, invalid_metadata, invalid_webhook_url, invalid_source_url, source_fetch_failed, unsupported_content_type.
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.
409ErrorResponseState does not allow this
413ErrorResponseFile over 4 GiB.
429ErrorResponseSlow down; see Retry-After
GET/v1/jobs/{id}API key or session

Get a job

With wait, the server holds the request up to that many seconds and returns as soon as the job reaches done, failed or canceled (long-poll). One call instead of a loop.

parameters

id * (path)uuid
wait (query)integerSeconds to wait for a terminal state. Default 0.

responses

200JobThe job
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. Running jobs are canceled first.

parameters

id * (path)uuid

responses

204Deleted
401ErrorResponseMissing or invalid credentials
404ErrorResponseUnknown, deleted, or not yours
POST/v1/jobs/{id}/cancelAPI key or session

Cancel a job

Queued jobs cancel immediately. Running jobs stop at the next step boundary. 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.

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. 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.

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 a Content-Disposition attachment header with a friendly filename.

responses

200The file
206Partial content
401ErrorResponseMissing or invalid credentials
404ErrorResponseUnknown, deleted, or not yours
410ErrorResponseOutputs expired (retention is 7 days, 30 on Studio and Enterprise)

account

Balance, usage, API keys, webhook settings, billing.

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
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
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 (Paddle price ids the dashboard passes to checkout), the current subscription, and a customer-portal link when one exists.

responses

200BillingBilling
401ErrorResponseMissing or invalid credentials
POST/v1/account/billing/mock-purchaseAPI key or session

Dev only — credit a price without Paddle

Enabled only when the server runs with PADDLE_MOCK=1. Returns 404 otherwise.

body · application/json

price_id *string

responses

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

meta

Health and machine-readable docs.

GET/healthzPublic

Health

responses

200objectOK
503ErrorResponseDependency down
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/webhooks/paddlePublic

Paddle webhook receiver

Verifies Paddle-Signature, adds credits on transaction.completed, tracks subscription.*. Idempotent on event_id.

responses

200Processed or already seen
400ErrorResponseInvalid input (error.param names the field)
401ErrorResponseMissing or invalid credentials

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)>. Retries 5× over ~15 h on non-2xx. 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

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

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

Job

object *'job'
id *uuid
status *Status
cancel_requestedboolean
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
metadataobject
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
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_atdatetime | null

Progress

stepstring | nullextract · detect · separate · identify · match · render · done
donestring[]
elapsed_snumber
percentintegerEstimate from the step weights.

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.

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

JobError

code *string
message *string

JobList

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

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 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_hintstringLast 4 chars of the signing secret, e.g. …ab12.
default_keepKeepWhat 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

idstring
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
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 *stringPaddle price id. Pass to checkout.
kind *'pack' | 'subscription'
credits *integerCredits added per purchase (pack) or per billing period (subscription).
planstring | nullPlan granted by a subscription price.

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
daily *object[]

Billing

plan *string
prices *Price[]
subscriptionSubscription | null
portal_urlurl | nullPaddle customer portal
mock *booleanTrue when the server has no Paddle configured.

WebhookEvent

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

ErrorResponse

error *object