La vignette d'un asset

La vignette d’un asset est l’image sous laquelle il se présente — dans Videas, sur ses chaînes, et dans vos propres pages. L’API l’écrit et la sert :

• PUT /v1/assets/{asset_id}/thumbnail choisit la vignette, en l’envoyant ;
• thumbnail_url, sur chaque asset que renvoient GET /v1/assets et GET /v1/assets/{asset_id}, est l’adresse où l’afficher.

Envoyer une vignette

Le corps de la requête est l’image elle-même, pas du JSON : un JPEG, un PNG ou un WebP de 10 Mio au plus, avec un Content-Type qui dit lequel. La clé doit porter Modifier les contenus de la bibliothèque par l’API (assets.library.edit).

curl -X PUT https://api.videas.com/v1/assets/0192a6e4-3b5c-7d6e-8f90-a1b2c3d4e5f6/thumbnail \
  -H "Authorization: Bearer $VIDEAS_API_KEY" \
  -H "Content-Type: image/jpeg" \
  --data-binary @vignette.jpg

Le même envoi en Node.js (18 ou plus) et en Python :

import { readFile } from 'node:fs/promises'

const response = await fetch(
  'https://api.videas.com/v1/assets/0192a6e4-3b5c-7d6e-8f90-a1b2c3d4e5f6/thumbnail',
  {
    method: 'PUT',
    headers: {
      Authorization: `Bearer ${process.env.VIDEAS_API_KEY}`,
      'Content-Type': 'image/webp',
    },
    body: await readFile('vignette.webp'),
  },
)
const asset = await response.json()
if (!response.ok) throw new Error(`${asset.code}: ${asset.message}`)

import os

import requests

with open("vignette.png", "rb") as picture:
    response = requests.put(
        "https://api.videas.com/v1/assets/0192a6e4-3b5c-7d6e-8f90-a1b2c3d4e5f6/thumbnail",
        headers={
            "Authorization": f"Bearer {os.environ['VIDEAS_API_KEY']}",
            "Content-Type": "image/png",
        },
        data=picture,
    )
response.raise_for_status()

L’image devient celle sous laquelle l’asset se présente, dans Videas et sur ses chaînes, et celle que sert désormais son thumbnail_url. La réponse est un 200 portant l’asset entier, tel que le lit GET /v1/assets/{asset_id}.

• Envoyer l’image que l’asset porte déjà ne change rien — pas même son updated_at.
• Une vignette différente, elle, fait bouger updated_at, comme ses textes.
• La dernière requête arrivée l’emporte, et un PUT renvoyé tel quel après une expiration ou une 5xx ne fait rien de plus.
• Un asset validé dans le fonds commun de l’organisation est refusé par un 403, comme pour ses textes.

Une vidéo ajoutée depuis YouTube, Vimeo ou Dailymotion prend l’affiche de son fournisseur quand elle arrive à temps ; cette requête la remplace, ou en donne une à l’asset qui n’en a pas.

Afficher la vignette : thumbnail_url

{
  "id": "0192a6e4-3b5c-7d6e-8f90-a1b2c3d4e5f6",
  "thumbnail_url": "https://app.videas.com/images/assets/0192a6e4-3b5c-7d6e-8f90-a1b2c3d4e5f6/thumbnail.jpg"
}

thumbnail_url est l’adresse de la vignette de l’asset — celle que l’organisation a choisie, sinon celle que Videas a retenue —, et vaut null tant qu’il n’en a aucune.

• Elle est stable et anonyme. Elle ne demande aucune clé : mettez-la telle quelle dans le <img> d’une page web.
• Elle suit l’asset, pas une image : quand une autre vignette est choisie, la même adresse sert la nouvelle. Conservez l’adresse, pas les octets.
• Elle est sur le domaine de l’application Videas de votre organisation, pas sur celui de l’API.
• Elle sert un JPEG à la taille de l’image, 3 840 pixels de côté au plus.
• Ses réponses peuvent être gardées en cache quelques minutes et portent un ETag : une vignette qui vient de changer peut mettre ces quelques minutes à apparaître.

<img
  src="https://app.videas.com/images/assets/0192a6e4-3b5c-7d6e-8f90-a1b2c3d4e5f6/thumbnail.jpg"
  alt="Recycler la fibre de carbone : trois procédés comparés"
  loading="lazy"
/>

D’autres formats, d’autres tailles

La même adresse sert d’autres formats et d’autres tailles en changeant son dernier segment :

Dans la dernière forme :

• fit vaut cover — l’image remplit le cadre et y est recadrée — ou contain — elle tient dans le cadre, sans jamais être recadrée ;
• ext vaut jpg, webp ou png ;
• par exemple cover-320x180.jpg ou contain-1280x720.webp.

Les cadres servis forment une liste fixe. Un cadre qui n’en fait pas partie est redirigé (308) vers le plus petit cadre servi qui le couvre ; un navigateur suit la redirection de lui-même. Une image n’est jamais agrandie.

Un srcset se construit donc à partir de thumbnail_url :

function pictureSources(thumbnailUrl) {
  const base = thumbnailUrl.slice(0, thumbnailUrl.lastIndexOf('/') + 1)
  return {
    src: `${base}cover-640x360.jpg`,
    srcset: [320, 640, 1280]
      .map((width) => `${base}cover-${width}x${(width * 9) / 16}.webp ${width}w`)
      .join(', '),
  }
}

<img
  src="https://app.videas.com/images/assets/0192a6e4-…/cover-640x360.jpg"
  srcset="https://app.videas.com/images/assets/0192a6e4-…/cover-320x180.webp 320w,
          https://app.videas.com/images/assets/0192a6e4-…/cover-640x360.webp 640w,
          https://app.videas.com/images/assets/0192a6e4-…/cover-1280x720.webp 1280w"
  sizes="(max-width: 640px) 100vw, 640px"
  width="640" height="360"
  alt="Recycler la fibre de carbone : trois procédés comparés"
  loading="lazy"
/>

Quand l’adresse répond 404

thumbnail_url répond 404 dès que l’asset est supprimé ou masqué, ou qu’il n’a plus de vignette. Ce n’est pas une panne passagère : relisez l’asset avec GET /v1/assets/{asset_id} — un 404 là aussi dit qu’il n’est plus dans la bibliothèque, et un thumbnail_url à null qu’il n’a plus d’image.

Erreurs

Toutes les erreurs de PUT …/thumbnail ont le même corps JSON — {"code": "…", "message": "…", "request_id": "…"} —, même si la requête, elle, envoie une image.

Pour aller plus loin

• Modifier un asset — ses textes et ses tags.
• Lire la bibliothèque — où thumbnail_url figure sur chaque asset.
• La référence de l’API, générée depuis son contrat.