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
  1. 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.
  2. Espera. La llamada vuelve cuando el trabajo termina, o al cumplirse el tiempo que indiques.
  3. 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.

CampoSignificado
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

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.

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"
}

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));
}

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

ArchivoQué es
video.mp4Tu video con la nueva banda sonora. La imagen se copia, no se recodifica.
audio.mp3La mezcla final por separado.
cue_sheet.jsonUna fila por cue musical: tramo, qué sonaba, qué suena ahora, similitud, nivel, avisos.
cue_sheet.csvLas mismas filas para una hoja de cálculo o el papeleo de una emisora.
speech_fx.mp3Lo que se conservó del original, sin música. speech.mp3 si conservas solo la voz.
original_music.mp3La música que se quitó, por separado.
replacement_music.mp3La música nueva por separado, ya siguiendo los niveles originales.
music_timeline.csvProbabilidad 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é.

CampoSignificado
start, endSegundos desde el inicio de la entrada.
actionreplaced o removed.
original.howidentified · tagged · detected
original.artist, original.titlePara cues identificados.
original.descriptionPara cues etiquetados: género, ánimo, tempo e instrumentos en palabras.
replacementprovider, track_id, title, artists, genres, bpm, url, prompt, similarity, looped. null si se quitó.
leveloriginal_db, gain_db, range_db. null si se quitó.
flagsspeech_buried (voz dañada ahí) · possible_singing (nunca se reemplaza)
notePor qué se quitó un cue: 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,,

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"
  }
}
HTTPtypeCuándo
400invalid_requestFalta un campo o está fuera de rango. Corrige la petición.
401authenticationSin clave, clave revocada o sesión vencida.
402insufficient_creditsNo hay créditos disponibles: el saldo se agotó o los trabajos en curso lo retienen todo. Recarga, o espera a que terminen.
403permissionClave válida, credencial equivocada (por ejemplo, una clave de API creando claves).
404not_foundTrabajo desconocido, o no es tuyo.
409conflictEl estado no lo permite (cancelar un trabajo terminado).
413payload_too_largeMás de 4 GiB.
429rate_limitedMás despacio. Retry-After indica cuándo.
5xxserverDe 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 subida4 GiB por archivo
FormatosTodo lo que lee ffmpeg; mp4, mov, mkv y webm conservan su contenedor
Ritmo120 peticiones por minuto por cuenta
Enlaces de salidaValen 24 horas; vuelve a pedir el trabajo para renovarlos
RetenciónLos archivos se borran 7 días después de terminar (30 días en Studio y Enterprise); el registro del trabajo se conserva
CobroUn 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 TVResultado
Cues musicales encontrados59
Cues con un candidato del que generar43
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,1515,5 / 32,3 de 56,8 min
Similitud de los cues reemplazados0,26 a 0,48
Canciones identificadas desde la pista vs la mezcla10 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.

Referencia de la API