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.
/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 |
| 401 | ErrorResponse | Missing or invalid credentials |
/v1/jobsAPI key or sessionCreate 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) | string | Any unique string (≤ 200 chars). Repeating it within 24 h returns the first job instead of creating another. |
body · multipart/form-data
| file * | file | The video (mp4, mov, mkv, webm, …). 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) |
| webhook_url | url | Overrides the account default. |
body · application/json
| source_url * | url | Direct http(s) link to the video. Presigned S3/GCS links work. Downloaded server-side before queueing. |
| filename | string | Optional name when the 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 |
| 400 | ErrorResponse | Invalid 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. |
| 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. |
| 409 | ErrorResponse | State does not allow this |
| 413 | ErrorResponse | File over 4 GiB. |
| 429 | ErrorResponse | Slow down; see Retry-After |
/v1/jobs/{id}API key or sessionGet 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) | integer | Seconds to wait for a terminal state. Default 0. |
responses
| 200 | Job | The job |
| 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. Running jobs are canceled first.
parameters
| id * (path) | uuid |
responses
| 204 | Deleted | |
| 401 | ErrorResponse | Missing or invalid credentials |
| 404 | ErrorResponse | Unknown, deleted, or not yours |
/v1/jobs/{id}/cancelAPI key or sessionCancel a job
Queued jobs cancel immediately. Running jobs stop at the next step boundary. 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.
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. 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) | string | One of outputs[].name, e.g. video.mp4. |
| sig (query) | string | |
| exp (query) | integer | Unix seconds. |
| download (query) | '1' | Adds a Content-Disposition attachment header with a friendly filename. |
responses
| 200 | The file | |
| 206 | Partial content | |
| 401 | ErrorResponse | Missing or invalid credentials |
| 404 | ErrorResponse | Unknown, deleted, or not yours |
| 410 | ErrorResponse | Outputs expired (retention is 7 days, 30 on Studio and Enterprise) |
account
Balance, usage, API keys, webhook settings, billing.
/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 |
| 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 |
| 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 (Paddle price ids the dashboard passes to checkout), the current subscription, and a customer-portal link when one exists.
responses
| 200 | Billing | Billing |
| 401 | ErrorResponse | Missing or invalid credentials |
/v1/account/billing/mock-purchaseAPI key or sessionDev 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
| 200 | Account | The account after crediting |
| 400 | ErrorResponse | Invalid input (error.param names the field) |
| 404 | ErrorResponse | Unknown, deleted, or not yours |
meta
Health and machine-readable docs.
/healthzPublicHealth
responses
| 200 | object | OK |
| 503 | ErrorResponse | Dependency down |
/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 |
/webhooks/paddlePublicPaddle webhook receiver
Verifies Paddle-Signature, adds credits on transaction.completed, tracks subscription.*. Idempotent on event_id.
responses
| 200 | Processed or already seen | |
| 400 | ErrorResponse | Invalid input (error.param names the field) |
| 401 | ErrorResponse | Missing or invalid credentials |
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)>. 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
| 200 | Acknowledged |
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_requested | boolean | |
| 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 | |
| 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 | null |
Progress
| step | string | null | extract · detect · separate · identify · match · render · done |
| done | string[] | |
| elapsed_s | number | |
| percent | integer | Estimate 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_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. |
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 |
JobError
| code * | string | |
| message * | string |
JobList
| object * | 'list' | |
| data * | Job[] | |
| has_more * | boolean | |
| next_cursor | string | null |
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 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 | |
| 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 |
| 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 | Paddle price id. 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. |
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 |
| daily * | object[] |
Billing
| plan * | string | |
| prices * | Price[] | |
| subscription | Subscription | null | |
| portal_url | url | null | Paddle customer portal |
| mock * | boolean | True 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 |