API v1ProducciónServidor a servidor

Envíe su primer trabajo multimedia en minutos.

Proporciona a MediaRuntime una URL de medios accesible, solicita exactamente las salidas que necesitas y recibe un webhook terminal firmado. Usa el endpoint de carga opcional solo cuando todavía no tengas una URL de origen.

El contrato de un vistazo
1
Fuente
Utilice un medio público o de tiempo limitado URL
2
Enviar
PUBLICAR /v1/jobs con file_url
3
Reconocer
Guarde el job_id devuelto
4
completo
Verificar y procesar el webhook firmado
Inicio rápido

Envíe un medio URL y luego espere el webhook.

MediaRuntime acepta directamente una URL HTTP(S) pública o una URL de lectura firmada y temporal. Debe seguir accesible hasta que el worker descargue la entrada. Un envío correcto devuelve QUEUED de inmediato; las salidas terminadas llegan después mediante tu webhook firmado.

cURL
Enviar un medio existente URL
# Submit a public or time-limited HTTPS source directly.
# Keep the URL fetchable until MediaRuntime has downloaded the input.
curl -sS -X POST "https://mediaruntime.com/v1/jobs" \
  -H "X-API-Key: $MEDIARUNTIME_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "file_url": "https://cdn.example.com/media/launch-trailer.mp4",
    "metadata": { "asset_id": "asset_0426", "media_type": "video" },
    "outputs": [{
      "type": "mp4",
      "preset": "mp4_720p_h264_aac",
      "poster_time_sec": 2
    }]
  }'
Traiga sus medios existentes URL
Configure `file_url` en un HTTP(S) URL público o en un URL de lectura firmado de corta duración desde el almacenamiento que ya utiliza. Debe permanecer accesible a través de la cola y la descarga del código fuente del trabajador. No es necesario que MediaRuntime se convierta en el sistema de registro de sus archivos fuente.
Mantenga job_id como su llave duradera
Consérvelo junto con su propia ID de entidad. Su metadatos se refleja en el webhook, lo que facilita la conciliación.
Bash
Carga opcional para bytes locales.
# Optional: use this when you have local bytes but no fetchable source URL.
UPLOAD=$(curl -sS -X POST "https://mediaruntime.com/v1/upload-url" \
  -H "X-API-Key: $MEDIARUNTIME_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"filename":"launch-trailer.mp4","content_type":"video/mp4"}')

UPLOAD_URL=$(printf '%s' "$UPLOAD" | jq -r .upload_url)
FILE_URI=$(printf '%s' "$UPLOAD" | jq -r .file_uri)
UPLOAD_CONTENT_TYPE=$(printf '%s' "$UPLOAD" | jq -r '.upload_headers["Content-Type"]')
UPLOAD_AUTH=$(printf '%s' "$UPLOAD" | jq -r '.upload_headers.Authorization // empty')

UPLOAD_ARGS=(-H "Content-Type: $UPLOAD_CONTENT_TYPE")
if [[ -n "$UPLOAD_AUTH" ]]; then
  UPLOAD_ARGS+=(-H "Authorization: $UPLOAD_AUTH")
fi
curl -sS -X PUT "$UPLOAD_URL" "${UPLOAD_ARGS[@]}" \
  --upload-file ./launch-trailer.mp4

# Then use "$FILE_URI" as file_url in POST /v1/jobs.
JSON
Respuesta inmediata
{
  "job_id": "job_1320c28b72104811b075a26a99496cf6",
  "status": "QUEUED",
  "tier": "standard",
  "msg": "accepted"
}
Autenticación

Mantenga las claves API en su servidor.

Cree una clave desde Cuenta → Claves API. La clave sin formato se muestra una vez y pertenece a su administrador secreto, nunca al código del navegador, archivos binarios móviles, registros o control de fuente.

encabezado

Envíe X-API-Key en cada solicitud de /v1.

Almacenamiento

Almacene MEDIARUNTIME_API_KEY en un administrador secreto del lado del servidor.

Rotación

Cree un reemplazo, impleméntelo, verifique el tráfico y luego revoque la clave anterior.

X-API-Key: sk_live_…
Crear empleos

Haz que los metadatos resuelvan la integración.

El patrón de producción usado por wMedia es deliberadamente sencillo: envía una entrada, recetas de salida y suficientes metadatos opacos para relacionar el evento terminal con tu propio registro de base de datos.

JSON
Solicitud de estilo de producción
{
  "file_url": "https://cdn.example.com/media/source.mp4",
  "metadata": {
    "producer": "my-api",
    "entity_id": "video_01J8Y4",
    "owner_id": "user_482",
    "media_type": "video",
    "trace_id": "req_f839"
  },
  "moderation": {
    "enabled": true,
    "mode": "report",
    "checks": ["sexual", "violence", "dangerous"]
  },
  "watermark": { "enabled": true },
  "outputs": [
    {
      "type": "mp4",
      "preset": "mp4_720p_h264_aac",
      "path_suffix": "web",
      "poster_time_sec": 2,
      "gif_preview": {
        "enabled": true,
        "width": 320,
        "fps": 8,
        "start_time": 2,
        "duration": 2.5
      }
    },
    {
      "type": "image",
      "preset": "image_multi_v1",
      "path_suffix": "covers",
      "images": [
        { "width": 1280, "height": 720, "mode": "fit", "format": "webp", "quality": 84 },
        { "width": 480, "height": 480, "mode": "cover", "format": "webp", "quality": 80 }
      ]
    }
  ]
}
campo
file_url
Tipo
cuerda
Notas
Un HTTP(S) público, un HTTP(S) firmado por tiempo limitado o una entrada gs:// accesible. Utilice este o entradas, nunca ambos.
campo
inputs
Tipo
matriz
Notas
Distribución por lotes para 1–25 entradas. Cada uno puede llevar input_id y metadatos.
campo
outputs
Tipo
matriz
Notas
1 a 10 recetas de salida. Cada uno requiere tipo; Se recomienda encarecidamente preajuste.
campo
metadata
Tipo
objeto
Notas
Hasta 32 KiB de JSON. Persistió y se hizo eco en meta.request_metadata.
campo
moderation
Tipo
objeto
Notas
Premium visual-media comprobaciones: sexual, violencia, peligrosa.
campo
watermark
Tipo
objeto
Notas
Superposición de medios visuales Premium. La cuenta ya debe tener un logotipo PNG.

Distribución por lotes

Utilice un lote cuando cada entrada necesite el mismo salidas. El metadatos por entrada se fusiona en cada trabajo secundario; el trabajo principal se convierte en su referencia de lote.

JSON
Dos entradas, una receta de salida
{
  "inputs": [
    {
      "file_url": "https://cdn.example.com/a.mp4",
      "input_id": "asset-a",
      "metadata": { "position": 0 }
    },
    {
      "file_url": "https://cdn.example.com/b.mp4",
      "input_id": "asset-b",
      "metadata": { "position": 1 }
    }
  ],
  "metadata": { "batch_id": "import_2026_08_09" },
  "outputs": [{ "type": "mp4", "preset": "mp4_720p_h264_aac" }]
}

Reintentos seguros con Idempotency-Key

Una solicitud con tiempo de espera agotado es ambigua: es posible que el trabajo haya estado en cola y solo se haya perdido la respuesta. Envíe un encabezado Idempotency-Key y volver a intentarlo es seguro: la misma clave devuelve el trabajo original en lugar de hacer cola y cobrar por un segundo. Sin el encabezado, el comportamiento no cambia y cada POST crea un nuevo trabajo.

Bash
Vuelva a intentar el mismo envío de forma segura
# One key per logical job. Generate it in your client, not inside the retry loop.
KEY=$(uuidgen)   # or a deterministic id you can regenerate: asset_0426:mp4_720p:v1

curl -sS -X POST "https://mediaruntime.com/v1/jobs" \
  -H "X-API-Key: $MEDIARUNTIME_API_KEY" \
  -H "Idempotency-Key: $KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "file_url": "https://example.com/source.mp4",
    "metadata": { "asset_id": "asset_0426" },
    "outputs": [{ "type": "mp4", "preset": "mp4_720p_h264_aac" }]
  }'

