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.
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.
# 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
}]
}'# 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.{
"job_id": "job_1320c28b72104811b075a26a99496cf6",
"status": "QUEUED",
"tier": "standard",
"msg": "accepted"
}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.
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.
{
"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 | Tipo | Notas |
|---|---|---|
| file_url | cuerda | Un HTTP(S) público, un HTTP(S) firmado por tiempo limitado o una entrada gs:// accesible. Utilice este o entradas, nunca ambos. |
| inputs | matriz | Distribución por lotes para 1–25 entradas. Cada uno puede llevar input_id y metadatos. |
| outputs | matriz | 1 a 10 recetas de salida. Cada uno requiere tipo; Se recomienda encarecidamente preajuste. |
| metadata | objeto | Hasta 32 KiB de JSON. Persistió y se hizo eco en meta.request_metadata. |
| moderation | objeto | Premium visual-media comprobaciones: sexual, violencia, peligrosa. |
| watermark | objeto | 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.
{
"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.
# 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.Reglas clave
- Un UUID funciona; una identificación determinista como
asset_0426:mp4_720p:v1es 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.
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.
{
"file_url": "https://cdn.example.com/landscape-interview.mp4",
"outputs": [{
"type": "social",
"preset": "social_vertical_blur"
}]
}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 | enviar | Ejecución del trabajo | Nivel básico |
|---|---|---|---|
| mp4_720p_h264_aac (type: mp4) | Vídeo | 720p H.264/AAC MP4 con inicio rápido para reproducción web. | Standard |
| mp4_ladder_v1 (type: mp4) | Vídeo | Tres interpretaciones de MP4 a 1080p, 720p y 480p, además de un póster para cada interpretación. | Standard |
| transmux_mp4_fast (type: mp4) | Audio/vídeo compatibles | 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. | Standard |
| poster_frame_v1 (type: mp4) | Vídeo | Un JPG de 720p capturado en poster_time_sec. La solicitud tipo sigue siendo mp4. | Standard |
| mp4_hevc_1080p (type: mp4) | Vídeo | 1080p HEVC/H.265 + AAC MP4 con la etiqueta hvc1 para reproducción de Apple. | Premium |
| mp4_av1_smart (type: mp4) | Vídeo | 1080p AV1 + Opus MP4 optimizado para eficiencia de compresión; La codificación requiere un uso intensivo de la CPU. | Premium |
| mov_prores_422 (type: mp4) | Vídeo | ProRes 422 HQ + PCM MOV maestro de edición. Conserva las dimensiones de origen y produce un archivo intermedio de gran tamaño. | Premium |
Vídeo social
| Preestablecido | enviar | Ejecución del trabajo | Nivel básico |
|---|---|---|---|
| social_vertical_blur (type: social) | Vídeo | 1080×1920 H.264/AAC MP4. Ajusta la fuente sobre un fondo borroso de 9:16 para carretes, TikTok y cortos. | Premium |
Animado GIF
| Preestablecido | enviar | Ejecución del trabajo | Nivel básico |
|---|---|---|---|
| gif_hq (type: gif) | Vídeo | GIF animado a 480 px de ancho y 15 fps usando generación de paleta para una mejor calidad de color. | Standard |
Extracción de cuadros
| Preestablecido | enviar | Ejecución del trabajo | Nivel básico |
|---|---|---|---|
| extract_frames_1 (type: frames) | Vídeo | Secuencia de cuadros numerada JPG muestreada a 1 cuadro por segundo. | Standard |
| extract_frames_5 (type: frames) | Vídeo | Secuencia de cuadros numerada JPG muestreada a 5 cuadros por segundo. | Standard |
| scene_detect_v1 (type: frames) | Ver reglas de entrada | 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. | Varía |
| perceptual_hash_v1 (type: frames) | Ver reglas de entrada | 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. | Varía |
Transmisión
| Preestablecido | enviar | Ejecución del trabajo | Nivel básico |
|---|---|---|---|
| hls_ladder_v1 (type: hls) | Vídeo | Paquete HLS VOD con variantes H.264/AAC de 1080p y 720p, lista de reproducción maestra y segmentos de 6 segundos. | Standard |
Audio
| Preestablecido | enviar | Ejecución del trabajo | Nivel básico |
|---|---|---|---|
| audio_copy_fast (type: audio) | Audio o vídeo con audio. | 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. | Standard |
| audio_aac_128k (type: audio) | Audio o vídeo con audio. | 128 kbps AAC en un archivo M4A de inicio rápido. | Standard |
| audio_mp3_128k (type: audio) | Audio o vídeo con audio. | Archivo MP3 de 128 kbps. | Standard |
| audio_opus_96k (type: audio) | Audio o vídeo con audio. | Archivo Opus de 96 kbps, muy adecuado para la transmisión de voz. | Standard |
| audio_loudnorm_aac_128k (type: audio) | Audio o vídeo con audio. | Se normaliza hacia -16 LUFS, luego escribe 128 kbps AAC. | Standard |
| audio_trim_silence_aac_128k (type: audio) | Audio o vídeo con audio. | Elimina el silencio inicial y final y luego escribe AAC a 128 kbps. | Premium |
| audio_loudnorm_trim_aac_128k (type: audio) | Audio o vídeo con audio. | Recorta el silencio de límites, se normaliza hacia -16 LUFS y luego escribe 128 kbps AAC. | Premium |
| audio_whisper_prep (type: audio) | Audio o vídeo con audio. | PCM mono de 16 kHz WAV preparado para Whisper, ASR u otros canales de voz. | Premium |
Derivados de imagen
| Preestablecido | enviar | Ejecución del trabajo | Nivel básico |
|---|---|---|---|
| image_multi_v1 (type: image) | Imagen | 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. | Standard o Premium |
| media_report_v1 (type: image) | Ver reglas de entrada | 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. | Varía |
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.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 | Entregable | Receta |
|---|---|---|
| JPG, PNG o WebP | JPG, PNG, WebP o derivados AVIF | imagen + image_multi_v1; elija imágenes[].formato, dimensiones, mode y calidad. |
| Vídeo | Web MP4, HLS, video social o edición maestra | Elija el mp4, hls o social preajuste correspondiente. |
| Vídeo | Secuencia de fotograma animada GIF, póster o JPG | Utilice gif_hq, poster_frame_v1, extract_frames_1/5 o conecte gif_preview a una salida de vídeo. |
| Vídeo o audio | M4A, MP3, Opus o voz WAV | Elija el audio correspondiente_* preajuste; video entradas se extrae su transmisión de audio. |
| Discurso en vídeo o audio | SRT, WebVTT o ambos | Agregue subtítulos a una salida de audio o video y elija srt, vtt o ambos. |
{
"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 }
]
}]
}{
"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" }
]
}{
"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
}
}]
}{
"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
}
}]
}{
"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"
}]
}{
"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_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_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.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.
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.
{
"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 }
]
}]
}{
"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"
}
}]
}{ "watermark": { "enabled": true } }; MediaRuntime resuelve el logotipo propiedad del servidor.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.
{
"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"
}]
}{
"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 | Value | Notes |
|---|---|---|
| Plan | Premium | The API returns 403 unless the account is Premium or auto-upgrade is allowed. |
| Mode | report | This is the only accepted mode today. Do not send block. |
| Checks | sexual, violence, dangerous | Send one to three checks. Omitting checks selects all three. |
| Inputs | One image or video | Audio-only inputs, batches, and Sandbox moderation are rejected. |
| Video sampling | Fixed interval, bounded frames | The service chooses the interval and cap; read the actual values from result.video and result.evidence. |
| Decision | allow, review, or block signal | Report mode never blocks execution. Use result.verdict, decisions, flagged_checks, and evidence in your own policy. |
| Artifact | meta/moderation_result.json | Included in the output ZIP and exposed through meta.moderation_result.url when available. |
| Billing | Separate moderation units | Estimated and settled with the job at usage.breakdown.moderation_units. |
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.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.
{
"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"
}
}
}delivery.bundle.download.url o busque meta.engine_result_url para enumerar salidas individuales y rutas de artefactos.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);
});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.
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 -sS "https://mediaruntime.com/v1/jobs/$JOB_ID" \
-H "X-API-Key: $MEDIARUNTIME_API_KEY"# 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"{
"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"
}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.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.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.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 | Tipo | Notas |
|---|---|---|
| estado | cuerda | QUEUED, PROCESANDO, COMPLETED, FAILED o RECHAZADO. |
| nivel | objeto | solicitada/requerida/efectiva/facturada, más los motivos por los que se requirió la prima. |
| uso.units_total | entero | Unidades facturables para el trabajo. |
| facturación | objeto | Moneda, precio unitario y unidades e importe estimado frente a final. |
| paquete.download_url | cuerda | Paquete que vence y tiene alcance de trabajo URL. Solo punto final de un solo trabajo. |
| medios de comunicación | objeto | Cuál fue realmente la entrada, como se probó en el envío. Nulo en trabajos más antiguos. |
| medios.video.ancho/alto | entero | Mostrar dimensiones, rotación ya aplicada. |
| medios.duration_sec | numero | Ausente para imágenes fijas, que no tienen línea de tiempo. |
| metadata | objeto | El objeto metadatos que envió se repitió. |
| error | cuerda | 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á.
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 | Precio de uso inicial | Recarga mínima | Recarga automática predeterminada |
|---|---|---|---|
| Standard Pay-As-You-Go | Desde $0.02 | $20.00 | $20.00 en $2.00 disponible |
| Premium Pay-As-You-Go | Desde $0.05 | $60.00 | $60.00 en $5.00 disponible |
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.
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 | Significado | Qué debe hacer tu integración |
|---|---|---|
| 400 | La solicitud es lógicamente inválida o el estimador la rechazó. | Arreglar la solicitud; no lo vuelva a intentar sin cambios. |
| 401 | La clave API no es válida, ha caducado o está revocada. | Corrija o gire la clave; no lo vuelvas a intentar ciegamente. |
| 402 | La cuenta, la billetera o la verificación previa de facturación no pueden cubrir el trabajo. | Deposite fondos en la billetera o resuelva la facturación primero. |
| 403 | El plan, rol o característica no permite la solicitud. | Cambiar el plan/solicitud; no lo vuelva a intentar sin cambios. |
| 413 | El cuerpo de la solicitud HTTP supera los 2 MiB. | Cargue medios por separado y envíe URL únicamente. |
| 422 | El JSON no coincide con el esquema API. | Corrija el campo nombrado. |
| 429 | La cuenta o clave tiene una tarifa limitada. | Vuelva a intentarlo con retroceso exponencial y fluctuación. |
| 500/502/503 | Falló una dependencia de plataforma transitoria o un carril está en pausa. | Vuelva a intentarlo de forma segura con retroceso; conserve su correlación metadatos. |
{
"detail": "Insufficient wallet balance for this job"
}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 | Camino | Propósito |
|---|---|---|
| PUBLICAR | /v1/upload-url | Opcionalmente, cree un objetivo de carga de 15 minutos cuando aún no tenga un medio recuperable URL. |
| PUBLICAR | /v1/jobs | Ponga en cola un trabajo de medios de entrada única o por lotes. |
| OBTENER | /v1/jobs/{job_id} | Estado, decisión de nivel, uso, facturación y enlace de paquete para un trabajo. |
| OBTENER | /v1/jobs | Enumere sus trabajos, los más nuevos primero. Admite ?status= y paginación del cursor. |
| OBTENER | /v1/jobs/{job_id}/moderation | Veredicto de moderación de un trabajo. Devuelve 404 cuando no se solicitó moderación. |
| OBTENER | /v1/jobs/{job_id}/media-report | Informe de medios forenses para un trabajo. 404 cuando no se solicitó media_report_v1. |
| OBTENER | /v1/jobs/{job_id}/bundle?token=... | Canjee el token de ámbito de trabajo por un paquete; no se requiere ninguna clave API. |
| PUBLICAR | /v1/jobs/{job_id}/retry-webhook | Vuelva a intentar el webhook de terminal para un trabajo de su propiedad. |
| PUBLICAR | /v1/account/watermark-logo/upload-url | Cree un destino de carga para el logotipo de la cuenta PNG. |
| PUBLICAR | /v1/account/watermark-logo/confirm | Confirme el logotipo y su configuración de ubicación. |