On this page
Guide
Quickstart
Three requests: create a job, wait for it, download the video and the cue sheet. Replace the key with one from the dashboard.
# 1. Create a job. Returns 202 with the job JSON. Defaults: music=replace, keep=speech_fx, min_similarity=0.25.
curl -s https://api.strikefree.video/v1/jobs \
-H "Authorization: Bearer $STRIKEFREE_KEY" \
-H "Idempotency-Key: ep12-cut-b" \
-F file=@ep12.mp4 -F name="Episode 12"
# 2. Wait up to 120 s; repeat until status is done, failed or canceled.
curl -s "https://api.strikefree.video/v1/jobs/$JOB?wait=120" \
-H "Authorization: Bearer $STRIKEFREE_KEY"
# 3. Download. outputs[].url is pre-signed: no header needed, valid 24 h.
JOB_JSON=$(curl -s "https://api.strikefree.video/v1/jobs/$JOB" -H "Authorization: Bearer $STRIKEFREE_KEY")
echo "$JOB_JSON" | jq -r '.outputs[] | select(.name=="video.mp4") | .url' | xargs curl -s -o ep12-replaced.mp4
echo "$JOB_JSON" | jq -r '.outputs[] | select(.name=="cue_sheet.csv") | .url' | xargs curl -s -o ep12-cues.csv
import requests
API = "https://api.strikefree.video"
H = {"Authorization": "Bearer sf_live_..."}
with open("ep12.mp4", "rb") as f:
job = requests.post(f"{API}/v1/jobs", headers={**H, "Idempotency-Key": "ep12-cut-b"},
files={"file": f}, data={"name": "Episode 12"}).json()
while job["status"] not in ("done", "failed", "canceled"):
job = requests.get(f"{API}/v1/jobs/{job['id']}", headers=H, params={"wait": 120}).json()
if job["status"] == "done":
out = {o["name"]: o["url"] for o in job["outputs"]}
open("ep12-replaced.mp4", "wb").write(requests.get(out["video.mp4"]).content)
open("ep12-cues.csv", "wb").write(requests.get(out["cue_sheet.csv"]).content)
for cue in job["result"]["cues"]:
print(cue["start"], cue["end"], cue["action"], cue["original"].get("title"), (cue.get("replacement") or {}).get("title"))
else:
print(job["error"])
import { openAsBlob } from "node:fs";
import { writeFile } from "node:fs/promises";
const API = "https://api.strikefree.video";
const H = { Authorization: `Bearer ${process.env.STRIKEFREE_KEY}` };
const form = new FormData();
form.append("file", await openAsBlob("ep12.mp4"), "ep12.mp4");
form.append("name", "Episode 12");
let job = await fetch(`${API}/v1/jobs`, { method: "POST", headers: { ...H, "Idempotency-Key": "ep12-cut-b" }, body: form }).then(r => r.json());
while (!["done", "failed", "canceled"].includes(job.status)) {
job = await fetch(`${API}/v1/jobs/${job.id}?wait=120`, { headers: H }).then(r => r.json());
}
const out = Object.fromEntries(job.outputs.map(o => [o.name, o.url]));
await writeFile("ep12-replaced.mp4", Buffer.from(await fetch(out["video.mp4"]).then(r => r.arrayBuffer())));
await writeFile("ep12-cues.csv", await fetch(out["cue_sheet.csv"]).then(r => r.text()));
claude mcp add --transport http strikefree https://api.strikefree.video/mcp \
--header "Authorization: Bearer sf_live_..."
- Create a job with a video file (or a direct URL). The defaults replace the music and keep speech, crowd and effects.
- Wait. The call returns when the job finishes, or after the timeout you set.
- Download the outputs. Links are pre-signed and valid for 24 hours.
Authentication
Create API keys in the dashboard. Send one as a Bearer token or in the X-API-Key header. Keys are shown once and stored hashed.
curl https://api.strikefree.video/v1/account -H "Authorization: Bearer sf_live_..."
# or
curl https://api.strikefree.video/v1/account -H "X-API-Key: sf_live_..."
Keys belong to your account (your Clerk organization, or you). Jobs, credits and settings are shared across the account. Revoking a key takes effect immediately.
Creating or revoking keys and rotating the webhook secret require a dashboard session, not an API key.
Jobs
A job is one video. Send it as JSON with upload: {filename, bytes} and then PUT the bytes in 25 MiB parts (what the dashboard does), as one multipart/form-data request (field file, up to 50 MB), or as JSON with a source_url the server can download: a presigned S3 or GCS link works.
# From a URL, stricter matching: cues under 0.4 similarity are removed instead of replaced.
curl -s https://api.strikefree.video/v1/jobs \
-H "Authorization: Bearer $STRIKEFREE_KEY" -H "Content-Type: application/json" \
-d '{"source_url": "https://bucket.s3.amazonaws.com/ep12.mp4?X-Amz-Signature=...", "min_similarity": 0.4}'
Options: music replace (default) swaps every music cue for a generated soundalike; remove takes the music out and stops there. keep says what stays from the original under the new music: speech_fx (default) keeps speech, crowd and effects; speech keeps speech only. min_similarity (default 0.25) is the bar a candidate must reach, or the cue is removed. max_songs (default 60) is the most songs the job may generate, so the most credits it can cost. duck_db (default -12) sets how far removed music-only stretches are turned down. name and metadata are returned untouched.
| Field | Meaning |
|---|---|
| file | multipart only. The video. video is a legacy alias. |
| source_url | JSON only. Direct http(s) link the server downloads before queueing. |
| music | replace (default) or remove. |
| keep | speech_fx (default): speech, crowd and effects stay under the new music. speech: speech only. |
| min_similarity | 0 to 1, default 0.25. A cue is replaced only when its best candidate scores at least this; otherwise it is removed. |
| max_songs | 1 to 1000, default 60. The most songs the job may generate = the most credits it can cost. Cues past it are removed. |
| duck_db | -60 to 0, default -12. Where music is removed and nobody talks, the original is lowered this much instead of scrubbed. |
| name | Your label, up to 200 characters. |
| metadata | JSON object up to 4 KB, returned untouched. |
| webhook_url | Overrides the account default for this job. |
# Just take the music out, no replacement.
curl -s https://api.strikefree.video/v1/jobs -H "Authorization: Bearer $STRIKEFREE_KEY" -F file=@ep12.mp4 -F music=remove
Status moves uploading (parts upload only), queued, running, then done, failed or canceled. Steps: extract, detect, separate, identify, match, render. Cancel a queued job and it stops at once; a running job stops at the next step boundary.
Credits: a job needs one available credit to be accepted. A replace job holds min(max_songs, credits_available) credits while it runs and never generates more songs than that. When it finishes it is charged one credit per song generated and placed (credits_billed) and the rest of the hold is released. Removed cues, music: remove jobs, failed and canceled jobs cost nothing. GET /v1/account returns credits_balance, credits_held and credits_available; GET /v1/account/meter returns usage per day.
{
"object": "job",
"id": "4fbf3d4a-1b2c-4d5e-8f90-123456789abc",
"status": "done",
"music": "replace",
"keep": "speech_fx",
"min_similarity": 0.25,
"duck_db": -12,
"name": "Episode 12",
"input": { "filename": "ep12.mp4", "bytes": 1834003200, "duration_s": 1977.0 },
"progress": { "step": "done", "done": ["extract", "detect", "separate", "identify", "match", "render"], "elapsed_s": 1412, "percent": 100 },
"result": {
"elapsed_s": 1412, "music_s": 1020.5, "replaced_s": 970.5, "removed_s": 50.0,
"cues": [
{ "start": 0, "end": 50, "action": "removed",
"original": { "how": "tagged", "artist": null, "title": null,
"description": "low-energy mid blues, male vocal, organ, accordion, ~108 bpm" },
"replacement": null, "level": null, "flags": [], "note": "similarity 0.07 below 0.25" },
{ "start": 570, "end": 745, "action": "replaced",
"original": { "how": "identified", "artist": "Nahuel Pennisi", "title": "Mundo" },
"replacement": { "provider": "stable_audio", "track_id": "gen_5b0e8d73",
"title": "Generated take 1 (175 s)", "artists": ["Stable Audio 3"], "genres": ["Acoustic", "Latin Folk"], "bpm": 150,
"url": null, "prompt": "acoustic latin folk, nylon guitar, warm, hopeful, 150 bpm, instrumental",
"similarity": 0.64, "looped": false },
"level": { "original_db": -33.5, "gain_db": -20.6, "range_db": 9.1 }, "flags": [], "note": null }
]
},
"outputs": [
{ "name": "video.mp4", "bytes": 1797000000, "content_type": "video/mp4",
"url": "https://api.strikefree.video/v1/jobs/4fbf.../outputs/video.mp4?sig=...&exp=1762041600" },
{ "name": "cue_sheet.csv", "bytes": 2104, "content_type": "text/csv",
"url": "https://api.strikefree.video/v1/jobs/4fbf.../outputs/cue_sheet.csv?sig=...&exp=1762041600" }
],
"max_songs": 25,
"credits_billed": 1,
"created_at": "2026-11-01T02:14:09Z",
"finished_at": "2026-11-01T02:37:41Z",
"expires_at": "2026-11-08T02:37:41Z"
}
Waiting for a job
Jobs take minutes. Pick the way that fits your code.
wait
Long-poll: add ?wait=120 to GET /v1/jobs/{id}. The server answers as soon as the job finishes, or after 120 seconds with the current state. Loop until the status is terminal.
# 2. Wait up to 120 s; repeat until status is done, failed or canceled.
curl -s "https://api.strikefree.video/v1/jobs/$JOB?wait=120" \
-H "Authorization: Bearer $STRIKEFREE_KEY"
Events
Events: GET /v1/jobs/{id}/events is a text/event-stream. You get progress events, then one of done, failed or canceled, and the stream closes.
curl -N "https://api.strikefree.video/v1/jobs/$JOB/events" -H "Authorization: Bearer $STRIKEFREE_KEY"
event: progress
data: {"id":"4fbf...","status":"running","progress":{"step":"identify","percent":52},...}
event: done
data: {"id":"4fbf...","status":"done","result":{"cues":[...]},"outputs":[...],...}
Webhooks
Webhook: set webhook_url on the job or a default in settings. We POST the job when it finishes, signed with your webhook secret. Reply 2xx quickly and fetch outputs afterwards. Five retries over about 15 hours.
POST https://your.app/hooks/strikefree
StrikeFree-Event: job.completed
StrikeFree-Delivery: 7c1d2a9e-...
StrikeFree-Signature: t=1761955200,v1=5f1a...e9
Content-Type: application/json
{"id":"evt_...","type":"job.completed","created_at":"2026-11-01T02:31:09Z","data":{ ...job }}
Verify the signature header: t is the Unix time, v1 is HMAC-SHA256 of "t.body" with your secret.
import { createHmac, timingSafeEqual } from "node:crypto";
export function verify(rawBody, signatureHeader, secret) {
const parts = Object.fromEntries(signatureHeader.split(",").map((kv) => kv.split("=")));
if (Math.abs(Date.now() / 1000 - Number(parts.t)) > 300) return false; // 5 min tolerance
const expected = createHmac("sha256", secret).update(`${parts.t}.${rawBody}`).digest("hex");
return parts.v1?.length === expected.length && timingSafeEqual(Buffer.from(parts.v1), Buffer.from(expected));
}
import hmac, hashlib, time
def verify(raw_body: bytes, signature_header: str, secret: str) -> bool:
parts = dict(kv.split("=", 1) for kv in signature_header.split(","))
if abs(time.time() - int(parts["t"])) > 300:
return False
expected = hmac.new(secret.encode(), f"{parts['t']}.".encode() + raw_body, hashlib.sha256).hexdigest()
return hmac.compare_digest(parts.get("v1", ""), expected)
Outputs
When a job is done, outputs lists every file with a pre-signed, absolute URL. No auth header needed; links work in a browser and can be handed to another system. They expire after 24 hours, and the files themselves after 7 days (30 on Studio and Enterprise).
| File | What it is |
|---|---|
| video.mp4 | Your video with the new soundtrack. Picture is copied, not re-encoded. |
| audio.mp3 | The final mix on its own. |
| cue_sheet.json | One row per music cue: span, what played, what plays now, similarity, level, flags. |
| cue_sheet.csv | The same rows for a spreadsheet or a broadcaster’s paperwork. |
| speech_fx.mp3 | What was kept from the original, music removed. speech.mp3 when you keep speech only. |
| original_music.mp3 | The music that was taken out, on its own. |
| replacement_music.mp3 | The new music on its own, already following the original levels. |
| music_timeline.csv | Music probability per second. |
The video keeps its container when it is mp4, mov, mkv or webm. The picture is copied; only the audio track is new (AAC 192 kb/s, or Opus for webm). replacement_music.mp3 is only there for music: replace.
# 3. Download. outputs[].url is pre-signed: no header needed, valid 24 h.
JOB_JSON=$(curl -s "https://api.strikefree.video/v1/jobs/$JOB" -H "Authorization: Bearer $STRIKEFREE_KEY")
echo "$JOB_JSON" | jq -r '.outputs[] | select(.name=="video.mp4") | .url' | xargs curl -s -o ep12-replaced.mp4
echo "$JOB_JSON" | jq -r '.outputs[] | select(.name=="cue_sheet.csv") | .url' | xargs curl -s -o ep12-cues.csv
The cue sheet
result.cues lists one row per stretch of music, in order. cue_sheet.json and cue_sheet.csv carry the same rows, so you can hand them to a spreadsheet, a licensing desk or an agent.
original.how tells you how the cue was found. identified: the song was recognised by fingerprint on the separated music stem, and artist and title are filled in. tagged: not recognised; description says what it sounds like in words. detected: found but not analysed (music: remove).
replacement is the track now playing there. provider is stable_audio when it was generated for the cue; then prompt holds the description it was generated from and url is null. similarity is a 0 to 1 score against the original cue. level says where it sits: the original bed’s median level, the gain applied, and how much the bed moved inside the cue; the replacement follows that envelope. When action is removed, replacement is null and note says why.
| Field | Meaning |
|---|---|
| start, end | Seconds into the input. |
| action | replaced or removed. |
| original.how | identified · tagged · detected |
| original.artist, original.title | For identified cues. |
| original.description | For tagged cues: genre, mood, tempo and instruments in words. |
| replacement | provider, track_id, title, artists, genres, bpm, url, prompt, similarity, looped. null when removed. |
| level | original_db, gain_db, range_db. null when removed. |
| flags | speech_buried (voice damaged there) · possible_singing (never replaced) |
| note | Why a cue was removed: similarity 0.07 below 0.25, no candidate, singing, song limit reached (max_songs 10), music: remove. |
start,end,action,how,original_artist,original_title,original_description,replacement_track_id,replacement_title,replacement_artists,replacement_url,similarity,gain_db,flags,note
0,50,removed,tagged,,,"low-energy mid blues, male vocal, organ, accordion, ~108 bpm",,,,,,,,"similarity 0.07 below 0.25"
570,745,replaced,identified,Nahuel Pennisi,Mundo,,gen_5b0e8d73,Generated take 1 (175 s),Stable Audio 3,,0.64,-20.6,,
Errors
Errors are JSON with a stable shape. type tells you how to react; code names the exact problem; param, when present, names the field.
{
"error": {
"type": "insufficient_credits",
"code": "insufficient_credits",
"message": "no credits available (balance 3, 3 held by jobs in progress); buy credits in the dashboard"
}
}
| HTTP | type | When |
|---|---|---|
| 400 | invalid_request | A field is missing or out of range. Fix the request. |
| 401 | authentication | No key, a revoked key, or an expired session. |
| 402 | insufficient_credits | No credit is available: the balance is used up, or running jobs hold all of it. Top up, or wait for them to finish. |
| 403 | permission | Valid key, wrong kind of credential (for example an API key creating keys). |
| 404 | not_found | Unknown job, or not yours. |
| 409 | conflict | The state does not allow it (canceling a finished job). |
| 413 | payload_too_large | Over 4 GiB. |
| 429 | rate_limited | Slow down. Retry-After says when. |
| 5xx | server | Our side. Retry with backoff. |
Idempotency
Networks fail mid-upload. Send an Idempotency-Key header with any unique string; repeating it within 24 hours returns the first job instead of creating a second one. Use it from retry loops, queues and agents.
# 1. Create a job. Returns 202 with the job JSON. Defaults: music=replace, keep=speech_fx, min_similarity=0.25.
curl -s https://api.strikefree.video/v1/jobs \
-H "Authorization: Bearer $STRIKEFREE_KEY" \
-H "Idempotency-Key: ep12-cut-b" \
-F file=@ep12.mp4 -F name="Episode 12"
Limits and retention
| What | Limit |
|---|---|
| Upload size | 4 GiB per file |
| Formats | Anything ffmpeg reads; mp4, mov, mkv and webm keep their container |
| Rate | 120 requests per minute per account |
| Output links | Valid 24 hours; request the job again for fresh ones |
| Retention | Files are deleted 7 days after the job finishes (30 days on Studio and Enterprise); the job record stays |
| Billing | One credit per song generated and placed; removed cues, failed and canceled jobs are free |
Quality and how we measure
We count what we can verify. Identification: on the separated music stem, 10 of 10 TV snippets were recognised; on the original mix, 1 of 10. That is why we identify after separating.
Replacement: on four TV clips (59 minutes) the pipeline found 59 music cues; 43 had something to generate from, 16 did not (singing, too short, nothing to describe). With two generated takes per song, 16 cues passed the default bar of 0.25 and 30 passed 0.15; the rest were removed. Replaced cues scored 0.26 to 0.48. Every cue sheet carries the score.
| In our tests on four TV clips | Result |
|---|---|
| Music cues found | 59 |
| Cues with a candidate to generate from | 43 |
| Replaced at the default bar (0.25) | 16 |
| Replaced at a lower bar (0.15) | 30 |
| Music replaced at 0.25 / at 0.15 | 15.5 / 32.3 of 56.8 min |
| Similarity of replaced cues | 0.26 to 0.48 |
| Songs identified from the stem vs the mix | 10 of 10 vs 1 of 10 |
Where music is removed instead, we run the same detector on the result: on a 16-minute live-concert vlog 2.3% of the music windows were still detectable and 92% of the speech windows stayed intact; on a talk show with a music bed, 1.4% and 99%.
Known limits: speech 10 dB or more under the music comes out damaged (flag speech_buried). Singing on camera is never replaced (flag possible_singing). Show stingers and library beds are often unidentifiable and go through the tag route. A soundalike is not the same song.