# Timed out? Send the exact same request again with the SAME key.
# You get the original job_id back - no second job, no second charge.
Tú generas la clave, no nosotros.
MediaRuntime no puede distinguir dos solicitudes por sí solo; solo su cliente sabe que una segunda llamada es un reintento y no un trabajo nuevo. Genere una clave por trabajo lógico y reutilícela en cada reintento de ese trabajo. Generar una clave dentro de su ciclo de reintento le da a cada intento una nueva clave y elimina la protección por completo.

Reglas clave

  • Un UUID funciona; una identificación determinista como asset_0426:mp4_720p:v1 es mejor, porque puedes regenerarla después de un fallo.
  • Las claves se asignan a su cuenta y se respetan durante 24 horas.
  • Reutilizar una clave con un cuerpo diferente devuelve 422, generalmente una clave reutilizada en un bucle.
  • Un reintento enviado mientras el primero todavía está ejecutándose devuelve 409; Vuelva a intentarlo después de un breve retroceso.
  • ¿Enviar el mismo archivo dos veces a propósito? Utilice dos claves diferentes.
Ajustes preestablecidos de salida

Elija el artefacto que desea que produzca el motor.

`type` y `preset` forman una receta ejecutable. Usa el valor exacto de `type` indicado a continuación: un nombre de `preset` por sí solo no cambia el tipo de salida, y una combinación incompatible puede rechazarse o dirigirse de forma incorrecta.

JSON
Vídeo social vertical
{
  "file_url": "https://cdn.example.com/landscape-interview.mp4",
  "outputs": [{
    "type": "social",
    "preset": "social_vertical_blur"
  }]
}
Lo que ejecutan las redes sociales
social_vertical_blur crea un H.264/AAC MP4 de 1080 × 1920. La fuente se escala para ajustarse sin recortar; una copia borrosa llena el lienzo 9:16 detrás de ella. Úselo para Reels, TikTok y Shorts. Es una receta Premium porque la salida vertical tiene 1920 píxeles de alto.

Archivos de vídeo y carteles.

Preestablecido
mp4_720p_h264_aac (type: mp4)
enviar
Vídeo
Ejecución del trabajo
720p H.264/AAC MP4 con inicio rápido para reproducción web.
Nivel básico
Standard
Preestablecido
mp4_ladder_v1 (type: mp4)
enviar
Vídeo
Ejecución del trabajo
Tres interpretaciones de MP4 a 1080p, 720p y 480p, además de un póster para cada interpretación.
Nivel básico
Standard
Preestablecido
transmux_mp4_fast (type: mp4)
enviar
Audio/vídeo compatibles
Ejecución del trabajo
Copia transmisiones existentes en un inicio rápido MP4 sin volver a codificar. Si la copia falla y el respaldo está habilitado, el motor vuelve a codificar con 720p H.264 preajuste.
Nivel básico
Standard
Preestablecido
poster_frame_v1 (type: mp4)
enviar
Vídeo
Ejecución del trabajo
Un JPG de 720p capturado en poster_time_sec. La solicitud tipo sigue siendo mp4.
Nivel básico
Standard
Preestablecido
mp4_hevc_1080p (type: mp4)
enviar
Vídeo
Ejecución del trabajo
1080p HEVC/H.265 + AAC MP4 con la etiqueta hvc1 para reproducción de Apple.
Nivel básico
Premium
Preestablecido
mp4_av1_smart (type: mp4)
enviar
Vídeo
Ejecución del trabajo
1080p AV1 + Opus MP4 optimizado para eficiencia de compresión; La codificación requiere un uso intensivo de la CPU.
Nivel básico
Premium
Preestablecido
mov_prores_422 (type: mp4)
enviar
Vídeo
Ejecución del trabajo
ProRes 422 HQ + PCM MOV maestro de edición. Conserva las dimensiones de origen y produce un archivo intermedio de gran tamaño.
Nivel básico
Premium

