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",
  "language": string,
  "aiContent": "none" | "generated" | "modified",
  "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
      },
      [...]
    ],
    "audio": [
      {
        "name": string, // for example "high-quality" or "low-quality"
        "url": string
      },
      [...]
    ]
  },
  "texttracks": [
    {
      "id": string,
      "language": "en-US" | "de-DE" | "...", // region locale
      "filename": string,
      "type": "subtitles" | "captions",
      "url": string,
      "autoGenerated": boolean,
      "autoTranslated": boolean,
      "edited": boolean,
      "updatedAt": Date,
      "content": string // URL-encoded placeholder. GET the track for the WebVTT.
    },
    [...]
  ],
  "chapters": [
    {
      "id": string,
      "title": string,
      "timestamp": string, // 00:00:00
    },
    [...]
  ],
  "categories": [
    {
      "id": string,
      "title": string,
      "slug": string,
      "description": string,
    },
    [...]
  ],
  "tags": [
    {
      "id": string,
      "title": string,
      "slug": string,
      "description": 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
          },
          [...]
      ],
    },
    [...]
  ],
  "audiotracks": [ ... ], // present on the object; ignored by PATCH
  "autoTranscription": {
    "autoStart": boolean,
    "lastUpdatedAt": Date,
    "data": object // transcription records; population follows depth
  },
  "contentUpdatedAt": Date, // bumped on content writes; not writable
  "customMetadata": object,
  "passwordProtection": {
    "enabled": boolean,
    "password": string // present for callers who can update the video
  },
  "previewVideoUrl": string,
  "previewThumbnailUrl": string,
  "previewThumbnailUrlSmall": string,
  "player": {
    "selectedPreset": object | null, // player preset object
    "useCustomDesign": boolean,
    "playerDesign": { ... }, // player design properties, see "Player settings"
    "shareUrl": string
  },
  "workspace": string, // workspace id; stays an id at every depth
  "createdAt": Date,
  "updatedAt": Date
}

aiContent

Marca de contenido IA para contenido generado o modificado con IA que podría parecer auténtico, como exigen normativas como el Reglamento de IA de la UE (art. 50). none (predeterminado) significa que el reproductor embebido nunca muestra la etiqueta IA. generated y modified muestran la etiqueta IA en el reproductor cuando la opción de diseño aiContentLabel no es off.

v

Versión del archivo. Empieza en 0 y aumenta cuando un archivo de reemplazo termina la codificación.

autoTranscription

autoTranscription es un único objeto con autoStart, lastUpdatedAt y data. autoStart indica si la transcripción empieza después de la codificación. data guarda los registros de transcripción relacionados, y su población sigue depth. Los videos de más de 3 horas generan varios trabajos de transcripción. Consulta transcribe para esos registros de trabajo.

contentUpdatedAt

Marca de tiempo que se actualiza en las escrituras de contenido. No puedes establecer este campo.

customMetadata

Un objeto plano de datos personalizados, con 50 claves como máximo. Cada clave coincide con ^[a-zA-Z0-9_-]+$ y tiene 40 caracteres como máximo. Cada valor es una cadena de 500 caracteres como máximo, un número finito o un booleano. Los objetos anidados y los arrays se rechazan. Una escritura posterior se fusiona con el objeto almacenado. Enviar "" o null para una clave elimina esa clave. Puedes establecerlo al crear o actualizar un video.

passwordProtection

enabled indica si el video requiere una contraseña. password se incluye para quien puede actualizar el video, cuando el espacio de trabajo tiene la protección por contraseña activada. En una actualización, password debe tener al menos 8 caracteres. El campo solo se puede escribir mientras esa función está activa.

categories y tags

Con la profundidad predeterminada, cada entrada es un objeto con id, title, slug y description. Con depth=0, cada entrada es un id. Una lista vacía es null.

URLs de vista previa

previewVideoUrl, previewThumbnailUrl y previewThumbnailUrlSmall son URLs de vista previa firmadas. Se añaden en la lectura cuando existen rendiciones.

Ajustes del reproductor

La propiedad player contiene el diseño del reproductor del video. Solo se incluye en las respuestas a solicitudes con una Clave API. Los payloads de webhook no la incluyen.

selectedPreset y useCustomDesign solo se incluyen si tu plan incluye diseños de reproductor personalizados y el espacio de trabajo tiene al menos un preset del reproductor.

Para encontrar el diseño que usa el reproductor:

1. Si useCustomDesign es true o selectedPreset es null, usa playerDesign.
2. De lo contrario, usa las propiedades de diseño de selectedPreset.

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

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"
}

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)

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

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.

src.audio

src.audio enumera las rendiciones de audio del video. Cada entrada tiene name y url. name es una etiqueta como high-quality o low-quality.