Aller au contenu

Médias et vidéo

Une publication porte ses médias sous forme d’URL. Les routes de cette page déposent un fichier dans la bibliothèque de médias et renvoient l’id et le path à passer dans image[] pour créer une publication.

POST /upload téléversement multipart
POST /upload-from-url le serveur va chercher le fichier

Le path d’un média n’est pas servi indéfiniment. Chaque nuit, une vidéo quitte le stockage 7 jours après la dernière publication qui l’a utilisée, ou 21 jours après son téléversement si elle n’a jamais été publiée. Une vidéo jointe à une publication encore planifiée, à un brouillon, à une publication en erreur ou à une publication récurrente reste tant que cette publication existe. Les images restent. La règle, côté utilisateur, est sur la page Bibliothèque de médias.

Créer une publication avec une vidéo qui a quitté le stockage est refusé par un 400 dont l’erreur commence par MEDIA_EXPIRED : téléversez à nouveau le fichier et utilisez le nouveau path.

POST /upload
Content-Type: multipart/form-data

Un seul champ, file. Le type est lu dans les octets, pas dans le nom : image/jpeg, image/png, image/gif, image/webp, image/avif, image/bmp, image/tiff et video/mp4 sont acceptés.

Fenêtre de terminal
curl -X POST "https://app.usenadia.com/api/public/v1/upload" \
-H "Authorization: your-api-key" \
-F "file=@reel.mp4"

Réponse 201, la ligne de la bibliothèque de médias :

{
"id": "cm4med0001",
"name": "k3J9aQ2xZp.mp4",
"originalName": "reel.mp4",
"path": "https://media.usenadia.com/k3J9aQ2xZp.mp4",
"thumbnail": null,
"alt": null
}
Champ Type Description
id string Ce qu’une publication prend comme image[].id
name string Nom du fichier stocké
originalName string | null Le nom avec lequel le fichier a été envoyé
path string URL publique, ce qu’une publication prend comme image[].path
thumbnail string | null Quand une miniature a été générée
alt string | null Quand un texte alternatif a été défini

400 avec No file provided quand le champ manque, ou quand les octets ne correspondent à aucun type accepté.

POST /upload-from-url
{ "url": "https://example.com/reel.mp4" }

Le serveur télécharge lui-même le fichier et l’enregistre. L’URL doit être une adresse HTTPS publique (pas de réseau privé), et son chemin doit se terminer par .png, .jpg, .jpeg, .gif, .webp ou .mp4, avant toute query string. En pratique : MP4, JPEG, PNG, WebP et GIF. Une URL signée qui expire (R2, S3) convient, tant que le serveur peut la lire sans se connecter.

Réponse 201 : la même ligne de média que ci-dessus. Les erreurs, toutes en 400 :

msg Quand
File must have a valid extension… Le chemin ne se termine pas par une extension acceptée
Failed to fetch URL Erreur réseau, adresse bloquée, ou l’origine a répondu hors 2xx (c’est ce que fait une signature expirée)
Unsupported file type. Les octets ne sont pas d’un type accepté, quoi que dise l’extension

Le fichier peut peser jusqu’à 500 Mo et doit arriver en 10 minutes. Au-delà, et quand le budget de l’espace de travail est épuisé, d’autres statuts :

Statut Quand
413 Le fichier dépasse 500 Mo (refusé sur son Content-Length, ou coupé pendant le transfert)
429 60 imports par heure et par espace de travail, ou 2 déjà en cours en même temps : réessayez plus tard (/upload et /upload-from-url partagent aussi un budget de 300 appels par heure)
507 Le serveur manque d’espace disque : réessayez plus tard

Le sandbox de code d’un assistant IA a en général un fichier sur son disque et aucune URL publique. Pour ce cas, il existe un flux en trois étapes, où les octets partent directement vers UseNadia avec curl, sans jamais passer par un appel d’outil :

  1. createUploadUrl (nom, Content-Type, taille exacte) répond par une URL à usage unique sous https://upload.usenadia.com/api/uploads/…, valable 15 minutes, avec la commande curl exacte à lancer.
  2. Le sandbox lance cette commande : un PUT du fichier, avec le type et la taille déclarés. 201 quand les octets sont arrivés.
  3. confirmUpload vérifie les octets (type détecté, une vidéo doit être lisible et avoir une durée) et enregistre le média ; il répond par la ligne, plus size, duration, width, height et codec, pour que le client compare avec le fichier qu’il comptait envoyer.