L’objet vidéo

L’objet vidéo est un objet JSON avec les propriétés suivantes :

{
  "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 contenu IA pour les contenus générés ou modifiés par IA pouvant paraître authentiques, comme l’exigent des réglementations telles que l’AI Act européen (art. 50). none (par défaut) signifie que le lecteur embed n’affiche jamais le label IA. generated et modified affichent le label IA dans le lecteur lorsque l’option de design aiContentLabel n’est pas off.

v

Version du fichier. Elle commence à 0 et s’incrémente lorsqu’un fichier de remplacement a terminé l’encodage.

autoTranscription

autoTranscription est un seul objet, avec autoStart, lastUpdatedAt et data. autoStart indique si la transcription démarre après l’encodage. data contient les enregistrements de transcription liés, et sa population suit depth. Les vidéos de plus de 3 heures produisent plusieurs jobs de transcription. Interroge transcrire pour ces enregistrements de jobs.

contentUpdatedAt

Horodatage mis à jour lors des écritures de contenu. Tu ne peux pas définir ce champ.

customMetadata

Objet plat de données personnalisées, avec 50 clés maximum. Chaque clé correspond à ^[a-zA-Z0-9_-]+$ et fait 40 caractères maximum. Chaque valeur est une chaîne de 500 caractères maximum, un nombre fini ou un booléen. Les objets imbriqués et les tableaux sont rejetés. Une écriture ultérieure fusionne avec l’objet stocké. Envoyer "" ou null pour une clé supprime cette clé. Tu peux le définir lorsque tu crées ou mets à jour une vidéo.

passwordProtection

enabled indique si la vidéo exige un mot de passe. password est inclus pour les appelants qui peuvent mettre à jour la vidéo, lorsque l’espace de travail a la protection par mot de passe activée. Lors d’une mise à jour, password doit faire au moins 8 caractères. Le champ n’est modifiable que tant que cette fonction est activée.

categories et tags

À la profondeur par défaut, chaque entrée est un objet avec id, title, slug et description. Avec depth=0, chaque entrée est un id. Une liste vide vaut null.

URLs de prévisualisation

previewVideoUrl, previewThumbnailUrl et previewThumbnailUrlSmall sont des URL de prévisualisation signées. Elles sont ajoutées lors de la lecture de l’objet, lorsque des rendus existent.

Configuration du lecteur

La propriété player contient le design du lecteur de la vidéo. Elle n’est incluse que dans les réponses aux requêtes effectuées avec une Clé API. Les payloads de webhook ne l’incluent pas.

selectedPreset et useCustomDesign ne sont inclus que si ton abonnement comprend les designs de lecteur personnalisés et que l’espace de travail possède au moins un preset de lecteur.

Pour trouver le design utilisé par le lecteur :

1. Si useCustomDesign vaut true ou si selectedPreset vaut null, utilise playerDesign.
2. Sinon, utilise les propriétés de design de selectedPreset.

Statut d’encodage

Ces champs décrivent le cycle de vie de l’encodage après le téléchargement ou le remplacement d’un fichier vidéo.

Cycle de vie typique

1. Après la création d’un objet vidéo, status vaut NO_FILE jusqu’à ce qu’un fichier soit téléchargé.
2. Une fois le téléchargement du fichier terminé, l’encodage démarre et status devient PROGRESSING. statusProgress progresse de 0 vers 100.
3. En cas de succès, status devient COMPLETE, statusProgress vaut 100, et les sources de lecture sont disponibles sous src.
4. En cas d’échec, status devient ERROR. Lis errorCode et errorMessage pour les détails.

Quand tu remplaces une vidéo, status devient brièvement REPLACING pendant le téléchargement du nouveau fichier, puis suit le même chemin PROGRESSING → COMPLETE / ERROR.

status

statusProgress

Progression de l’encodage en pourcentage de 0 à 100.

Tant que status est PROGRESSING, interroge GET /api/videos/[VIDEO_ID] (voir obtenir la vidéo) et lis statusProgress pour afficher la progression dans ton interface. Un intervalle de sondage de quelques secondes suffit généralement.

Tu peux aussi t’abonner aux webhooks video.updated. Les mises à jour de progression peuvent se déclencher souvent pendant l’encodage — debounce les mises à jour de l’interface si nécessaire. Voir Webhooks.

Une fois l’encodage terminé, status devient COMPLETE et statusProgress vaut 100.

errorCode et errorMessage

Lorsque status est ERROR, ces champs expliquent l’échec. Privilégie errorCode pour le traitement programmatique. Utilise errorMessage comme repli lisible si tu ne fais pas toi-même la correspondance du code.

Les deux champs valent null (ou sont absents) lorsque la vidéo n’est pas en état d’erreur.

Exemple en cas d’échec de l’encodage :

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

D’autres valeurs errorCode peuvent apparaître avec le temps. Pour les codes inconnus, reviens toujours à errorMessage (ou à un message d’échec générique).

Miniatures

src.thumbnails

Variantes multi-résolution de la miniature actuellement active. Le tableau est trié par largeur décroissante (résolution la plus élevée en premier). Seules les tailles inférieures ou égales à l’image source sont générées. Résolutions 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 }
  }
}

Chaque variante de résolution est disponible au format JPEG et WebP. Utilise formats.webp.url pour des fichiers plus légers ou formats.jpeg.url pour une compatibilité maximale. Pour obtenir la miniature en plus haute résolution, utilise src.thumbnails[0].formats.jpeg.url (ou .webp.url). Pour choisir une résolution précise, filtre le tableau par name, width ou height.

src.thumbnailUrl (déprécié)

Contient l’URL de la variante 1080p (ou la plus haute disponible) de la miniature active. Mis à jour automatiquement à chaque changement de miniature.

Cycle de vie des miniatures

Sources vidéo

Tableaux src vidéo

Les tableaux hls et mp4 contiennent la liste de toutes les sources vidéo disponibles pour la vidéo. Les tableaux sont triés par qualité, en commençant par la plus haute. Les variantes vidéo sont générées jusqu’à la résolution de la vidéo d’entrée. Ainsi, une vidéo 1080p téléchargée n’aura pas de variante 2160p ni 1440p.

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

Adaptive Bitrate Streaming (ABR)

Si tu veux diffuser tes vidéos en streaming à débit adaptatif (abrégé ABR), tu peux utiliser src.abr.url comme source vidéo. Le fichier playlist regroupe toutes les qualités fournies listées dans le tableau src.hls.

src.audio

src.audio liste les rendus audio de la vidéo. Chaque entrée a name et url. name est un libellé tel que high-quality ou low-quality.