Crear un job

POST /v1/jobs
Idempotency-Key: 5f0c2a8e-…

{
  "input": { "upload_id": "0199a0e0-5f1c-7c3a-9d2e-1b4f6a8c2d10", "clip": { "start": 10, "duration": 60 } },
  "outputs": {
    "streaming": { "formats": ["hls", "dash"], "variants": ["1080p", "720p", "480p", "360p", "240p"] },
    "mp4": { "variants": ["720p", { "resolution": "1080p", "audio": false }] },
    "mp3": { "bitrate": 192000 },
    "posters": [{ "at": 5, "width": 1280 }],
    "storyboard": { "interval": 5 }
  },
  "audio": { "tracks": [{ "language": "es" }, { "language": "en", "required": false }] },
  "subtitles": { "tracks": "all" },
  "on_upscale": "skip",
  "quality_metrics": true,
  "webhook_url": "https://tu-servidor.example.com/hooks/iomza",
  "metadata": { "video_id": "123" }
}

La respuesta es el job (201): queued hasta que tu plan tenga hueco, luego processing. Mira Seguir un job.

Idempotencia. Envía un Idempotency-Key (cualquier texto único de hasta 255 caracteres, un UUID por ejemplo): si la petición se repite con la misma clave, tras un tiempo agotado por ejemplo, recibes el mismo job (200) en vez de un segundo. La misma clave con otro cuerpo da 409.

La petición

Campo
input	La fuente: exactamente uno de upload_id (una subida tuya: completada, o una progresiva que aún llega) o url (se copia primero: mira O da una URL).
input.clip	Procesar solo un tramo: start en segundos (por defecto 0) y duration (por defecto, hasta el final).
outputs	Al menos uno de streaming, mp4, mp3, posters, storyboard.
outputs.streaming	Streaming adaptativo. formats: hls y/o dash (por defecto los dos; comparten segmentos, así que pedir ambos no cuesta más). variants: las calidades.
outputs.mp4	Un MP4 por variante, cada uno con todas las pistas de audio elegidas.
outputs.mp3	Solo el audio. bitrate 32 000–320 000 (por defecto 128 000).
outputs.posters	1–10 imágenes JPEG: at (segundo), width/height opcionales (uno solo conserva la forma).
outputs.storyboard	Sprites de miniaturas y un índice WebVTT, para la vista previa sobre la barra del reproductor: interval (1–60 s), width/height (por defecto 160×90 con la forma del video), columns.
audio.bitrate	Obliga a recodificar el audio en AAC a ese bitrate. Sin él, el AAC mono y estéreo se copia tal cual: más rápido y sin pérdida.
audio.tracks, subtitles.tracks	Qué pistas de la fuente salen: mira Idiomas y subtítulos.
on_upscale	Para calidades mayores que la fuente: skip (por defecto) las omite y las lista en skipped del job; fail rechaza el job.
quality_metrics	true puntúa la calidad percibida de cada variante (VMAF): mira Calidad. Añade unos segundos.
webhook_url	Envía también aquí los eventos de este job, además de los endpoints de tu organización. https, pública.
metadata	Hasta 10 pares de texto tuyos (claves de hasta 40 caracteres, valores de hasta 500), que vuelven en el job y en sus webhooks.

Variantes

Cada variante es una calidad. Escríbela con su nombre para los valores por defecto, o como objeto para controlarla:

"variants": [
  "1080p",
  { "resolution": "720p", "codec": "hevc", "quality": 24 },
  { "resolution": "480p", "bitrate": 1200000, "rate_control": "cbr" }
]

Hasta 10 por resultado. La misma calidad pedida en streaming y en mp4 se codifica una vez y cuenta una vez.

Campo	Valores	Por defecto
resolution	240p 360p 480p 720p 1080p 1440p 2160p, o cualquier otra altura par de 144 a 2160 ("540p", "576p", "900p")	obligatorio
codec	h264 (se reproduce en todas partes), hevc (un 30 % más ligero a igual calidad; dispositivos Apple, televisores y navegadores recientes), av1 (el más ligero; dispositivos recientes)	h264
quality	Calidad constante, CRF 16–35: menor es mejor y más pesado	22
max_bitrate	Un techo, en bps (100 000–100 000 000)	según la resolución
bitrate	Un bitrate objetivo, en bps (100 000–100 000 000), en vez de una calidad	—
rate_control	Con bitrate: vbr o cbr	vbr
preset	ultrafast … veryslow: velocidad frente a compresión	veryfast
profile	Solo H.264: baseline, main, high	según la resolución
fit	Cómo llena la imagen el cuadro: mira abajo	contain
rotate	0, 90, 180, 270 (en sentido horario, antes de escalar)	0
flip	horizontal, vertical	—
watermark	{ "url": "https://…/logo.png", "position": "bottomright" }: topleft, topright, bottomleft, bottomright o center	—
audio	Solo MP4: si el archivo lleva audio	true