Vídeo social

Preestablecido
social_vertical_blur (type: social)
enviar
Vídeo
Ejecución del trabajo
1080×1920 H.264/AAC MP4. Ajusta la fuente sobre un fondo borroso de 9:16 para carretes, TikTok y cortos.
Nivel básico
Premium

Animado GIF

Preestablecido
gif_hq (type: gif)
enviar
Vídeo
Ejecución del trabajo
GIF animado a 480 px de ancho y 15 fps usando generación de paleta para una mejor calidad de color.
Nivel básico
Standard

Extracción de cuadros

Preestablecido
extract_frames_1 (type: frames)
enviar
Vídeo
Ejecución del trabajo
Secuencia de cuadros numerada JPG muestreada a 1 cuadro por segundo.
Nivel básico
Standard
Preestablecido
extract_frames_5 (type: frames)
enviar
Vídeo
Ejecución del trabajo
Secuencia de cuadros numerada JPG muestreada a 5 cuadros por segundo.
Nivel básico
Standard
Preestablecido
scene_detect_v1 (type: frames)
enviar
Ver reglas de entrada
Ejecución del trabajo
Detects shot boundaries and exports one keyframe per shot (scene_00001.jpg…), plus scenes.txt with each boundary's timestamp and score. Frame count equals shot count — a single continuous take yields one.
Nivel básico
Varía
Preestablecido
perceptual_hash_v1 (type: frames)
enviar
Ver reglas de entrada
Ejecución del trabajo
Fingerprints the video by sampling one frame per second and reducing each to a 64-bit dHash, written to phash.json. Compare two videos with Hamming distance to answer “is this the same content?” — it survives re-encoding and rescaling, where a checksum does not. Useful for deduplication and reupload detection. Not crop-invariant.
Nivel básico
Varía

Transmisión

Preestablecido
hls_ladder_v1 (type: hls)
enviar
Vídeo
Ejecución del trabajo
Paquete HLS VOD con variantes H.264/AAC de 1080p y 720p, lista de reproducción maestra y segmentos de 6 segundos.
Nivel básico
Standard

Audio

Preestablecido
audio_copy_fast (type: audio)
enviar
Audio o vídeo con audio.
Ejecución del trabajo
Copia la secuencia de audio de origen sin volver a codificarla. Si la copia falla y el respaldo está habilitado, el motor escribe AAC de 128 kbps en su lugar.
Nivel básico
Standard
Preestablecido
audio_aac_128k (type: audio)
enviar
Audio o vídeo con audio.
Ejecución del trabajo
128 kbps AAC en un archivo M4A de inicio rápido.
Nivel básico
Standard
Preestablecido
audio_mp3_128k (type: audio)
enviar
Audio o vídeo con audio.
Ejecución del trabajo
Archivo MP3 de 128 kbps.
Nivel básico
Standard
Preestablecido
audio_opus_96k (type: audio)
enviar
Audio o vídeo con audio.
Ejecución del trabajo
Archivo Opus de 96 kbps, muy adecuado para la transmisión de voz.
Nivel básico
Standard
Preestablecido
audio_loudnorm_aac_128k (type: audio)
enviar
Audio o vídeo con audio.
Ejecución del trabajo
Se normaliza hacia -16 LUFS, luego escribe 128 kbps AAC.
Nivel básico
Standard
Preestablecido
audio_trim_silence_aac_128k (type: audio)
enviar
Audio o vídeo con audio.
Ejecución del trabajo
Elimina el silencio inicial y final y luego escribe AAC a 128 kbps.
Nivel básico
Premium
Preestablecido
audio_loudnorm_trim_aac_128k (type: audio)
enviar
Audio o vídeo con audio.
Ejecución del trabajo
Recorta el silencio de límites, se normaliza hacia -16 LUFS y luego escribe 128 kbps AAC.
Nivel básico
Premium
Preestablecido
audio_whisper_prep (type: audio)
enviar
Audio o vídeo con audio.
Ejecución del trabajo
PCM mono de 16 kHz WAV preparado para Whisper, ASR u otros canales de voz.
Nivel básico
Premium

Derivados de imagen

