Ajouter une vidéo hébergée ailleurs

Une vidéo déjà publiée sur YouTube, Vimeo ou Dailymotion n’a pas besoin d’être téléchargée pour entrer dans votre bibliothèque : POST /v1/assets crée un asset qui la lit depuis le site de son fournisseur. Il suffit de l’adresse de sa page. L’asset est prêt aussitôt — il n’y a aucun fichier à recevoir ni à traiter —, et vous pouvez ensuite le modifier et le publier sur une chaîne comme n’importe quel autre.

Un fichier, lui, s’ajoute avec POST /v1/uploads : envoyé par vous ou récupéré depuis un lien.

Avant de commencer

• Une clé qui porte deux permissions : Ajouter des fichiers à la bibliothèque par l’API (assets.library.upload) et Importer des vidéos d’autres plateformes (assets.third_party_video.import). L’une sans l’autre vaut un 403. Cochez aussi Lire la bibliothèque par l’API pour relancer sans risque.
• L’import de vidéos hébergées ailleurs activé pour votre organisation. Il s’active organisation par organisation, sur demande à Videas : tant qu’il ne l’est pas, POST /v1/assets répond 404. Une clé créée avant fonctionne sans rien changer dès qu’il l’est.
• Un workspace : l’id de l’un de ceux que renvoie GET /v1/workspaces, privés compris. L’asset arrive à sa racine.

Créer l’asset

curl -X POST https://api.videas.com/v1/assets \
  -H "Authorization: Bearer $VIDEAS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "workspace_id": "0192a6b1-7c3e-7d40-9a51-3f0e2b6c8d10",
    "third_party_url": "https://www.youtube.com/watch?v=Xk3Ua9yQe7M",
    "language": "fr",
    "external_ref": "webtv/2026/recyclage-fibre-carbone"
  }'

POST /v1/assets ne prend aucun paramètre de requête, et son corps aucun autre champ.

La réponse est un 201, avec Location: /v1/assets/{asset_id} et l’asset tel que le lit GET /v1/assets/{asset_id} :

{
  "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:12Z",
  "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": null,
  "copyright": null,
  "seo_title": null,
  "seo_description": null,
  "tags": [],
  "custom_fields": []
}

• type vaut third_party, et status est ready dès la création.
• third_party dit quelle vidéo l’asset lit : provider (youtube, vimeo ou dailymotion), video_id, l’identifiant de la vidéo chez son fournisseur — le v d’une adresse YouTube —, et player_url, l’adresse de son lecteur, à mettre dans un <iframe>.
• thumbnail_url est l’affiche que le fournisseur a donnée, si elle est arrivée à temps (voir plus bas).

Les adresses acceptées

third_party_url est l’adresse d’une vidéo sur l’un des trois sites, sous la forme que donne sa page ou son bouton de partage :

Rien d’autre n’est pris, et tout le reste répond un 400 qui en donne la raison : un code d’intégration (<iframe …>), une adresse sur un autre site, ou le lien d’un fichier — qui s’ajoute avec POST /v1/uploads.

Le fournisseur est interrogé pendant votre requête

Avant de créer quoi que ce soit, Videas demande au fournisseur ce qu’est la vidéo, et votre requête attend sa réponse. Elle sert à trois choses :

• nommer et décrire l’asset — son titre devient le name de l’asset si vous n’en envoyez pas, sa description la description si vous n’en envoyez pas ;
• vérifier que la vidéo peut être lue hors de son site : une vidéo privée, supprimée ou dont l’intégration est interdite est refusée par un 400, et rien n’est créé ;
• donner son affiche à l’asset : elle devient sa vignette si elle arrive à temps. Sinon l’asset est créé sans vignette, et PUT /v1/assets/{asset_id}/thumbnail lui en donne une.

Un fournisseur qui ne répond pas à temps, ou qui répond par un échec de son côté, vaut un 502 de code upstream_error : rien n’est créé, renvoyez la requête un peu plus tard.

{
  "code": "upstream_error",
  "message": "YouTube could not be asked about this video; try again in a moment",
  "request_id": "0192a6e4-1f2a-7b3c-8d4e-5f6a7b8c9d0e"
}

Retrouver vos vidéos

third_party figure sur chaque ligne de GET /v1/assets, pas seulement sur la lecture d’un asset. Pour relier les vidéos d’une bibliothèque à vos propres enregistrements — y compris celles ajoutées avant que vous ne posiez des external_ref —, parcourez les assets de type third_party et comparez third_party.video_id à l’identifiant de la vidéo chez vous :

import os

import requests

API = "https://api.videas.com/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['VIDEAS_API_KEY']}"}

def videos_by_provider_id():
    """{(provider, video_id): asset} pour chaque vidéo hébergée ailleurs."""
    found, params = {}, {"type": "third_party"}
    while True:
        page = requests.get(f"{API}/assets", headers=HEADERS, params=params)
        page.raise_for_status()
        body = page.json()
        for asset in body["data"]:
            video = asset["third_party"]
            if video and video["video_id"]:
                found[(video["provider"], video["video_id"])] = asset
        if body["next"] is None:
            return found
        params["after"] = body["next"]

provider peut aussi valoir other — un lecteur d’un autre site, ajouté depuis l’application Videas — et n’a alors pas de video_id. La liste des fournisseurs peut s’allonger : lisez une valeur inconnue comme other.

Relancer sans risque

POST /v1/assets n’est pas idempotent : envoyé deux fois, il crée deux assets. Une requête qui a expiré ou répondu une 5xx peut en avoir créé un. Donc :

1. renseignez external_ref à chaque requête ;

2. après une expiration ou une 5xx, cherchez-le avant de renvoyer la requête — avec une clé qui lit la bibliothèque :

   curl "https://api.videas.com/v1/assets?external_ref=webtv%2F2026%2Frecyclage-fibre-carbone" \
     -H "Authorization: Bearer $VIDEAS_API_KEY"

3. rien trouvé : renvoyez-la. Trouvé : c’est l’asset que la première requête a créé, et il est complet — prêt dès qu’il existe. Il n’y a rien à reprendre.

Un 502 n’a rien créé : il se renvoie tel quel.

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

• Modifier un asset — ses textes et ses tags, une fois créé.
• La vignette d’un asset — quand l’affiche du fournisseur n’est pas arrivée, ou ne convient pas.
• Publier sur une chaîne — dont un exemple de bout en bout qui part d’une vidéo YouTube.
• La référence de l’API, générée depuis son contrat.