En esta página
Guía
Inicio rápido
Tres peticiones: crear un trabajo, esperarlo, descargar el video y la hoja de cues. Reemplaza la clave por una del panel.
# 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_..."
- Crea un trabajo con un archivo de video (o una URL directa). Por defecto se reemplaza la música y se conservan voz, público y efectos.
- Espera. La llamada vuelve cuando el trabajo termina, o al cumplirse el tiempo que indiques.
- Descarga las salidas. Los enlaces vienen prefirmados y valen 24 horas.
Autenticación
Crea claves de API en el panel. Envía una como token Bearer o en la cabecera X-API-Key. Las claves se muestran una sola vez y se guardan con hash.
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_..."
Las claves pertenecen a tu cuenta (tu organización de Clerk, o tú). Trabajos, créditos y ajustes se comparten en la cuenta. Revocar una clave surte efecto de inmediato.
Crear o revocar claves y rotar el secreto de webhooks requiere una sesión del panel, no una clave de API.
Trabajos
Un trabajo es un video. Envíalo como JSON con upload: {filename, bytes} y luego sube los bytes con PUT en partes de 25 MiB (lo que hace el panel), como una sola petición multipart/form-data (campo file, hasta 50 MB), o como JSON con una source_url que el servidor pueda descargar: un enlace prefirmado de S3 o GCS funciona.
# 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}'
Opciones: music replace (por defecto) cambia cada cue musical por una pista parecida generada; remove quita la música y nada más. keep dice qué queda del original bajo la música nueva: speech_fx (por defecto) conserva voz, público y efectos; speech solo la voz. min_similarity (por defecto 0,25) es el umbral que debe alcanzar un candidato, o el cue se quita. max_songs (por defecto 60) es el máximo de canciones que el trabajo puede generar, es decir, el máximo de créditos que puede costar. duck_db (por defecto -12) define cuánto se bajan los tramos de solo música que se quitan. name y metadata se devuelven tal cual.
| Campo | Significado |
|---|---|
| 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
El estado pasa por uploading (solo en la subida por partes), queued, running y luego done, failed o canceled. Pasos: extract, detect, separate, identify, match, render. Cancela un trabajo en cola y se detiene al instante; uno en curso se detiene al terminar el paso actual.
Créditos: un trabajo necesita un crédito disponible para ser aceptado. Un trabajo de reemplazo retiene min(max_songs, credits_available) créditos mientras corre y nunca genera más canciones que eso. Al terminar se le cobra un crédito por canción generada y colocada (credits_billed) y el resto de la retención se libera. Los cues quitados, los trabajos music: remove, los fallidos y los cancelados no cuestan nada. GET /v1/account devuelve credits_balance, credits_held y credits_available; GET /v1/account/meter devuelve el uso por día.
{
"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"
}
Esperar un trabajo
Los trabajos tardan minutos. Elige la forma que encaje con tu código.
wait
Long-poll: agrega ?wait=120 a GET /v1/jobs/{id}. El servidor responde en cuanto el trabajo termina, o a los 120 segundos con el estado actual. Repite hasta que el estado sea final.
# 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
Eventos: GET /v1/jobs/{id}/events es un text/event-stream. Recibes eventos progress y luego uno de done, failed o canceled, y el flujo se cierra.
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: define webhook_url en el trabajo o un valor por defecto en ajustes. Hacemos POST del trabajo cuando termina, firmado con tu secreto. Responde 2xx rápido y descarga las salidas después. Cinco reintentos a lo largo de unas 15 horas.
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 }}
Verifica la cabecera de firma: t es la hora Unix, v1 es HMAC-SHA256 de "t.cuerpo" con tu secreto.
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)
Salidas
Cuando un trabajo está done, outputs lista cada archivo con una URL absoluta y prefirmada. No hace falta cabecera de autenticación; los enlaces abren en el navegador y se pueden pasar a otro sistema. Vencen a las 24 horas, y los archivos a los 7 días (30 en Studio y Enterprise).
| Archivo | Qué es |
|---|---|
| video.mp4 | Tu video con la nueva banda sonora. La imagen se copia, no se recodifica. |
| audio.mp3 | La mezcla final por separado. |
| cue_sheet.json | Una fila por cue musical: tramo, qué sonaba, qué suena ahora, similitud, nivel, avisos. |
| cue_sheet.csv | Las mismas filas para una hoja de cálculo o el papeleo de una emisora. |
| speech_fx.mp3 | Lo que se conservó del original, sin música. speech.mp3 si conservas solo la voz. |
| original_music.mp3 | La música que se quitó, por separado. |
| replacement_music.mp3 | La música nueva por separado, ya siguiendo los niveles originales. |
| music_timeline.csv | Probabilidad de música por segundo. |
El video conserva su contenedor si es mp4, mov, mkv o webm. La imagen se copia; solo la pista de audio es nueva (AAC a 192 kb/s, u Opus para webm). replacement_music.mp3 solo aparece con 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
La hoja de cues
result.cues lista una fila por tramo de música, en orden. cue_sheet.json y cue_sheet.csv llevan las mismas filas, para pasarlas a una hoja de cálculo, al área de licencias o a un agente.
original.how dice cómo se encontró el cue. identified: la canción se reconoció por huella sobre la pista de música separada, y artist y title vienen llenos. tagged: no se reconoció; description dice cómo suena, en palabras. detected: se encontró pero no se analizó (music: remove).
replacement es la pista que suena ahí ahora. provider es stable_audio cuando se generó para el cue; entonces prompt trae la descripción de la que se generó y url es null. similarity es una puntuación de 0 a 1 contra el cue original. level dice dónde queda: el nivel medio de la cortina original, la ganancia aplicada y cuánto se movió la cortina dentro del cue; el reemplazo sigue esa envolvente. Cuando action es removed, replacement es null y note dice por qué.
| Campo | Significado |
|---|---|
| start, end | Segundos desde el inicio de la entrada. |
| action | replaced o removed. |
| original.how | identified · tagged · detected |
| original.artist, original.title | Para cues identificados. |
| original.description | Para cues etiquetados: género, ánimo, tempo e instrumentos en palabras. |
| replacement | provider, track_id, title, artists, genres, bpm, url, prompt, similarity, looped. null si se quitó. |
| level | original_db, gain_db, range_db. null si se quitó. |
| flags | speech_buried (voz dañada ahí) · possible_singing (nunca se reemplaza) |
| note | Por qué se quitó un cue: 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,,
Errores
Los errores son JSON con una forma estable. type dice cómo reaccionar; code nombra el problema exacto; param, cuando aparece, nombra el campo.
{
"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 | Cuándo |
|---|---|---|
| 400 | invalid_request | Falta un campo o está fuera de rango. Corrige la petición. |
| 401 | authentication | Sin clave, clave revocada o sesión vencida. |
| 402 | insufficient_credits | No hay créditos disponibles: el saldo se agotó o los trabajos en curso lo retienen todo. Recarga, o espera a que terminen. |
| 403 | permission | Clave válida, credencial equivocada (por ejemplo, una clave de API creando claves). |
| 404 | not_found | Trabajo desconocido, o no es tuyo. |
| 409 | conflict | El estado no lo permite (cancelar un trabajo terminado). |
| 413 | payload_too_large | Más de 4 GiB. |
| 429 | rate_limited | Más despacio. Retry-After indica cuándo. |
| 5xx | server | De nuestro lado. Reintenta con espera creciente. |
Idempotencia
Las redes fallan a mitad de una subida. Envía una cabecera Idempotency-Key con cualquier cadena única; repetirla dentro de 24 horas devuelve el primer trabajo en vez de crear otro. Úsala en reintentos, colas y agentes.
# 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"
Límites y retención
| Qué | Límite |
|---|---|
| Tamaño de subida | 4 GiB por archivo |
| Formatos | Todo lo que lee ffmpeg; mp4, mov, mkv y webm conservan su contenedor |
| Ritmo | 120 peticiones por minuto por cuenta |
| Enlaces de salida | Valen 24 horas; vuelve a pedir el trabajo para renovarlos |
| Retención | Los archivos se borran 7 días después de terminar (30 días en Studio y Enterprise); el registro del trabajo se conserva |
| Cobro | Un crédito por canción generada y colocada; cues quitados, trabajos fallidos y cancelados son gratis |
Calidad y cómo medimos
Contamos lo que podemos verificar. Identificación: sobre la pista de música separada se reconocieron 10 de 10 fragmentos de TV; sobre la mezcla original, 1 de 10. Por eso identificamos después de separar.
Reemplazo: en cuatro clips de TV (59 minutos) el proceso encontró 59 cues musicales; 43 tenían algo de lo que generar, 16 no (canto, demasiado cortos, nada que describir). Con dos tomas generadas por canción, 16 cues superaron el umbral por defecto de 0,25 y 30 superaron 0,15; el resto se quitó. Los cues reemplazados puntuaron entre 0,26 y 0,48. Cada hoja de cues trae la puntuación.
| En nuestras pruebas con cuatro clips de TV | Resultado |
|---|---|
| Cues musicales encontrados | 59 |
| Cues con un candidato del que generar | 43 |
| Reemplazados con el umbral por defecto (0,25) | 16 |
| Reemplazados con un umbral más bajo (0,15) | 30 |
| Música reemplazada con 0,25 / con 0,15 | 15,5 / 32,3 de 56,8 min |
| Similitud de los cues reemplazados | 0,26 a 0,48 |
| Canciones identificadas desde la pista vs la mezcla | 10 de 10 vs 1 de 10 |
Donde la música se quita en vez de reemplazarse, pasamos el mismo detector sobre el resultado: en un vlog de 16 minutos en un concierto en vivo, el 2,3 % de las ventanas con música seguía siendo detectable y el 92 % de las ventanas con voz quedó intacto; en un programa de entrevistas con cortina, 1,4 % y 99 %.
Límites conocidos: la voz 10 dB o más por debajo de la música sale dañada (aviso speech_buried). Alguien cantando a cámara nunca se reemplaza (aviso possible_singing). Los separadores y cortinas de librería suelen no identificarse y van por la ruta de etiquetas. Un instrumental parecido no es la misma canción.