Aller au contenu principal
videas.comContacter le supportOuvrir l'app

Lire la bibliothèque

Listez et comptez les assets et les workspaces de votre organisation avec l'API Videas, lisez un asset avec ses tags et ses champs personnalisés, filtrez par type, par workspace ou par votre propre référence, et parcourez toutes les pages avec un curseur.

Mis à jour le 15 oct. 2026apiv1assetsworkspacespaginationfiltres

La bibliothèque de votre organisation se compose d’assets — vidéos, sons, images, documents et autres fichiers —, et chaque asset se trouve dans un seul workspace. L’API lit les deux, avec une clé qui porte Lire la bibliothèque par l’API (assets.library.read) ; Démarrer explique comment la créer.

Tous les exemples ci-dessous envoient la clé depuis la variable d’environnement VIDEAS_API_KEY.

Lister les assets

curl https://api.videas.com/v1/assets \
  -H "Authorization: Bearer $VIDEAS_API_KEY"

GET /v1/assets renvoie chaque asset visible de l’organisation dont le premier upload a commencé — un asset en cours d’envoi y figure, uploading —, dans tous les workspaces, du plus ancien au plus récent. Les dossiers et les collections n’y figurent pas. Chaque ligne porte :

Champ
id L’identifiant de l’asset — stable toute sa vie, et celui à conserver.
name Son titre. Jamais vide.
type Sa nature : video, audio, image, document, archive, file, subtitles, third_party ou other.
status Où en est son traitement : uploading, processing, ready ou error. Seul un asset ready peut être lu.
workspace_id Le workspace où il se trouve — l’id de l’un de ceux de GET /v1/workspaces.
description Sa description, ou null.
external_ref Votre identifiant pour lui, s’il en a un, ou null. Pas unique.
language La langue de son contenu, en balise BCP 47 (fr, en-GB), ou null.
duration_ms Sa durée en millisecondes pour une vidéo ou un son, ou null.
created_at Sa création (RFC 3339). Les listes sont rangées selon cet instant, puis selon id.
updated_at Sa dernière modification (RFC 3339) — sauf ses tags et ses champs personnalisés : les changer ne le fait pas bouger.
third_party Pour un asset de type third_party, la vidéo qu’il lit sur le site d’un autre fournisseur : provider (youtube, vimeo, dailymotion ou other), video_id, l’identifiant de la vidéo chez lui, et player_url, l’adresse de son lecteur à mettre dans un <iframe>. null pour tout autre type.
thumbnail_url L’adresse de sa vignette — stable, anonyme, à mettre telle quelle dans un <img> —, ou null s’il n’en a pas. La vignette d’un asset dit ses formats et ses tailles.

Les listes de valeurs de type, de status et de third_party.provider peuvent s’allonger : lisez une valeur inconnue comme une valeur que votre code ne traite pas encore, pas comme une erreur — un fournisseur inconnu, comme other.

Filtrer

Trois filtres restreignent la liste, et se combinent :

Paramètre Garde Exemple
type les assets de ces types ?type=video,audio
workspace_id les assets de ces workspaces ?workspace_id=0192a6b1-…,0192a6b5-…
external_ref les assets dont l’external_ref vaut exactement ceci, aux espaces qui l’entourent près ?external_ref=cours-42%2Fseance-1

type et workspace_id prennent plusieurs valeurs dans une seule clé, séparées par des virgules. external_ref n’en prend qu’une, car vos propres identifiants peuvent contenir des virgules : encodez-la comme toute valeur de requête.

curl "https://api.videas.com/v1/assets?type=video&workspace_id=0192a6b1-7c3e-7d40-9a51-3f0e2b6c8d10" \
  -H "Authorization: Bearer $VIDEAS_API_KEY"

Un paramètre que l’endpoint ne connaît pas est refusé, tout comme une clé donnée deux fois : ?typ=video ou ?type=video&type=audio répondent un 400, jamais une liste discrètement non filtrée. Un workspace_id étranger à votre organisation ne correspond simplement à rien.

Parcourir toutes les pages

Une page contient data — les lignes — et next, le curseur de la page suivante. Renvoyez next dans after, avec les mêmes filtres, jusqu’à ce qu’il vaille null :

curl "https://api.videas.com/v1/assets?type=video&after=MDE5MmE2YjItNGYxYS03Yjkw…" \
  -H "Authorization: Bearer $VIDEAS_API_KEY"
  • limit fixe le nombre de lignes par page ; une valeur au-dessus du plafond de l’endpoint est ramenée à ce plafond plutôt que refusée.
  • order=desc lit du plus récent au plus ancien ; asc, du plus ancien au plus récent, est la valeur par défaut.
  • after n’accepte qu’un next renvoyé par le même endpoint : le curseur est opaque, et un curseur venu d’ailleurs vaut un 400.
  • Une page ne porte ni décalage ni total : pour savoir combien, comptez.

Le parcours complet, en Node.js et en Python :

async function allAssets(filters = {}) {
  const assets = []
  let after = null
  do {
    const query = new URLSearchParams({ ...filters, ...(after ? { after } : {}) })
    const response = await fetch(`https://api.videas.com/v1/assets?${query}`, {
      headers: { Authorization: `Bearer ${process.env.VIDEAS_API_KEY}` },
    })
    const page = await response.json()
    if (!response.ok) throw new Error(`${page.code}: ${page.message}`)
    assets.push(...page.data)
    after = page.next
  } while (after)
  return assets
}

const videos = await allAssets({ type: 'video' })
import os

import requests

