Ajouter un fichier depuis un lien

Si le fichier est déjà en ligne — dans un bucket, sur un CDN, sur votre serveur de médias —, inutile de l’envoyer : donnez-nous son lien, nous le téléchargeons en arrière-plan dans votre bibliothèque. C’est la même ressource que pour un fichier que vous envoyez, POST /v1/uploads, avec source_url à la place de size_bytes.

Ouvrir l’upload avec un lien

curl -X POST https://api.videas.com/v1/uploads \
  -H "Authorization: Bearer $VIDEAS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "workspace_id": "0192a6b1-7c3e-7d40-9a51-3f0e2b6c8d10",
    "source_url": "https://medias.example.com/exports/cours-magistral.mp4?X-Amz-Expires=86400&X-Amz-Signature=…",
    "sha256": "5e8f4c0d9b1a…",
    "external_ref": "cours-42/seance-1"
  }'

La clé, le workspace et les champs facultatifs name, description, language et external_ref sont les mêmes que pour un fichier envoyé. Ensuite :

La réponse est un 201 — et il n’y a rien à envoyer : ni adresse, ni jeton.

{
  "id": "0192a6c0-1e2f-7a34-9b56-7c8d9e0f1a2b",
  "asset_id": "0192a6c0-1e2b-7c01-8d23-4e5f6a7b8c9d",
  "workspace_id": "0192a6b1-7c3e-7d40-9a51-3f0e2b6c8d10",
  "source": "link",
  "status": "pending",
  "size_bytes": null,
  "received_bytes": 0,
  "upload_url": null,
  "max_put_bytes": null,
  "expires_at": null,
  "source_url": "https://medias.example.com/exports/cours-magistral.mp4",
  "failure": null,
  "created_at": "2026-09-26T09:20:03Z",
  "updated_at": "2026-09-26T09:20:03Z",
  "finished_at": null,
  "upload_token": null
}

Ce qu’un lien doit être

• http ou https, sur le port de son schéma : 80 pour http, 443 pour https.
• Sans identifiant ni mot de passe — https://utilisateur:secret@… est refusé.
• Sur un serveur public : ni localhost, ni une adresse privée ou réservée.
• Le fichier lui-même, pas une page qui en parle. Une page YouTube, Vimeo ou Dailymotion est refusée d’emblée : c’est un lecteur, pas un fichier, et POST /v1/assets crée l’asset qui la lit. Une page web (text/html) à la place du fichier échoue en not_a_file.
• 10 Gio au plus.

Ce qui se voit dans le lien est refusé d’emblée, par un 400 qui en donne la raison. Le reste, c’est le téléchargement qui le découvre.

Comment nous téléchargeons : des requêtes GET portant User-Agent: Videas-Fetch/… (+https://videas.com/bot; support@videas.com), cinq redirections suivies au plus — jamais de https vers http —, et un téléchargement interrompu repris par une requête Range là où il s’est arrêté. Un serveur qui ignore Range voit le fichier relu depuis le début.

Autoriser nos adresses

Les liens sont téléchargés depuis ces quatre adresses, et depuis aucune autre. Si votre serveur, votre pare-feu ou la politique d’accès de votre bucket ne répond qu’à des adresses connues, autorisez les quatre — l’une ou l’autre famille peut servir :

Attention : autoriser ces adresses ne tient pas lieu d’authentification. Elles téléchargent les liens de tous les clients de Videas : un fichier lisible par ces seules adresses l’est donc par quiconque peut nous en donner l’URL. Gardez le lien signé — une URL présignée — et servez-vous des adresses pour restreindre l’accès, jamais pour l’ouvrir.

Un lien présigné est un secret, et nous le traitons comme tel

• Il est scellé — chiffré — tant que le téléchargement en a besoin, puis effacé à la fin de l’upload.
• Il n’est jamais renvoyé en entier : le source_url de nos réponses est votre lien sans sa query, donc sans sa signature. Nos journaux le citent de la même façon.
• Signez-le pour assez longtemps. Le téléchargement peut attendre son tour et être repris là où il s’est arrêté ; une signature expirée entre-temps fait échouer l’upload en refused. Signez-le pour plus longtemps que le téléchargement ne peut durer, relances comprises.

Vérifier le fichier avec sha256

Donnez l’empreinte SHA-256 du fichier et nous le vérifions une fois téléchargé. Une copie qui ne correspond pas est téléchargée une seconde fois, depuis le début ; si elle ne correspond toujours pas, l’upload échoue en checksum_mismatch. En http simple, c’est la seule preuve que le fichier est bien celui que vous vouliez.

Suivre le téléchargement

Il n’y a pas encore de notification : interrogez GET /v1/uploads/{id} à intervalles réguliers.

failed, cancelled et expired sont définitifs, et l’asset finit alors en error. Un upload échoué dit pourquoi :

{
  "status": "failed",
  "failure": {
    "code": "refused",
    "message": "the link's server refused the request: answered 403 Forbidden"
  }
}

Testez failure.code ; message, en anglais, s’adresse à un humain et peut changer.

Chacun est définitif : une fois la cause corrigée, ouvrez un nouvel upload. Un code que vous ne connaissez pas est un échec que votre code ne traite pas encore — la liste peut s’allonger.

Limites et relances

• 10 Gio au plus par fichier.
• Une organisation ne peut avoir qu’un nombre limité de liens en attente ou en cours de téléchargement. Au-delà, la requête est refusée par un 429 avec Retry-After : attendez ce nombre de secondes, puis renvoyez-la. Un upload terminé, quelle qu’en soit l’issue, libère sa place.
• Relancer après une expiration ou une 5xx se fait comme pour un fichier envoyé : renseignez external_ref et cherchez-le avant de renvoyer. Un lien retrouvé ainsi est déjà en cours de téléchargement — ne le renvoyez pas.
• Pour abandonner, DELETE /v1/uploads/{id} : le téléchargement s’arrête à sa prochaine partie, le lien est oublié, et l’asset finit en error.

Pour aller plus loin

• Ajouter un fichier par l’API — envoyer le fichier vous-même, depuis un serveur ou un navigateur.
• Ajouter une vidéo hébergée ailleurs — quand le lien est celui d’une page YouTube, Vimeo ou Dailymotion.
• Erreurs, limites et versions — chaque refus, et ce qu’il faut relancer.
• La référence de l’API, générée depuis son contrat.