Preestablecido
image_multi_v1 (type: image)
enviar
Imagen
Ejecución del trabajo
Crea la matriz de imágenes que solicita usando ajustar, rellenar, cubrir o contener. El nivel depende del formato, el tamaño, el recuento, el recorte inteligente y la eliminación del fondo.
Nivel básico
Standard o Premium
Preestablecido
media_report_v1 (type: image)
enviar
Ver reglas de entrada
Ejecución del trabajo
Inspects the file without transcoding it and writes media_report.json: container and stream detail, encoder strings, GOP/keyframe structure, and EXIF including GPS coordinates converted to decimal degrees. This READS metadata rather than stripping it — image renditions still strip metadata as before. Accepts video or images; audio-only inputs are not supported.
Nivel básico
Varía
Compatibilidad con copia de flujo
transmux_mp4_fast evita una codificación que cambie la calidad cuando la fuente es compatible con MP4. Si la copia falla y el respaldo está habilitado, el motor vuelve a codificar con mp4_720p_h264_aac; Utilice ese preajuste directamente cuando necesite características de salida predecibles.
El nivel puede aumentar con anulaciones
La tabla muestra el nivel base del Workspace. Las salidas de imagen adicionales, WebP/AVIF, los conjuntos grandes de imágenes, el recorte inteligente, la eliminación de fondo, las marcas de agua, la moderación, los subtítulos avanzados o las vistas previas GIF pueden requerir Premium.
Conversión de formato

Utilice una fuente. Produzca los formatos y artefactos sidecar que su producto necesita.

La extensión de origen no selecciona la salida. tipo y preajuste eligen la receta ejecutable, por lo que un video cargado puede convertirse en video de reproducción, medios de solo audio, transcripciones, vistas previas de GIF, carteles o secuencias de fotogramas en el mismo trabajo asincrónico.

Fuente
JPG, PNG o WebP
Entregable
JPG, PNG, WebP o derivados AVIF
Receta
imagen + image_multi_v1; elija imágenes[].formato, dimensiones, mode y calidad.
Fuente
Vídeo
Entregable
Web MP4, HLS, video social o edición maestra
Receta
Elija el mp4, hls o social preajuste correspondiente.
Fuente
Vídeo
Entregable
Secuencia de fotograma animada GIF, póster o JPG
Receta
Utilice gif_hq, poster_frame_v1, extract_frames_1/5 o conecte gif_preview a una salida de vídeo.
Fuente
Vídeo o audio
Entregable
M4A, MP3, Opus o voz WAV
Receta
Elija el audio correspondiente_* preajuste; video entradas se extrae su transmisión de audio.
Fuente
Discurso en vídeo o audio
Entregable
SRT, WebVTT o ambos
Receta
Agregue subtítulos a una salida de audio o video y elija srt, vtt o ambos.
JSON
PNG → JPG + WebP
{
  "file_url": "https://cdn.example.com/media/product-photo.png",
  "metadata": {
    "media_type": "image",
    "asset_id": "product-photo-0426"
  },
  "outputs": [{
    "type": "image",
    "preset": "image_multi_v1",
    "path_suffix": "converted",
    "images": [
      { "width": 1600, "height": 1200, "mode": "fit", "format": "jpg", "quality": 88 },
      { "width": 1600, "height": 1200, "mode": "fit", "format": "webp", "quality": 82 }
    ]
  }]
}
JSON
Un vídeo → MP4 + MP3
{
  "file_url": "https://cdn.example.com/media/interview.mov",
  "outputs": [
    { "type": "mp4", "preset": "mp4_720p_h264_aac", "path_suffix": "web-video" },
    { "type": "audio", "preset": "audio_mp3_128k", "path_suffix": "audio-only" }
  ]
}
JSON
Vídeo → M4A + SRT + WebVTT
{
  "file_url": "https://cdn.example.com/media/interview.mp4",
  "metadata": { "media_type": "video", "asset_id": "interview-0426" },
  "outputs": [{
    "type": "audio",
    "preset": "audio_aac_128k",
    "path_suffix": "audio-and-transcript",
    "subtitles": {
      "enabled": true,
      "languages": ["auto"],
      "format": "both",
      "model": "ggml-base.bin",
      "translate_to_english": false
    }
  }]
}
JSON
Vídeo → MP4 + póster + vista previa de GIF
{
  "file_url": "https://cdn.example.com/media/trailer.mp4",
  "metadata": { "media_type": "video", "asset_id": "trailer-0426" },
  "outputs": [{
    "type": "mp4",
    "preset": "mp4_720p_h264_aac",
    "path_suffix": "web",
    "poster_time_sec": 4,
    "poster_format": "jpg",
    "gif_preview": {
      "enabled": true,
      "width": 480,
      "fps": 10,
      "start_time": 4,
      "duration": 3
    }
  }]
}
JSON
Vídeo → Paquete de transmisión adaptativa HLS
{
  "file_url": "https://cdn.example.com/media/feature-film.mp4",
  "metadata": { "media_type": "video", "asset_id": "stream-0426" },
  "outputs": [{
    "type": "hls",
    "preset": "hls_ladder_v1",
    "path_suffix": "stream"
  }]
}
JSON
Vídeo → secuencia de fotogramas independiente GIF + JPG
{
  "file_url": "https://cdn.example.com/media/clip.mp4",
  "metadata": { "media_type": "video", "asset_id": "clip-0426" },
  "outputs": [
    { "type": "gif", "preset": "gif_hq", "path_suffix": "animated-preview" },
    { "type": "frames", "preset": "extract_frames_1", "path_suffix": "sampled-frames" }
  ]
}
HLS es un paquete, no un archivo de vídeo
hls_ladder_v1 crea una lista de reproducción maestra, listas de reproducción variantes de 1080p y 720p H.264/AAC y segmentos multimedia de 6 segundos. Utilice la lista de reproducción maestra informada URL o junte el paquete completo.
GIF dedicado versus vista previa adjunta
gif_hq crea un GIF primario completo de 480 px y 15 fps. gif_preview agrega un GIF más corto y cronometrado explícitamente a otra salida de video. Los ajustes preestablecidos de fotogramas devuelven secuencias JPG numeradas a uno o cinco fotogramas por segundo.
Cada artefacto permanece adherido al trabajo.
Lea el manifiesto de salida del trabajo completado o utilice su paquete de marca URL. Los archivos de audio, transcripciones, carteles, vistas previas y reproducción se incluyen sin necesidad de volver a cargar la fuente. No cree nombres de archivos ni rutas de almacenamiento.
Estimar el conjunto de salida completo
MediaRuntime estima cada resultado y función solicitados antes de la ejecución. Las vistas previas de GIF, los derivados de WebP/AVIF, los subtítulos avanzados y los trabajos de salida múltiple pueden requerir Premium; el API no los omite silenciosamente.

