Modifier un asset : ses textes et ses tags

Quatre requêtes modifient un asset déjà dans la bibliothèque, toutes avec une clé qui porte Modifier les contenus de la bibliothèque par l’API (assets.library.edit) :

Chacune répond l’asset entier, tel que le lit GET /v1/assets/{asset_id} : une seule forme à lire, quoi que vous ayez écrit.

Aucune permission n’en implique une autre : une clé qui modifie ne lit pas pour autant la bibliothèque. Une écriture répond ce qu’elle a écrit dans tous les cas, mais pour retrouver un asset avant de le modifier — par votre external_ref, par exemple —, la clé doit aussi porter Lire la bibliothèque par l’API (assets.library.read).

Changer ses textes

PATCH /v1/assets/{asset_id} écrit les champs que vous envoyez, et ceux-là seulement :

curl -X PATCH https://api.videas.com/v1/assets/0192a6e4-3b5c-7d6e-8f90-a1b2c3d4e5f6 \
  -H "Authorization: Bearer $VIDEAS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "excerpt": "Trois procédés de recyclage, essayés sur les mêmes chutes.",
    "seo_title": "Recycler la fibre de carbone : pyrolyse, solvolyse ou broyage ?",
    "copyright": null
  }'

Absent, null ou une valeur

• Un champ absent reste tel quel.
• Une valeur le remplace.
• null le vide — sauf name, refusé par un 400. Une language vidée devient inconnue.
• Une chaîne vide vide aussi description, excerpt et copyright ; sur name, external_ref, seo_title et seo_description, elle est refusée par un 400 — envoyez null pour les vider.

La réponse est un 200 portant l’asset tel qu’il est désormais :

{
  "id": "0192a6e4-3b5c-7d6e-8f90-a1b2c3d4e5f6",
  "name": "Recycler la fibre de carbone : trois procédés comparés",
  "type": "third_party",
  "status": "ready",
  "workspace_id": "0192a6b1-7c3e-7d40-9a51-3f0e2b6c8d10",
  "description": "Pyrolyse, solvolyse et broyage mécanique, comparés sur les mêmes chutes de production.",
  "external_ref": "webtv/2026/recyclage-fibre-carbone",
  "language": "fr",
  "duration_ms": null,
  "created_at": "2026-10-15T08:30:12Z",
  "updated_at": "2026-10-15T08:30:14Z",
  "third_party": {
    "provider": "youtube",
    "video_id": "Xk3Ua9yQe7M",
    "player_url": "https://www.youtube.com/embed/Xk3Ua9yQe7M"
  },
  "thumbnail_url": "https://app.videas.com/images/assets/0192a6e4-3b5c-7d6e-8f90-a1b2c3d4e5f6/thumbnail.jpg",
  "excerpt": "Trois procédés de recyclage, essayés sur les mêmes chutes.",
  "copyright": null,
  "seo_title": "Recycler la fibre de carbone : pyrolyse, solvolyse ou broyage ?",
  "seo_description": null,
  "tags": [],
  "custom_fields": []
}

Ce qui ne se change pas ici : le type de l’asset, son adresse, sa visibilité, son expiration, sa licence et sa vignette. Un corps qui nomme l’un de ces champs — ou n’importe quel champ que la requête ne liste pas — est refusé par un 422. La vignette se change par PUT …/thumbnail.

Ses tags

PUT /v1/assets/{asset_id}/tags range l’asset sous les tags que vous nommez, par leurs mots — pas par leurs identifiants :

curl -X PUT https://api.videas.com/v1/assets/0192a6e4-3b5c-7d6e-8f90-a1b2c3d4e5f6/tags \
  -H "Authorization: Bearer $VIDEAS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"tags": ["Fibre de carbone", "Recyclage"]}'

La réponse est l’asset entier, ses tags par ordre alphabétique :

{
  "id": "0192a6e4-3b5c-7d6e-8f90-a1b2c3d4e5f6",
  "updated_at": "2026-10-15T08:30:14Z",
  "tags": [
    { "id": "0192a690-3d4e-7f5a-8b6c-7d8e9f0a1b2c", "name": "Fibre de carbone" },
    { "id": "0192a690-4e5f-7a6b-9c7d-8e9f0a1b2c3d", "name": "Recyclage" }
  ]
}

