Skip to Content
Referencia APIVídeosObjeto de vídeo

El objeto de video

El objeto de video es un objeto JSON con las siguientes propiedades:

{
  "id": string,
  "status": "COMPLETE" | "PROGRESSING" | "REPLACING" | "NO_FILE" | "ERROR",
  "statusProgress": number,
  "errorCode": string | null,
  "errorMessage": string | null,
  "visibility": "public" | "private",
  "v": number,
  "title": string,
  "description": string,
  "duration": number,
  "fps": number,
  "orientation": "landscape" | "portrait",
  "sourceFolder": string,
  "language": string,
  "src": {
    "thumbnails": [
      {
        "name": "2160p" | "1440p" | "1080p" | "720p" | "480p" | "360p" | "240p",
        "width": number,
        "height": number,
        "formats": {
          "jpeg": { "url": string, "fileSize": number },
          "webp": { "url": string, "fileSize": number }
        }
      },
      [...]
    ],
    "thumbnailUrl": string, // DEPRECATED — use src.thumbnails instead
    "filename": string,
    "abr": {
      "resolution": "auto",
      "description": "Adaptive Bitrate Streaming (ABR)",
      "url": string, // .m3u8 playlist file
      "maxWidth": number,
      "maxHeight": number
    },
    "hls": [
      {
        "name": "2160p" | "1440p" | "1080p" | "720p" | "540p" | "360p" | "240p",
        "url": string, // .m3u8 playlist file
        "width": number,
        "height": number
      },
      [...]
    ],
    "mp4": [
      {
        "name": "2160p" | "1440p" | "1080p" | "720p" | "540p" | "360p" | "240p",
        "url": string, // .mp4 file
        "width": number,
        "height": number
      },
      [...]
    ]
  },
  "texttracks": [
    {
      "language": "en" | "en-US" | "de" | "de-DE" | "it" | "fr" | "...",
      "filename": string,
      "type": "subtitles" | "captions",
      "url": string,
      "id": string
      // If you need the `content` property, you have to fetch the specific texttrack by its ID.
      // See "Text tracks > Get" for details.
    },
    [...]
  ],
  "chapters": [
    {
      "id": string,
      "title": string,
      "timestamp": string, // 00:00:00
    },
    [...]
  ],
  "categories": [
    {
      "id": string,
      "title": string,
      "slug": string,
    },
    [...]
  ],
  "tags": [
    {
      "id": string,
      "title": string,
      "slug": string,
    },
    [...]
  ],
  "transcriptions": [
    {
      "language": string, // locale in de-DE format
      "autoGenerated": boolean,
      "text": string, // plain text transcript
      "segments": [
          {
            "startTime": number, // in seconds
            "endTime": number, // in seconds
            "text": string
          },
          [...]
      ],
    },
    [...]
  ],
  "autoTranscription": [
    // for videos longer then 3 hours, there will be multiple entries after auto transcription
    {
      "autoStart": boolean,
      "lastUpdatedAt": Date,
      "data": {
        "id": string,
        "status": "COMPLETED" | "QUEUED" | "IN_PROGRESS" | "FAILED" | "NONE",
        "videoDuration": number,
        "language": string,
        "subtitle": string, // webVTT format
        "transcription": string, // plain text
        "transcriptionParts": [
          {
            "id": number,
            "transcript": string,
            "start_time": number, // in seconds
            "end_time": number // in seconds
          },
          [...]
        ],
        "createdAt": Date,
        "updatedAt": Date,
      }
    },
    ...
  ],
  "createdAt": Date,
  "updatedAt": Date
}

Estado de codificación

Estos campos describen el ciclo de vida de la codificación después de subir o reemplazar un archivo de video.

Ciclo de vida típico

  1. Después de crear un objeto de video, status es NO_FILE hasta que se sube un archivo.
  2. Cuando termina la subida del archivo, comienza la codificación y status pasa a PROGRESSING. statusProgress avanza de 0 hacia 100.
  3. Si tiene éxito, status pasa a COMPLETE, statusProgress es 100, y las fuentes de reproducción están disponibles en src.
  4. Si falla, status pasa a ERROR. Lee errorCode y errorMessage para obtener detalles.

Cuando reemplazas un video, status pasa brevemente a REPLACING mientras se sube el archivo nuevo y luego sigue el mismo camino PROGRESSING → COMPLETE / ERROR.

status

ValorDescripción
NO_FILEEl objeto de video existe, pero aún no se ha subido ningún archivo
PROGRESSINGLa codificación está en curso
REPLACINGSe está subiendo un archivo nuevo para reemplazar el video existente
COMPLETELa codificación finalizó correctamente; las fuentes de reproducción están disponibles en src
ERRORLa codificación falló