Interruptores útiles

audio_aac_128k devuelve M4A, audio_mp3_128k devuelve MP3, audio_opus_96k devuelve Opus y audio_whisper_prep devuelve WAV mono de 16 kHz. Establezca subtitles.format en srt, vtt o both. Para una sola imagen de póster, envíe type: mp4 con preset: poster_frame_v1 y el poster_time_sec deseado.

Recetas

Comience con un preajuste; anular sólo lo que importa.

Los ajustes preestablecidos mantienen las solicitudes legibles y le dan al motor una base estable. Agregue opciones explícitas de reproducción, subtítulos, vista previa, códec o velocidad de bits solo cuando el producto las requiera.

JSON
Derivados de imágenes responsivas
{
  "file_url": "https://cdn.example.com/source.jpg",
  "outputs": [{
    "type": "image",
    "preset": "image_multi_v1",
    "images": [
      { "width": 1200, "height": 630, "mode": "cover", "format": "webp", "quality": 84 },
      { "width": 320, "height": 320, "mode": "cover", "format": "webp", "quality": 78 }
    ]
  }]
}
JSON
Archivos de audio y transcripción
{
  "file_url": "https://cdn.example.com/interview.wav",
  "outputs": [{
    "type": "audio",
    "preset": "audio_aac_128k",
    "subtitles": {
      "enabled": true,
      "languages": ["auto"],
      "format": "both",
      "model": "ggml-base.bin"
    }
  }]
}
Enrutamiento de funciones Premium
La moderación, las marcas de agua, los códecs avanzados, múltiples vistas previas de salidas, GIF y algunas funciones de subtítulos pueden requerir Premium. El API rechaza el trabajo que su cuenta no puede ejecutar en lugar de eliminar funciones silenciosamente.
Configuración de marca de agua
Cargue y confirme una cuenta PNG desde la página Cuenta. Luego envíe solo { "watermark": { "enabled": true } }; MediaRuntime resuelve el logotipo propiedad del servidor.
Moderación

Agregue análisis de seguridad visual en capas al trabajo.

La moderación utiliza un canal en capas para una entrada de imagen o video: las señales claras toman el camino rápido, mientras que las señales inciertas o de mayor riesgo se escalan para un análisis más profundo. Devuelve evidencia y decisiones de mejor esfuerzo a través del contrato actual de solo informe sin bloquear la transcodificación.

JSON
Solicitar todo el visual comprobaciones
{
  "file_url": "https://cdn.example.com/upload.mp4",
  "metadata": { "media_type": "video", "asset_id": "asset_0426" },
  "moderation": {
    "enabled": true,
    "mode": "report",
    "checks": ["sexual", "violence", "dangerous"]
  },
  "outputs": [{
    "type": "mp4",
    "preset": "mp4_720p_h264_aac"
  }]
}
JSON
Resultado del trabajo completado y webhook
{
  "moderation": {
    "requested": {
      "enabled": true,
      "mode": "report",
      "checks": ["sexual", "violence", "dangerous"],
      "media_type": "video",
      "phase": "phase1_video_report"
    },
    "result": {
      "ok": true,
      "media_type": "video",
      "verdict": "review",
      "flagged_checks": ["violence"],
      "scores": {
        "violence": { "yes": 0.82, "no": 0.18 }
      },
      "decisions": {
        "violence": { "decision": "review", "raw_decision": "review" }
      },
      "evidence": {
        "frames_sampled": 8,
        "frames_flagged": [{
          "frame_index": 3,
          "timestamp_sec": 20,
          "verdict": "review",
          "flagged_checks": ["violence"]
        }]
      },
      "video": {
        "frame_interval_sec": 10,
        "max_frames": 24
      }
    }
  },
  "meta": {
    "moderation_result": {
      "url": "https://storage.googleapis.com/.../moderation_result.json"
    }
  },
  "usage": {
    "breakdown": { "moderation_units": 120 }
  }
}
Contract
Plan
Value
Premium
Notes
The API returns 403 unless the account is Premium or auto-upgrade is allowed.
Contract
Mode
Value
report
Notes
This is the only accepted mode today. Do not send block.
Contract
Checks
Value
sexual, violence, dangerous
Notes
Send one to three checks. Omitting checks selects all three.
Contract
Inputs
Value
One image or video
Notes
Audio-only inputs, batches, and Sandbox moderation are rejected.
Contract
Video sampling
Value
Fixed interval, bounded frames
Notes
The service chooses the interval and cap; read the actual values from result.video and result.evidence.
Contract
Decision
Value
allow, review, or block signal
Notes
Report mode never blocks execution. Use result.verdict, decisions, flagged_checks, and evidence in your own policy.
Contract
Artifact
Value
meta/moderation_result.json
Notes
Included in the output ZIP and exposed through meta.moderation_result.url when available.
Contract
Billing
Value
Separate moderation units
Notes
Estimated and settled with the job at usage.breakdown.moderation_units.
Su aplicación posee la aplicación
Trate a review como una señal para una cola humana, una retención de publicación u otra política que usted controle. Un informe completo no es una promesa de que los medios sean seguros, legales o cumplan con las políticas.
Los modelos pueden estar equivocados
Las puntuaciones son clasificadores salidas, no hechos. Conserve la evidencia, versione sus umbrales posteriores, proporcione una ruta de apelación cuando corresponda y evite decisiones de alto impacto totalmente automatizadas.
Ganchos web

