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

SDK Python

Installer et utiliser le client Python officiel videas-sdk pour appeler l'API externe Videas depuis votre backend, sans aucune dépendance.

Mis à jour le 28 août 2026sdkpython

videas-sdk est le client Python officiel de l’API externe Videas. Il encapsule chaque endpoint dans un client compact, organisé par ressource : vous n’avez plus à construire les URLs, définir les en-têtes ni analyser les réponses à la main. Il n’utilise que la bibliothèque standard de Python — aucune dépendance tierce — et fonctionne sur Python 3.9+.

Installation

pip install videas-sdk
# ou : uv add videas-sdk

Démarrage rapide

Créez un client avec la clé API de votre organisation, puis appelez n’importe quelle ressource :

from videas_sdk import VideasClient

client = VideasClient(api_key="sk_votre_cle_ici")

# Lister les vidéos « prêtes » de votre organisation
page = client.videos.list(status="ready", limit=50)
print(page["count"], "vidéos")
for video in page["results"]:
    print(video["uid"], video["name"])

Vous créez une clé API depuis Paramètres → Clés API — voir Créer une clé API. La clé identifie à la fois l’organisation concernée par les appels et les portées qu’ils peuvent utiliser.

Authentification

La clé passée à VideasClient est envoyée sous forme de jeton Bearer sur chaque requête. Chaque client est lié à une seule clé : vous pouvez donc créer plusieurs clients avec des clés différentes dans le même processus.

Options du client : délais et réessais

Outre api_key, VideasClient accepte aussi :

  • timeout — délai d’expiration par requête en secondes (None, la valeur par défaut, signifie aucun délai). S’applique à toutes les requêtes, y compris le transfert de l’upload.
  • retries — réessaie les requêtes idempotentes (GET/HEAD) ce nombre de fois supplémentaires sur erreur de connexion ou 429/503, avec un court back-off. Les appels mutants (create/update/delete/upload) ne sont jamais réessayés.
client = VideasClient(
    api_key="sk_votre_cle_ici",
    timeout=10,   # secondes
    retries=2,
)

Manipuler les vidéos

Chaque méthode renvoie le corps JSON analysé (un dict), ou lève une erreur.

# Récupérer une vidéo
video = client.videos.get("vid_123")

# Mettre à jour les champs éditoriaux (partiel — n'envoyez que ce qui change)
client.videos.update("vid_123", name="Onboarding — v2", tags=["onboarding"])

# Supprimer (déplace vers la corbeille)
client.videos.delete("vid_123")

# Métadonnées du player + un jeton de lecture signé
player = client.videos.get_player("vid_123")

videos.list() accepte les mêmes filtres que l’endpoint REST : search, status, tag, created_after, created_before, ordering, ainsi que limit (1 à 100) et offset.

Autres ressources

# Assets — tous les types de médias (vidéo, audio, image, document)
client.assets.list(limit=20)
client.assets.get("ast_123")

# Dossiers dans un espace de travail
client.folders.list("ws_123")
client.folders.create("ws_123", name="Cours")
client.folders.update("ws_123", "fld_1", name="Cours archivés")
client.folders.delete("ws_123", "fld_1")

# Espaces de travail et leurs réglages de domaines d'embed
client.workspaces.list()
client.workspaces.get_embed_settings("ws_123")
client.workspaces.add_embed_domain("ws_123", domain="example.com")

Les champs URL sont absolus. Les champs de réponse comme thumbnail_url sont renvoyés en URLs complètes, résolues contre l’URL de base de l’API Videas — utilisez-les directement, aucun hôte à préfixer.

Résoudre les URLs de lecture

La lecture se fait en deux étapes : obtenir un jeton signé depuis l’endpoint du player, puis l’échanger contre les vraies URLs de flux. Le helper resolve_playback fait les deux en un seul appel :

info = client.videos.resolve_playback("vid_123")
print(info["hls_url"])  # URL HLS signée, à durée limitée

assets.resolve_playback(uid) fait de même pour n’importe quel type d’asset. Préférez ces helpers ; si vous avez besoin du jeton lui-même, enchaînez les deux étapes à la main :

player = client.videos.get_player("vid_123")
info = client.playback.resolve(
    asset_id="vid_123",
    playback_token=player["playback_token"],
)

Envoyer un fichier

upload.upload_file() gère tout le flux résumable (TUS) : il crée la session, transfère les octets, puis renvoie les métadonnées de l’asset créé (dont asset_uid, disponible immédiatement).

with open("intro.mp4", "rb") as fh:
    data = fh.read()

created = client.upload.upload_file(
    workspace_uid="ws_123",
    filename="intro.mp4",
    data=data,
    content_type="video/mp4",
    asset_name="Intro onboarding",       # optionnel
    parent_folder_uid="fld_1",           # optionnel — par défaut la racine du workspace
)
print("Nouvel asset :", created["asset_uid"])

Gros fichiers & progression

Le transfert des octets est découpé en chunks automatiquement — 32 Mio par requête par défaut, sous la limite serveur de 50 Mio par chunk — donc les vidéos de plusieurs gigaoctets s’envoient sans effort. Ajustez la taille de chunk et suivez la progression :

client.upload.upload_file(
    workspace_uid="ws_123",
    filename="cours.mp4",
    data=data,
    chunk_size=16 * 1024 * 1024,  # optionnel — 32 Mio par défaut, doit rester <= 50 Mio
    on_progress=lambda sent, total: print(f"{round(sent / total * 100)} %"),
)

Besoin de piloter le transfert vous-même ? upload.create_session(headers=...) expose l’appel bas niveau de création de session.

Gestion des erreurs

Toute réponse non-2xx lève VideasAPIError, qui porte le status HTTP, le code lisible par machine et le body d’erreur analysé :

from videas_sdk import VideasAPIError

try:
    client.videos.get("nexiste-pas")
except VideasAPIError as err:
    print(err.status)  # 404
    print(err.code)    # "NOT_FOUND"
    print(err)         # message lisible

Consultez le guide de l’API REST pour la liste complète des codes de statut.

Limitations actuelles

  • Pas encore de reprise entre appels. upload.upload_file() envoie par chunks, mais un appel interrompu repart du premier chunk — reprendre une session partiellement envoyée n’est pas encore exposé. Pour une logique de reprise sur mesure, pilotez le transfert avec un client TUS dédié via upload.create_session() — voir Envoyer avec l’API REST.

Étapes suivantes