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
  1. Create a job with a video file (or a direct URL). The defaults replace the music and keep speech, crowd and effects.
  2. Wait. The call returns when the job finishes, or after the timeout you set.
  3. 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.

FieldMeaning
filemultipart only. The video. video is a legacy alias.
source_urlJSON only. Direct http(s) link the server downloads before queueing.
musicreplace (default) or remove.
keepspeech_fx (default): speech, crowd and effects stay under the new music. speech: speech only.
min_similarity0 to 1, default 0.25. A cue is replaced only when its best candidate scores at least this; otherwise it is removed.
max_songs1 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.
nameYour label, up to 200 characters.
metadataJSON object up to 4 KB, returned untouched.
webhook_urlOverrides 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.

GET /v1/jobs/{id}
{
  "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));
}

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

FileWhat it is
video.mp4Your video with the new soundtrack. Picture is copied, not re-encoded.
audio.mp3The final mix on its own.
cue_sheet.jsonOne row per music cue: span, what played, what plays now, similarity, level, flags.
cue_sheet.csvThe same rows for a spreadsheet or a broadcaster’s paperwork.
speech_fx.mp3What was kept from the original, music removed. speech.mp3 when you keep speech only.
original_music.mp3The music that was taken out, on its own.
replacement_music.mp3The new music on its own, already following the original levels.
music_timeline.csvMusic 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.

FieldMeaning
start, endSeconds into the input.
actionreplaced or removed.
original.howidentified · tagged · detected
original.artist, original.titleFor identified cues.
original.descriptionFor tagged cues: genre, mood, tempo and instruments in words.
replacementprovider, track_id, title, artists, genres, bpm, url, prompt, similarity, looped. null when removed.
leveloriginal_db, gain_db, range_db. null when removed.
flagsspeech_buried (voice damaged there) · possible_singing (never replaced)
noteWhy a cue was removed: similarity 0.07 below 0.25, no candidate, singing, song limit reached (max_songs 10), music: remove.
cue_sheet.csv
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"
  }
}
HTTPtypeWhen
400invalid_requestA field is missing or out of range. Fix the request.
401authenticationNo key, a revoked key, or an expired session.
402insufficient_creditsNo credit is available: the balance is used up, or running jobs hold all of it. Top up, or wait for them to finish.
403permissionValid key, wrong kind of credential (for example an API key creating keys).
404not_foundUnknown job, or not yours.
409conflictThe state does not allow it (canceling a finished job).
413payload_too_largeOver 4 GiB.
429rate_limitedSlow down. Retry-After says when.
5xxserverOur 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

WhatLimit
Upload size4 GiB per file
FormatsAnything ffmpeg reads; mp4, mov, mkv and webm keep their container
Rate120 requests per minute per account
Output linksValid 24 hours; request the job again for fresh ones
RetentionFiles are deleted 7 days after the job finishes (30 days on Studio and Enterprise); the job record stays
BillingOne 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 clipsResult
Music cues found59
Cues with a candidate to generate from43
Replaced at the default bar (0.25)16
Replaced at a lower bar (0.15)30
Music replaced at 0.25 / at 0.1515.5 / 32.3 of 56.8 min
Similarity of replaced cues0.26 to 0.48
Songs identified from the stem vs the mix10 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.

API reference