Nouveau sur Videas ? Cette page explique, de zéro, comment faire entrer un fichier (souvent une vidéo) dans la plateforme — et comment le faire de façon fiable, même pour de gros fichiers. Une fois le modèle compris, choisissez votre voie : le SDK (recommandé) ou l’API REST.
Ce que veut dire « envoyer »
Vous envoyez un fichier dans un espace de travail (workspace). Videas le stocke et crée un asset (vidéo, audio, image ou document) que vous pourrez ensuite lire, intégrer et gérer via l’API. Chaque envoi est rattaché à votre organisation via votre clé API.
Le même asset apparaît dans la médiathèque Mediasbox, rangé dans le dossier que vous avez indiqué : ce que votre intégration dépose, votre client le retrouve et le classe sans écrire une ligne de code.
Les envois sont reprenables et découpés en chunks
Les vidéos sont volumineuses et les réseaux peu fiables — Videas ne prend donc pas le fichier entier d’un coup. Il utilise le protocole reprenable TUS, qui fonctionne en deux temps :
- Créer une session d’envoi — vous annoncez le fichier (nom + taille totale). Videas répond avec une URL vers laquelle envoyer les octets.
- Envoyer les octets par morceaux (chunks) — vous transférez le fichier en plusieurs parties, l’une après l’autre. Si un morceau échoue, vous ne réessayez que celui-là, pas tout le fichier.
Vous n’envoyez pas le fichier entier en une seule requête : chaque morceau doit rester sous la limite par chunk (voir plus bas). Découper un gros fichier en morceaux est l’idée centrale qui rend les gros envois possibles.
Bonne nouvelle : les SDK officiels font tout cela pour vous — création de session, découpage, offsets, réessais. Vous appelez une seule fonction. Ne passez au protocole brut que si vous ne pouvez pas utiliser de SDK.
Les limites à connaître
| Limite | Valeur | Signification |
|---|---|---|
| Taille par chunk | 50 Mio | Taille maximale d’une requête de transfert. Un fichier plus gros doit être découpé en plusieurs chunks (le SDK utilise 32 Mio par défaut). |
| Taille totale du fichier | 10 Gio | Taille maximale d’un fichier envoyé. |
| Durée de vie de la session | 24 heures | Une session d’envoi expire si elle n’est pas terminée à temps ; recommencez avec une nouvelle session après. |
Dépasser la limite par chunk renvoie une erreur du type
Chunk too large: … exceeds maximum 52428800 bytes — c’est le signe qu’il faut
envoyer des chunks plus petits (le SDK n’atteint jamais cette limite).
Après l’envoi : le traitement
Dès la création de la session, vous obtenez un asset_uid — l’identifiant
de l’asset en cours de création — avant même la fin du transfert des octets. Les
vidéos sont ensuite traitées de façon asynchrone (transcodage, vignettes…),
donc l’asset n’est pas immédiatement lisible. Le transcodage produit un flux HLS
à débit adaptatif distribué par CDN — c’est ce que décrit
Hébergement vidéo, et c’est ce que vous
récupérerez à l’étape de lecture.
Interrogez l’asset jusqu’à ce qu’il soit prêt :
GET /api/external/v1/assets/{asset_uid}/ → { "status": "ready", … }Le statut passe du traitement à ready (ou error). N’essayez pas de lire ou
d’intégrer un asset tant qu’il n’est pas ready.
Bien gérer les gros fichiers
- Préférez le SDK. Il transfère le fichier par chunks (vous ne gardez jamais tout en mémoire), suit la progression et remonte des erreurs claires.
- Affichez la progression. Pour des fichiers de plusieurs centaines de Mo ou plusieurs Go, donnez une barre de progression (les SDK exposent un callback).
- Évitez de charger un énorme fichier en mémoire si possible — lisez/streamez depuis le disque. (L’API brute vous laisse envoyer n’importe quelle tranche ; le SDK s’en charge.)
- Comptez sur la reprise, pas le redémarrage. Avec les chunks, une coupure ne coûte que le chunk en cours, pas tout le fichier.
Choisir votre voie
- Envoyer avec le SDK — un seul appel de fonction, découpage et progression intégrés. Commencez ici.
- Envoyer avec l’API REST — pilotez le protocole TUS vous-même en HTTP simple, dans n’importe quel langage.