Introducción

Iomza convierte un video en todo lo que necesitas para publicarlo: streaming adaptativo (HLS y DASH), archivos MP4, un MP3, pósters y storyboards para la barra de progreso del reproductor. Tú envías el video, o nos dices dónde está; nosotros te devolvemos las URLs.

La API es JSON sobre HTTPS, con campos en snake_case:

https://api.iomza.com/v1

Autenticación

Cada petición lleva una API key en la cabecera Authorization:

Authorization: Bearer iz_live_...

Las claves se crean en el panel (API keys). Una clave actúa en nombre de su organización: ve las subidas y los jobs de esa organización, y nada más. Guárdala en tu servidor: quien la tenga puede crear jobs que se te facturan. Al revocarla en el panel deja de funcionar al instante.

Tu primer job

1. Sube el video. Pide una subida y haz PUT del archivo a la URL que recibes (los archivos de más de 100 MB van por partes: mira Subir un video).

curl https://api.iomza.com/v1/uploads \
  -H "Authorization: Bearer $IOMZA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "file_name": "video.mp4", "content_type": "video/mp4", "size": 48213775 }'
# → { "id": "0199a0e0-…", "mode": "single", "url": "https://…", "headers": { … }, … }

curl -X PUT "$UPLOAD_URL" -H "Content-Type: video/mp4" --data-binary @video.mp4

curl -X POST https://api.iomza.com/v1/uploads/$UPLOAD_ID/complete \
  -H "Authorization: Bearer $IOMZA_API_KEY"

También puedes saltarte la subida y dar la URL del video al crear el job.

2. Crea el job, diciendo qué quieres obtener:

curl https://api.iomza.com/v1/jobs \
  -H "Authorization: Bearer $IOMZA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "input": { "upload_id": "'$UPLOAD_ID'" },
    "outputs": {
      "streaming": { "variants": ["1080p", "720p", "480p"] },
      "posters": [{ "at": 5 }]
    }
  }'

3. Espera a que termine: consulta GET /v1/jobs/{id} o, mejor, recibe el webhook job.succeeded. El job terminado lista la URL de cada resultado:

{
  "id": "0199a0e1-…",
  "status": "succeeded",
  "outputs": {
    "streaming": { "hls_url": "https://…/master.m3u8", "dash_url": "https://…/manifest.mpd", … },
    "posters": [{ "url": "https://…/poster-0.jpg", "size_bytes": 84512 }]
  }
}

Convenciones

• Los ids son textos opacos. Guárdalos como texto; no los interpretes.
• Las fechas van en ISO 8601 y UTC (2026-10-30T18:04:11.000Z); las duraciones, en segundos; los tamaños, en bytes; los bitrates, en bits por segundo.
• Las listas llegan como { "object": "list", "data": [...] }; las largas se paginan con un cursor.
• Los campos desconocidos se rechazan: una opción mal escrita falla en vez de ignorarse sin aviso.
• Los errores tienen siempre la misma forma, con un code estable para decidir qué hacer: mira Errores.

La API responde en inglés: los message de los errores son para tus logs, y el code es lo que debe leer tu código.

La referencia de la API lista cada ruta, campo, límite y valor por defecto. Se genera desde el propio código de la API, así que siempre es exacta; los nombres de campos y los valores van en inglés, porque son la API.