(extrait : la réponse porte tous les champs de l’asset.)

La liste remplace les tags de l’asset — sauf ceux que Videas pose lui-même

Les tags que vous envoyez remplacent ceux de l’asset. Un tag absent de la liste lui est retiré, et une liste vide, {"tags": []}, lui retire tous les vôtres. Les tags que Videas pose lui-même restent, quoi que vous envoyiez : la réponse les porte à côté des vôtres. Envoyez donc la liste complète de ce que l’asset doit porter, jamais un ajout.

Seul Videas pose ses propres tags. Un mot qui en nomme un ne change rien là où l’asset le porte déjà, et il est refusé par un 400 là où il ne le porte pas.

Un mot, un tag

Un mot est rapproché d’un tag par ses lettres et ses chiffres : la casse et les accents ne comptent pas, et toute suite d’espaces ou de ponctuation compte pour un seul séparateur. Fibre de carbone, fibre-de-carbone et FIBRE DE CARBONE sont un seul tag ; fibredecarbone en est un autre. Deux mots de votre liste qui désignent le même tag n’en posent qu’un.

Chaque mot est cherché d’abord parmi les tags du workspace de l’asset, puis parmi ceux de l’organisation. Un mot qui ne correspond à aucun devient un nouveau tag de l’organisation, écrit comme vous l’avez écrit ; un tag qui existe déjà garde sa propre graphie.

Un workspace peut n’accepter que les tags qu’il a déjà. Là, un mot qui ne correspond à aucun tag est refusé par un 400 — dont le message cite les dix premiers mots en cause et compte les autres — et rien ne change.

Les bornes : 100 mots au plus, chacun de 100 caractères au plus une fois ses espaces de bord retirés, jamais vide, et portant au moins une lettre latine ou un chiffre. Un mot refusé est désigné par sa position dans la liste, à partir de 0.

Un tag qu’une machine a suggéré et que personne n’a confirmé ne figure pas dans tags.

updated_at, et ce qui ne change rien

• updated_at bouge avec les textes de l’asset et avec sa vignette, jamais avec ses tags ni ses champs personnalisés. Pour savoir si un asset a changé depuis votre dernière synchronisation, comparez donc aussi ses tags et ses custom_fields.
• Une requête qui ne change rien n’écrit rien : renvoyer ce que l’asset porte déjà — ses textes, ses tags — le laisse tel quel, updated_at compris.
• La dernière requête arrivée l’emporte : rien ne vérifie ce que l’asset portait quand vous l’avez lu.

Ce que voit l’équipe

Une modification qu’une clé apporte au titre, à la description, au résumé, à la mention de droits ou à la langue d’un asset, à ses tags ou à ses champs personnalisés est inscrite dans l’historique de l’asset, dans Videas, sous le nom de la clé. Les personnes qui s’occupent de la bibliothèque voient ainsi quelle intégration a fait quoi : donnez à chaque clé un nom qui le dise — « Synchro CMS », « Import catalogue ».

Un asset validé dans le fonds commun est en lecture seule

Un asset que l’organisation a validé dans son fonds commun ne se modifie pas par l’API : chacune des quatre requêtes est refusée par un 403, quelles que soient les permissions de la clé. Seuls les modérateurs de ce fonds commun peuvent le modifier, depuis Videas.

Ce 403 porte le même code, forbidden, que celui d’une clé sans assets.library.edit. Si votre clé modifie d’autres assets sans encombre et qu’un seul la refuse, c’est ce verrou : ne relancez pas, signalez-le à l’équipe qui modère le fonds commun.

Relancer

PATCH et PUT disent ce que l’asset doit porter : renvoyés tels quels après une expiration ou une 5xx, ils ne font rien de plus, la seconde trouvant l’asset déjà dans cet état.

Erreurs

Toutes les erreurs ont le même corps — {"code": "…", "message": "…", "request_id": "…"}. Testez code ; message s’adresse à un humain et peut changer.

Pour aller plus loin

• Les champs personnalisés — les champs propres à votre organisation, et leurs valeurs.
• La vignette d’un asset — l’envoyer, et l’afficher.
• Lire la bibliothèque — chaque champ d’un asset.
• La référence de l’API, générée depuis son contrat.