def all_assets(**filters):
    headers = {"Authorization": f"Bearer {os.environ['VIDEAS_API_KEY']}"}
    params = dict(filters)
    while True:
        response = requests.get("https://api.videas.com/v1/assets", headers=headers, params=params)
        response.raise_for_status()
        page = response.json()
        yield from page["data"]
        if page["next"] is None:
            return
        params["after"] = page["next"]

videos = list(all_assets(type="video"))

Compter

GET /v1/assets/count compte ce que renverrait la liste, avec les mêmes filtres — et ne prend aucun autre paramètre :

curl "https://api.videas.com/v1/assets/count?type=video" \
  -H "Authorization: Bearer $VIDEAS_API_KEY"
# → { "count": 42 }

Le compte est pris au moment de la demande : un parcours commencé ensuite peut rencontrer des assets créés ou supprimés entre-temps.

Lire un asset

GET /v1/assets/{asset_id} renvoie tous les champs que la liste donne sur un asset, sous les mêmes noms, et ceux qu’une liste laisse de côté :

curl https://api.videas.com/v1/assets/0192a6b2-4f1a-7b90-8e0d-51c3a7f2b046 \
  -H "Authorization: Bearer $VIDEAS_API_KEY"
{
  "id": "0192a6b2-4f1a-7b90-8e0d-51c3a7f2b046",
  "name": "Cours d’ouverture",
  "type": "video",
  "status": "ready",
  "workspace_id": "0192a6b1-7c3e-7d40-9a51-3f0e2b6c8d10",
  "description": null,
  "external_ref": "cours-42/seance-1",
  "language": "fr",
  "duration_ms": 2712000,
  "created_at": "2026-09-26T09:12:44Z",
  "updated_at": "2026-09-26T09:31:02Z",
  "third_party": null,
  "thumbnail_url": "https://app.videas.com/images/assets/0192a6b2-4f1a-7b90-8e0d-51c3a7f2b046/thumbnail.jpg",
  "excerpt": null,
  "copyright": null,
  "seo_title": null,
  "seo_description": null,
  "tags": [{ "id": "0192a690-2c4d-7e8f-9a0b-1c2d3e4f5a6b", "name": "accueil" }],
  "custom_fields": [
    {
      "field_id": "0192a680-2e3f-7a4b-9c5d-6e7f8a9b0c1d",
      "slug": "format",
      "label": "Format",
      "type": "choice",
      "value": "0192a681-5b6c-7d7e-8f8a-9b0c1d2e3f4a"
    }
  ]
}
Champ
excerpt Un court résumé, qu’une liste affiche sous son titre là où la description ne tient pas, ou null.
copyright La mention qu’un réutilisateur doit reprendre — qui détient ses droits, à quelles conditions —, ou null.
seo_title Le titre que se donne une page web qui le publie, dans l’onglet du navigateur et les résultats d’un moteur de recherche, ou null : la page prend alors son name.
seo_description La description qu’une page qui le publie donne aux moteurs de recherche et aux aperçus de lien, ou null : la page prend alors son excerpt, sinon sa description.
tags Les tags sous lesquels l’organisation le range, par ordre alphabétique ; vide s’il n’en a pas.
custom_fields Ses valeurs des champs personnalisés de l’organisation, dans l’ordre d’un formulaire : field_id, slug, label, type et value, dans la forme que lui donne son type. Un champ dont il n’a pas de valeur n’y figure pas.

Un tag garde son id quand il est renommé ; un tag suggéré par une machine et que personne n’a confirmé n’est pas listé. Un id que la liste ne renverrait pas — un dossier, une collection, un asset masqué, celui d’une autre organisation — vaut un 404, exactement comme un id qui ne désigne rien.

Tous ces champs s’écrivent avec une clé qui porte assets.library.edit : Modifier un asset dit comment.

Les workspaces

GET /v1/workspaces liste les workspaces de l’organisation — ce que désigne le workspace_id d’un asset —, page par page, avec les mêmes limit, after et order, et sans filtre. GET /v1/workspaces/count les compte.

curl https://api.videas.com/v1/workspaces \
  -H "Authorization: Bearer $VIDEAS_API_KEY"
{
  "data": [
    {
      "id": "0192a6b1-7c3e-7d40-9a51-3f0e2b6c8d10",
      "name": "Formations",
      "created_at": "2026-09-01T08:00:00Z",
      "updated_at": "2026-09-01T08:00:00Z"
    }
  ],
  "next": null
}

L’id d’un workspace est aussi l’endroit où arrive un fichier que vous ajoutez.

Rester en phase avec vos données

external_ref est le champ qui relie un asset chez nous à un enregistrement chez vous. Renseignez-le quand vous ajoutez un fichier, et conservez l’id de l’asset à côté de votre enregistrement dès que vous l’avez : l’id ne change jamais. La référence sert à retrouver l’asset quand vous n’avez pas encore son id — après une requête d’upload dont la réponse s’est perdue, par exemple —, avec ?external_ref=. Elle n’est pas unique : une même référence peut désigner plusieurs assets, ou aucun.

Une vidéo hébergée ailleurs se retrouve aussi par son identifiant chez son fournisseur : third_party.video_id, sur chaque ligne de GET /v1/assets, est ce sur quoi rapprocher vos enregistrements quand ils n’ont pas d’external_ref — Ajouter une vidéo hébergée ailleurs montre le parcours.

Pour savoir ce qui a changé depuis votre dernière lecture, updated_at suffit pour les textes et la vignette d’un asset, pas pour ses tags ni ses champs personnalisés, qui ne le font pas bouger : comparez-les.

Pour aller plus loin