Tamaños

Una calidad nombra un cuadro 16:9: 1080p es 1920×1080, 540p es 960×540. Con fit: "contain" (por defecto) la imagen conserva su forma dentro del cuadro y el cuadro gira con el video, así que un video vertical de móvil en 720p sale de 720×1280, sin barras. pad mantiene el cuadro 16:9 y añade barras; crop lo llena y recorta lo que sobra.

Las alturas personalizadas ("540p", "900p"…) reciben un techo por defecto interpolado entre las calidades estándar que las rodean.

Calidad o bitrate

Hay dos formas de controlar el bitrate. Usa una por variante: quality y bitrate se excluyen.

Modo calidad (por defecto): quality fija una calidad percibida constante, y el codificador gasta lo que cada escena necesita. Una persona hablando ocupa una fracción de lo que ocupa un partido de fútbol. max_bitrate es un techo, no un objetivo: las escenas sencillas quedan muy por debajo y las complejas se sujetan en él. Los techos por defecto van de 400 Kbps en 240p a 15 Mbps en 2160p. El resultado tampoco supera nunca el bitrate de la propia fuente: recodificar no añade detalle que no existe. Es la mejor opción para casi todo, porque pagas bits solo donde se notan.

Modo bitrate: bitrate pide un bitrate, y se respeta aunque la fuente tenga menos.

• rate_control: "vbr" (por defecto): bitrate es la media. Las escenas complejas pueden subir hasta max_bitrate (por defecto 1,5 × bitrate).
• rate_control: "cbr": constante, rellenado donde la imagen necesita menos. Para televisión, servidores de anuncios y CDNs que lo exigen. Pesa más a igual calidad. Con cbr, da solo bitrate.
• AV1 solo admite vbr, sin max_bitrate.

Idiomas y subtítulos

Por defecto salen todas las pistas de audio de la fuente y sus subtítulos de texto. Para elegir, lista las pistas en orden de preferencia: la primera es la predeterminada.

"audio": { "tracks": [{ "language": "es" }, { "language": "en", "name": "English (original)" }, { "index": 2, "required": false }] },
"subtitles": { "tracks": [{ "language": "es" }] }

• Elige por language (es, spa y es-419 funcionan: la primera pista en ese idioma) o por index (su posición entre las pistas de ese tipo de la fuente, desde las pistas).
• name es lo que muestran los reproductores. Por defecto es el nombre del idioma en sí mismo (“Español”, “English”), distinto si dos coinciden (“English 2”). Las pistas sin idioma se nombran por su título, o “Audio 1”…; los nombres que escriben las herramientas de codificación se ignoran.
• required: false significa “si existe”: una pista que falta se lista en skipped_tracks del job en vez de hacerlo fallar.
• [] significa ninguna. "all" es el valor por defecto. Salen como mucho 8 pistas de audio.

Cada pista de audio sale como AAC estéreo: el sonido envolvente (5.1, 7.1, Atmos) se mezcla a estéreo, que todo dispositivo reproduce. En HLS y DASH son pistas de audio alternativas con su idioma, así que los reproductores muestran un menú de idiomas; los MP4 llevan todas las pistas, etiquetadas, con la predeterminada activa. Cada idioma de audio del streaming cuenta como minutos de audio.

Los subtítulos de texto (SRT, ASS, WebVTT, mov_text…) se convierten a WebVTT, recortados al clip, y se entregan como archivos y dentro del streaming. Los forzados se marcan (forced: true) y se nombran así en su propio idioma: “Español (forzados)”, “English (forced)”. Los de imagen (PGS, VobSub) no se pueden convertir y se listan en skipped_tracks.

Cuando la petición está mal

Recibes un 400 validation_error cuyo details lista cada problema con su ruta, explicado según la forma en que lo escribiste, para que los corrijas todos de una vez:

{
  "error": {
    "code": "validation_error",
    "message": "Invalid job request.",
    "details": [
      "outputs.streaming.variants.1.bitrate: give quality or bitrate, not both",
      "outputs.mp4.variants.0: must be one of 240p, 360p, 480p, 720p, 1080p, 1440p, 2160p, or another even height from 144 to 2160 such as \"540p\""
    ]
  }
}

Los mensajes vienen en inglés, como toda la API.