L’oggetto video

L’oggetto video è un oggetto JSON con le seguenti proprietà:

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

Tag contenuto IA per contenuti generati o modificati con IA che potrebbero sembrare autentici, come richiesto da normative quali l’AI Act europeo (art. 50). none (predefinito) significa che il player embed non mostra mai l’etichetta IA. generated e modified mostrano l’etichetta IA nel player quando l’opzione di design aiContentLabel non è off.

v

Versione del file. Parte da 0 e aumenta quando un file sostitutivo termina la codifica.

autoTranscription

autoTranscription è un singolo oggetto con autoStart, lastUpdatedAt e data. autoStart indica se la trascrizione parte dopo la codifica. data contiene i record di trascrizione correlati e il suo popolamento segue depth. I video più lunghi di 3 ore producono più job di trascrizione. Interroga transcribe per quei record di job.

contentUpdatedAt

Timestamp aggiornato alle scritture del contenuto. Non puoi impostare questo campo.

customMetadata

Un oggetto piatto di dati personalizzati, con al massimo 50 chiavi. Ogni chiave corrisponde a ^[a-zA-Z0-9_-]+$ e ha al massimo 40 caratteri. Ogni valore è una stringa di al massimo 500 caratteri, un numero finito o un booleano. Oggetti annidati e array vengono rifiutati. Una scrittura successiva unisce i campi all’oggetto salvato. Se invii "" o null per una chiave, quella chiave viene eliminata. Puoi impostarlo quando crei o aggiorni un video.

passwordProtection

enabled indica se il video richiede una password. password è inclusa per chi può aggiornare il video, quando il workspace ha la protezione con password abilitata. In aggiornamento, password deve avere almeno 8 caratteri. Il campo è scrivibile solo mentre quella funzione è attiva.

categories e tags

Con il depth predefinito ogni voce è un oggetto con id, title, slug e description. Con depth=0 ogni voce è un id. Una lista vuota è null.

URL di anteprima

previewVideoUrl, previewThumbnailUrl e previewThumbnailUrlSmall sono URL di anteprima firmati. Vengono aggiunti in lettura quando esistono le rendition.

Impostazioni del player

La proprietà player contiene il design del player del video. È inclusa solo nelle risposte alle richieste con una chiave API. I payload dei webhook non la includono.

selectedPreset e useCustomDesign sono inclusi solo se il tuo piano comprende design del player personalizzati e il workspace ha almeno un preset del player.

Per trovare il design che usa il player:

1. Se useCustomDesign è true o selectedPreset è null, usa playerDesign.
2. Altrimenti, usa le proprietà di design di selectedPreset.

Stato di codifica

Questi campi descrivono il ciclo di vita della codifica dopo il caricamento o la sostituzione di un file video.

Ciclo di vita tipico

1. Dopo la creazione di un oggetto video, status è NO_FILE finché non viene caricato un file.
2. Al termine del caricamento del file, inizia la codifica e status diventa PROGRESSING. statusProgress passa da 0 verso 100.
3. In caso di successo, status diventa COMPLETE, statusProgress è 100, e le sorgenti di riproduzione sono disponibili in src.
4. In caso di errore, status diventa ERROR. Leggi errorCode e errorMessage per i dettagli.

Quando sostituisci un video, status diventa brevemente REPLACING durante il caricamento del nuovo file, poi segue lo stesso percorso PROGRESSING → COMPLETE / ERROR.

status

statusProgress

Avanzamento della codifica come percentuale da 0 a 100.

Mentre status è PROGRESSING, interroga GET /api/videos/[VIDEO_ID] (vedi ottenere video) e leggi statusProgress per mostrare l’avanzamento nella tua UI. Un intervallo di polling di pochi secondi di solito è sufficiente.

Puoi anche iscriverti ai webhook video.updated. Gli aggiornamenti di progresso possono scattare spesso durante la codifica; debounce gli aggiornamenti dell’UI se necessario. Vedi Webhooks.

Al termine della codifica, status diventa COMPLETE e statusProgress è 100.

errorCode e errorMessage

Quando status è ERROR, questi campi spiegano il fallimento. Preferisci errorCode per la gestione programmatica. Usa errorMessage come fallback leggibile se non mappi il codice tu stesso.

Entrambi i campi sono null (o assenti) quando il video non è in stato di errore.

Esempio quando la codifica fallisce:

{
  "id": "[VIDEO_ID]",
  "status": "ERROR",
  "statusProgress": 42,
  "errorCode": "MEDIACONVERT_1040",
  "errorMessage": "Invalid or unsupported file format"
}

Possono comparire altri valori di errorCode nel tempo. Usa sempre errorMessage (o un messaggio di errore generico) per codici sconosciuti.

Miniature

src.thumbnails

Varianti multirisoluzione della miniatura attualmente attiva. L’array è ordinato per larghezza decrescente (risoluzione più alta per prima). Vengono generate solo dimensioni uguali o inferiori all’immagine sorgente. Risoluzioni disponibili: 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 }
  }
}

Ogni variante di risoluzione è disponibile sia in formato JPEG che WebP. Usa formats.webp.url per dimensioni file minori o formats.jpeg.url per la massima compatibilità. Per ottenere la miniatura alla risoluzione più alta, usa src.thumbnails[0].formats.jpeg.url (o .webp.url). Per selezionare una risoluzione specifica, filtra l’array per name, width o height.

src.thumbnailUrl (deprecato)

Contiene l’URL della variante 1080p (o la più alta disponibile) della miniatura attualmente attiva. Si aggiorna automaticamente ogni volta che cambia la miniatura.

Ciclo di vita delle miniature

Sorgenti video

Array src del video

Gli array hls e mp4 contengono l’elenco di tutte le sorgenti video disponibili per il video. Gli array sono ordinati per qualità, partendo dalla qualità più alta. Le varianti video vengono generate fino alla risoluzione del video in ingresso. Quindi un video caricato in 1080p non avrà varianti 2160p e 1440p.

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

Adaptive Bitrate Streaming (ABR)

Se vuoi fornire i tuoi video tramite streaming a bitrate adattivo (in breve ABR), puoi farlo usando src.abr.url come sorgente video. Il file playlist elenca tutte le qualità video fornite nell’array src.hls.

src.audio

src.audio elenca le rendition audio del video. Ogni voce ha name e url. name è un’etichetta come high-quality o low-quality.