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 multipartPOST /upload-from-url le serveur va chercher le fichierCombien de temps un fichier est conservé
Section intitulée « Combien de temps un fichier est conservé »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.
Téléverser un fichier
Section intitulée « Téléverser un fichier »POST /uploadContent-Type: multipart/form-dataUn 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.
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é.
Importer depuis une URL
Section intitulée « Importer depuis une URL »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 |
Téléversement direct depuis un sandbox
Section intitulée « Téléversement direct depuis un sandbox »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 :
createUploadUrl(nom,Content-Type, taille exacte) répond par une URL à usage unique soushttps://upload.usenadia.com/api/uploads/…, valable 15 minutes, avec la commandecurlexacte à lancer.- Le sandbox lance cette commande : un
PUTdu fichier, avec le type et la taille déclarés.201quand les octets sont arrivés. confirmUploadvé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, plussize,duration,width,heightetcodec, pour que le client compare avec le fichier qu’il comptait envoyer.