statusProgress

Progreso de codificación como porcentaje de 0 a 100.

Mientras status sea PROGRESSING, consulta GET /api/videos/[VIDEO_ID] (ver obtener video) y lee statusProgress para mostrar el progreso en tu UI. Un intervalo de sondeo de unos pocos segundos suele ser suficiente.

También puedes suscribirte a webhooks video.updated. Las actualizaciones de progreso pueden dispararse con frecuencia durante la codificación; debounce las actualizaciones de la UI si es necesario. Ver Webhooks.

Cuando la codificación termina, status pasa a COMPLETE y statusProgress es 100.

errorCode y errorMessage

Cuando status es ERROR, estos campos explican el fallo. Prefiere errorCode para el manejo programático. Usa errorMessage como respaldo legible si no mapeas el código tú mismo.

Ambos campos son null (o están ausentes) cuando el video no está en estado de error.

Ejemplo cuando la codificación falla:

{
  "id": "[VIDEO_ID]",
  "status": "ERROR",
  "statusProgress": 42,
  "errorCode": "MEDIACONVERT_1040",
  "errorMessage": "Invalid or unsupported file format"
}
errorCodeDescripción
DURATION_LIMIT_EXCEEDEDLa duración del video supera el límite de tu cuenta
UNKNOWN_ERRORSe produjo un error desconocido durante el procesamiento
MEDIACONVERT_1040Formato de archivo no válido o no compatible
MEDIACONVERT_1041El archivo de entrada está corrupto o incompleto
MEDIACONVERT_1050Códec de video no compatible
MEDIACONVERT_1060Códec de audio no compatible
MEDIACONVERT_1071Resolución o relación de aspecto de video no válida
MEDIACONVERT_3000Servicio temporalmente no disponible; inténtalo de nuevo más tarde

Pueden aparecer valores adicionales de errorCode con el tiempo. Usa siempre errorMessage (o un mensaje genérico de fallo) para códigos desconocidos.

Miniaturas

src.thumbnails

Variantes multiresolución de la miniatura activa en este momento. El array está ordenado por anchura descendente (primero la mayor resolución). Solo se generan tamaños iguales o menores que la imagen de origen. Resoluciones disponibles: 2160p, 1440p, 1080p, 720p, 480p, 360p, 240p.

{
  "name": "2160p" | "1440p" | "1080p" | "720p" | "480p" | "360p" | "240p",
  "width": number,
  "height": number,
  "formats": {
    "jpeg": { "url": string, "fileSize": number },
    "webp": { "url": string, "fileSize": number }
  }
}

Cada variante de resolución está disponible en formato JPEG y WebP. Usa formats.webp.url para archivos más pequeños o formats.jpeg.url para máxima compatibilidad. Para obtener la miniatura a mayor resolución, usa src.thumbnails[0].formats.jpeg.url (o .webp.url). Para elegir una resolución concreta, filtra el array por name, width o height.

src.thumbnailUrl (obsoleto)

Obsoleto — Usa src.thumbnails en su lugar. Este campo se eliminará en una versión futura.

Contiene la URL de la variante 1080p (o la mayor disponible) de la miniatura activa. Se actualiza automáticamente cuando cambia la miniatura.

Ciclo de vida de las miniaturas

Eventosrc.thumbnailssrc.thumbnailUrl
Finaliza el procesamiento del videoSe rellena con variantes generadasSe establece a la variante 1080p (o la mayor disponible)
Se sube una miniatura personalizadaSe sustituye por nuevas variantesSe actualiza a la variante 1080p (o la mayor disponible)
Miniatura desde marca de tiempoSe sustituye por nuevas variantesSe actualiza a la variante 1080p (o la mayor disponible)
Restablecimiento de miniaturaSe restauran las variantes autogeneradasSe restaura la variante 1080p (o la mayor disponible)

Fuentes de video

Arrays src de video

Los arrays hls y mp4 contienen una lista de todas las fuentes de video disponibles. Están ordenados por calidad, empezando por la mayor. Las variantes de video se generan hasta la resolución del video de entrada. Así, un video subido en 1080p no tendrá variantes 2160p ni 1440p.

{
  "name": "2160p" | "1440p" | "1080p" | "720p" | "540p" | "360p" | "240p",
  "url": string,
  "width": number,
  "height": number
}

Adaptive Bitrate Streaming (ABR)

Si quieres ofrecer tus videos mediante streaming de bitrate adaptativo (abreviado ABR), puedes hacerlo usando src.abr.url como fuente de video. El archivo de lista de reproducción incluye todas las calidades de video indicadas en el array src.hls.

AutenticaciónLista de vídeos