Verifique los bytes sin procesar antes de confiar en el evento.

Los eventos terminales se entregan al menos una vez y no se garantiza el pedido. Verifique HMAC-SHA256, rechace marcas de tiempo obsoletas, deduplica event_id, reconozca rápidamente y mueva el trabajo pesado a una cola.

JSON
Evento COMPLETED
{
  "event_id": "webhook_evt_job_1320c28b72104811b075a26a99496cf6",
  "job_id": "job_1320c28b72104811b075a26a99496cf6",
  "account_id": "acc_xxx",
  "status": "COMPLETED",
  "completedAt": "2026-08-09T02:41:23Z",
  "billing": { "status": "PAID", "estimatedUnits": 31 },
  "usage": { "units_total": 31, "breakdown": {} },
  "delivery": {
    "mode": "PULL",
    "retentionDays": 7,
    "expiresAt": "2026-08-16T02:41:23Z",
    "bundle": {
      "type": "zip",
      "filename": "outputs.zip",
      "download": {
        "url": "https://mediaruntime.com/v1/jobs/job_1320c28b72104811b075a26a99496cf6/bundle?token=...",
        "expiresAt": "2026-08-16T02:41:23Z"
      }
    }
  },
  "meta": {
    "engine_result_url": "https://storage.googleapis.com/...",
    "outputs_root_gs": "gs://.../jobs/acc_xxx/job_.../outputs",
    "request_metadata": {
      "producer": "my-api",
      "entity_id": "video_01J8Y4",
      "media_type": "video"
    }
  }
}
Donde vive salidas
Descargue el ZIP completo desde delivery.bundle.download.url o busque meta.engine_result_url para enumerar salidas individuales y rutas de artefactos.
Node
Verificación expresa del cuerpo en bruto
import crypto from "node:crypto";
import express from "express";

const app = express();

// Register this route before any express.json() middleware.
app.post("/webhooks/mediaruntime", express.raw({ type: "application/json" }), (req, res) => {
  const eventId = req.get("X-Transcoder-Id") || "";
  const signatureHeader = req.get("X-Transcoder-Signature") || "";
  const parts = Object.fromEntries(
    signatureHeader.split(",").map((part) => part.trim().split("="))
  );

  const timestamp = parts.t || "";
  const received = parts.v1 || "";
  const ageSeconds = Math.abs(Date.now() / 1000 - Number(timestamp));
  if (!eventId || !timestamp || !received || ageSeconds > 300) {
    return res.sendStatus(401);
  }

  const expected = crypto
    .createHmac("sha256", process.env.MEDIARUNTIME_WEBHOOK_SECRET)
    .update(timestamp + "." + eventId + ".")
    .update(req.body) // raw Buffer; never JSON.stringify(req.body)
    .digest("hex");

  const a = Buffer.from(expected, "utf8");
  const b = Buffer.from(received, "utf8");
  if (a.length !== b.length || !crypto.timingSafeEqual(a, b)) {
    return res.sendStatus(401);
  }

  const event = JSON.parse(req.body.toString("utf8"));
  // Enqueue work and deduplicate on event.event_id in your database.
  console.log(event.event_id, event.job_id, event.status);
  return res.sendStatus(200);
});
Configurar el punto final en Cuenta
Abra Cuenta → Webhooks, ingrese su punto final HTTPS y almacene el secreto de firma cuando se muestre. La integración pública de API solo requiere su clave API y su secreto de firma de webhook.

Reglas de entrega

  • Devuelva cualquier 2xx solo después de la verificación de la firma y la puesta en cola/deduplicación duradera.
  • Trate a event_id como la clave de idempotencia.
  • Utilice meta.request_metadata para encontrar su entidad sin una segunda tabla de búsqueda.
  • Descargue el salidas retenido antes de la entrega.expiresAt.
  • Un evento FAILED o REJECTED tiene error.code/message y no tiene ningún paquete utilizable.
Seguimiento de trabajos

Encuesta cuando un webhook no es práctico.

El envío regresa inmediatamente con un job_id. Los webhooks siguen siendo la forma de latencia más baja para saber si un trabajo ha terminado, pero las encuestas están disponibles para el desarrollo local, entornos sin un punto final público, conciliación y preguntas de soporte.

cURL
Consigue un trabajo
curl -sS "https://mediaruntime.com/v1/jobs/$JOB_ID" \
  -H "X-API-Key: $MEDIARUNTIME_API_KEY"
cURL
Lista tus trabajos
# Newest first. Filter by status and page with the cursor.
curl -sS "https://mediaruntime.com/v1/jobs?status=COMPLETED&limit=25" \
  -H "X-API-Key: $MEDIARUNTIME_API_KEY"

# Next page: pass the previous response's next_cursor
curl -sS "https://mediaruntime.com/v1/jobs?limit=25&cursor=$NEXT_CURSOR" \
  -H "X-API-Key: $MEDIARUNTIME_API_KEY"
