Aller au contenu principal
videas.comCréer un ticketOuvrir l'app

Utiliser l'API

URL de base, authentification, portées, endpoints, pagination, limites de débit et facturation de l'API REST Videas.

Mis à jour le 28 août 2026apirestauthentification

L’API REST Videas permet de gérer vos vidéos, vos espaces de travail et vos envois depuis votre propre backend. Ce guide couvre tout ce qu’il faut pour réaliser votre premier appel authentifié.

URL de base

Tous les endpoints se trouvent sous ce préfixe :

https://api.videas.com/api/external/v1/

Les exemples ci-dessous indiquent l’URL complète de chaque appel.

Authentification

Chaque requête doit porter une clé API sous forme de jeton Bearer :

Authorization: Bearer sk_votre_cle_ici

Créez-en une depuis Paramètres → Clés API — voir Créer une clé API. La clé identifie à la fois l’organisation concernée par l’appel et les portées qu’il peut utiliser. Les requêtes sans clé valide renvoient 401 Unauthorized.

Votre première requête

Listez les vidéos de votre organisation :

curl https://api.videas.com/api/external/v1/videos/ \
  -H "Authorization: Bearer sk_votre_cle_ici"

Le même appel en JavaScript :

const res = await fetch('https://api.videas.com/api/external/v1/videos/', {
  headers: { Authorization: 'Bearer sk_votre_cle_ici' },
})
const { items } = await res.json()

…et en Python :

import requests

res = requests.get(
    "https://api.videas.com/api/external/v1/videos/",
    headers={"Authorization": "Bearer sk_votre_cle_ici"},
)
res.raise_for_status()
videos = res.json()["items"]

Portées (scopes)

Une clé ne fonctionne que dans la limite des portées qui lui ont été accordées :

Portée Autorise
Read Assets Lire les vidéos et les espaces (liste, détail, données lecteur)
Write Assets Créer et modifier des vidéos, démarrer des envois
Delete Assets Supprimer des vidéos

Un appel nécessitant une portée absente de la clé renvoie 403 Forbidden.

Principaux endpoints

Les chemins sont relatifs à l’URL de base ci-dessus. La liste complète, avec les paramètres et les schémas de réponse, est dans la référence de l’API.

Méthode Chemin Portée Description
GET /videos/ Read Assets Lister les vidéos (paginé, filtrable)
GET /videos/{uid}/ Read Assets Récupérer une vidéo
PATCH /videos/{uid}/ Write Assets Modifier les champs éditoriaux d’une vidéo
DELETE /videos/{uid}/ Delete Assets Supprimer une vidéo
GET /videos/{uid}/player/ Read Assets Métadonnées du lecteur et jeton de lecture signé
GET /workspaces/ Read Assets Lister les espaces de travail
POST /upload/ Write Assets Démarrer un envoi reprenable (TUS)

Pagination

Les endpoints de liste acceptent limit (1 à 100, 20 par défaut) et offset :

curl "https://api.videas.com/api/external/v1/videos/?limit=50&offset=100" \
  -H "Authorization: Bearer sk_votre_cle_ici"

L’endpoint /videos/ accepte aussi des filtres comme search, status, tag, created_after, created_before et ordering.

Limites de débit

Chaque clé est limitée en débit (par défaut 1000 requêtes par heure). Chaque réponse contient :

  • X-RateLimit-Limit — le plafond pour la fenêtre en cours ;
  • X-RateLimit-Remaining — les appels restants dans la fenêtre ;
  • X-RateLimit-Reset — l’horodatage Unix de réinitialisation de la fenêtre.

En cas de dépassement, vous recevez 429 Too Many Requests avec un en-tête Retry-After (secondes à attendre). Patientez jusque-là avant de réessayer.

Facturation

Les appels à l’API ne sont pas facturés. Il n’y a ni coût par requête, ni tranche à acheter : l’accès à l’API est inclus, et seul le débit est plafonné (voir Limites de débit ci-dessus).

Ce que vos appels déclenchent, en revanche, débite le portefeuille de crédits de votre organisation, aux tarifs publiés sur la page Tarifs — exactement comme si l’action venait de l’application :

  • le stockage des vidéos et fichiers que vous envoyez ;
  • la diffusion auprès de vos spectateurs ;
  • la génération de sous-titres que vous demandez.

Si le solde de crédits de votre organisation est épuisé, un appel qui déclenche une de ces actions peut être refusé avec 402 Payment Required : ajoutez des crédits pour reprendre.

Erreurs

L’API utilise les codes de statut HTTP standards et renvoie un corps JSON contenant un objet error décrivant le problème :

Statut Signification
400 Requête mal formée
401 Clé API absente ou invalide
402 Crédits insuffisants (solde épuisé)
403 La clé n’a pas la portée requise
404 Ressource introuvable
429 Limite de débit dépassée

Envoyer une vidéo (TUS)

Les envois utilisent le protocole reprenable TUS : créez une session d’envoi (POST /upload/, Write Assets), puis transférez le fichier par chunks (≤ 50 Mio chacun) vers l’URL renvoyée dans l’en-tête Location.

Le guide dédié Uploads détaille toute la marche à suivre, y compris la gestion des gros fichiers :

Aller plus loin