JSON
Campos de respuesta
{
  "job_id": "job_2ee8db582cdf4a2fafb49d52218b3159",
  "status": "COMPLETED",
  "tier": {
    "requested": "premium",
    "required": "standard",
    "effective": "premium",
    "billed": "standard",
    "reasons": []
  },
  "usage": { "units_total": 4 },
  "billing": {
    "status": "PAID",
    "currency": "USD",
    "unit_price_cents": 1,
    "final_units": 4,
    "final_amount_cents": 4
  },
  "bundle": {
    "available": true,
    "download_url": "https://mediaruntime.com/v1/jobs/job_2ee8.../bundle?token=...",
    "expires_at": "2026-08-18T03:14:27Z",
    "size_bytes": 13056793,
    "retention_days": 7
  },
  "media": {
    "format": "mov,mp4,m4a,3gp,3g2,mj2",
    "duration_sec": 61.5,
    "bit_rate": 8000000,
    "video": {
      "codec": "h264",
      "profile": "High",
      "width": 1080,
      "height": 1920,
      "encoded_width": 1920,
      "encoded_height": 1080,
      "fps": 29.97,
      "rotation_deg": 90,
      "is_rotated": true,
      "orientation": "portrait"
    },
    "audio": { "codec": "aac", "sample_rate_hz": 48000, "channels": 2, "layout": "stereo" },
    "streams": { "video": 1, "audio": 1, "other": 0 }
  },
  "metadata": { "asset_id": "asset_0426", "media_type": "video" },
  "error": null,
  "completed_at": "2026-08-11T03:14:53Z"
}
Leyendo el bloque de niveles
requested es el nivel de la clave API que envió el trabajo. required es lo que realmente necesita el trabajo, effective es el carril por el que corrió y billed es lo que le cobraron. Una clave premium que ejecuta un trabajo estándar muestra requested: premium con billed: standard: se le cobra por el trabajo, no por la clave.
Leyendo el bloque de medios
media informa lo que MediaRuntime encontró en su entrada cuando la probó en el momento del envío, la misma sonda que decide si se acepta un trabajo. Cuando un trabajo es RECHAZADO por un emparejamiento incompatible, esto explica por qué: un MP3 enviado a una salida de imagen muestra streams.video: 0, y un todavía enviado a una salida de fotogramas no tiene duration_sec. Nota video.width/height son dimensiones de PANTALLA con rotación aplicada, por lo que un clip de teléfono vertical lee 1080x1920 aunque encoded_width/encoded_height sean 1920x1080. Cada campo es opcional: si falta uno significa que la sonda no lo informó, nunca cero.
Obtener un veredicto de moderación
GET /v1/jobs/{job_id}/moderation devuelve solo el veredicto, por lo que un cliente que consulta para decidir no descarga en cada petición los detalles de facturación y del paquete. Responde con verdict, decision y confidence por comprobación, además de likelihoods de escalado. Una comprobación marcada como review_only es consultiva: puede producir un veredicto review, pero no puede bloquear por sí sola. El endpoint devuelve **404 cuando el trabajo existe pero nunca se solicitó moderación**; una respuesta correcta vacía sería indistinguible de «moderado sin hallazgos». Los umbrales de cada decisión no se publican.
Obteniendo un informe de los medios
GET /v1/jobs/{job_id}/media-report devuelve el documento media_report_v1 sin descargar el paquete. report lo lleva en línea; un informe inusualmente grande no se almacena en línea y la respuesta establece report en nulo con un download_url que aún se resuelve, así que maneje ambos. Devuelve 404 cuando el trabajo no incluye ningún informe.
campo
estado
Tipo
cuerda
Notas
QUEUED, PROCESANDO, COMPLETED, FAILED o RECHAZADO.
campo
nivel
Tipo
objeto
Notas
solicitada/requerida/efectiva/facturada, más los motivos por los que se requirió la prima.
campo
uso.units_total
Tipo
entero
Notas
Unidades facturables para el trabajo.
campo
facturación
Tipo
objeto
Notas
Moneda, precio unitario y unidades e importe estimado frente a final.
campo
paquete.download_url
Tipo
cuerda
Notas
Paquete que vence y tiene alcance de trabajo URL. Solo punto final de un solo trabajo.
campo
medios de comunicación
Tipo
objeto
Notas
Cuál fue realmente la entrada, como se probó en el envío. Nulo en trabajos más antiguos.
campo
medios.video.ancho/alto
Tipo
entero
Notas
Mostrar dimensiones, rotación ya aplicada.
campo
medios.duration_sec
Tipo
numero
Notas
Ausente para imágenes fijas, que no tienen línea de tiempo.
campo
metadata
Tipo
objeto
Notas
El objeto metadatos que envió se repitió.
campo
error
Tipo
cuerda
Notas
Completado en FAILED o RECHAZADO; nulo en caso contrario.

Reglas de votación

  • Prefiere webhooks; Encuesta sólo cuando no puedas recibir una.
  • Página con next_cursor, nunca un desplazamiento: las filas cambian a medida que se actualizan los trabajos.
  • Una identificación de trabajo que no es de su propiedad devuelve 404, lo mismo que una que no existe.
  • Las filas de la lista omiten el paquete URL; busque el trabajo único para descargar.
  • Retroceda entre encuestas. El estado de una terminal no cambiará.
Facturación y precios

Prepago, pago sobre la marcha y liquidación según el uso real.

Agregue una tarjeta, deposite fondos en la billetera y envíe trabajos sin una suscripción recurrente. MediaRuntime reserva un presupuesto antes de la ejecución y liquida el cargo final cuando el trabajo llega a un estado terminal.

Planificar
Standard Pay-As-You-Go
Precio de uso inicial
Desde $0.02
Recarga mínima
$20.00
Recarga automática predeterminada
$20.00 en $2.00 disponible
Planificar
Premium Pay-As-You-Go
Precio de uso inicial
Desde $0.05
Recarga mínima
$60.00
Recarga automática predeterminada
$60.00 en $5.00 disponible
Cómo funcionan la reserva y la liquidación
El envío reserva el cargo estimado más un margen de seguridad del 15%. La finalización cobra el uso facturable real y libera la reserva no utilizada. Las recargas pendientes de Stripe se convierten en crédito de billetera solo después de que el webhook de pago firmado las confirme.
Cómo se mide el uso
El vídeo y el audio parten de la duración del medio y después reflejan las salidas y el procesamiento solicitados. Las imágenes usan unidades de procesamiento con una unidad mínima facturable por trabajo; los bytes de entrada no se cobran por MB. Varias salidas y funciones como códecs avanzados, subtítulos, GIF, moderación y marcas de agua pueden añadir unidades o requerir Premium. Usa la estimación del trabajo para planificar y los campos terminales billing y usage para conciliar.

Reglas de billetera

  • El crédito disponible equivale al crédito de billetera menos los fondos reservados para ejecutar trabajos.
  • El crédito disponible insuficiente devuelve HTTP 402 antes de la ejecución.
  • La recarga automática es opcional y requiere una tarjeta registrada.
  • Una solicitud exclusiva de Premium devuelve 403 cuando no se permite la actualización.
Utilice la instantánea de facturación de la cuenta
La tabla muestra los precios iniciales públicos en dólares, no un precio fijo para cada trabajo. Las cuentas de volumen negociado pueden tener precios específicos de la cuenta. No derivar el cargo final únicamente de la duración; conservar la estimación y la instantánea de facturación del terminal devueltas para el trabajo.
Errores y reintentos

Reintentar fallas de transporte, no trabajo no válido.

La mayoría de los errores API utilizan un campo de detalles de nivel superior. Puede ser una cadena o un objeto estructurado, así que registre la respuesta completa junto con su ID de correlación, pero nunca registre la clave API.

Estado
400
Significado
La solicitud es lógicamente inválida o el estimador la rechazó.
Qué debe hacer tu integración
Arreglar la solicitud; no lo vuelva a intentar sin cambios.
Estado
401
Significado
La clave API no es válida, ha caducado o está revocada.
Qué debe hacer tu integración
Corrija o gire la clave; no lo vuelvas a intentar ciegamente.
Estado
402
Significado
La cuenta, la billetera o la verificación previa de facturación no pueden cubrir el trabajo.
Qué debe hacer tu integración
Deposite fondos en la billetera o resuelva la facturación primero.
Estado
403
Significado
El plan, rol o característica no permite la solicitud.
Qué debe hacer tu integración
Cambiar el plan/solicitud; no lo vuelva a intentar sin cambios.
Estado
413
Significado
El cuerpo de la solicitud HTTP supera los 2 MiB.
Qué debe hacer tu integración
Cargue medios por separado y envíe URL únicamente.
Estado
422
Significado
El JSON no coincide con el esquema API.
Qué debe hacer tu integración
Corrija el campo nombrado.
Estado
429
Significado
La cuenta o clave tiene una tarifa limitada.
Qué debe hacer tu integración
Vuelva a intentarlo con retroceso exponencial y fluctuación.
Estado
500/502/503
Significado
Falló una dependencia de plataforma transitoria o un carril está en pausa.
Qué debe hacer tu integración
Vuelva a intentarlo de forma segura con retroceso; conserve su correlación metadatos.
JSON
Cuerpo de error típico
{
  "detail": "Insufficient wallet balance for this job"
}
Política de reintento seguro
Vuelva a intentar las respuestas 429 y 5xx transitorias con fluctuación y retroceso exponencial limitados. No vuelva a enviar automáticamente un trabajo aceptado después de perder la respuesta HTTP a menos que su aplicación pueda detectar duplicados; mantenga su propio ID de seguimiento en metadatos para la conciliación.
Referencia de API

La pequeña superficie que necesitan la mayoría de integraciones.

Todos los puntos finales de servidor a servidor a continuación utilizan X-API-Key. El paquete tokenizado URL es la única excepción porque lleva su propia credencial de corta duración y con ámbito de trabajo.

Método
PUBLICAR
Camino
/v1/upload-url
Propósito
Opcionalmente, cree un objetivo de carga de 15 minutos cuando aún no tenga un medio recuperable URL.
Método
PUBLICAR
Camino
/v1/jobs
Propósito
Ponga en cola un trabajo de medios de entrada única o por lotes.
Método
OBTENER
Camino
/v1/jobs/{job_id}
Propósito
Estado, decisión de nivel, uso, facturación y enlace de paquete para un trabajo.
Método
OBTENER
Camino
/v1/jobs
Propósito
Enumere sus trabajos, los más nuevos primero. Admite ?status= y paginación del cursor.
Método
OBTENER
Camino
/v1/jobs/{job_id}/moderation
Propósito
Veredicto de moderación de un trabajo. Devuelve 404 cuando no se solicitó moderación.
Método
OBTENER
Camino
/v1/jobs/{job_id}/media-report
Propósito
Informe de medios forenses para un trabajo. 404 cuando no se solicitó media_report_v1.
Método
OBTENER
Camino
/v1/jobs/{job_id}/bundle?token=...
Propósito
Canjee el token de ámbito de trabajo por un paquete; no se requiere ninguna clave API.
Método
PUBLICAR
Camino
/v1/jobs/{job_id}/retry-webhook
Propósito
Vuelva a intentar el webhook de terminal para un trabajo de su propiedad.
Método
PUBLICAR
Camino
/v1/account/watermark-logo/upload-url
Propósito
Cree un destino de carga para el logotipo de la cuenta PNG.
Método
PUBLICAR
Camino
/v1/account/watermark-logo/confirm
Propósito
Confirme el logotipo y su configuración de ubicación.