- Documentation
- API · Version 1.0
- Médias
Médias
Sur cette page
Une image se dépose dans la bibliothèque d'une marque, puis se joint à une publication par son identifiant med_…. Le dépôt se fait en une seule requête.
POST /media
Périmètre requis : media:create.
En-tête requis : Idempotency-Key.
Type de contenu : multipart/form-data.
| Champ | Type | Requis | Note |
|---|---|---|---|
file |
fichier | oui | JPEG, PNG ou WebP, 8 Mio au plus. Nom en UTF-8, de 255 caractères au plus, sans octet NUL. |
brand_id |
brd_… |
selon | Exigé si le client couvre tout l'espace de travail. |
curl -X POST https://quietsocial.dev/api/v1/media \
-u "$QUIET_CLIENT_ID:$QUIET_CLIENT_SECRET" \
-H 'Idempotency-Key: article-42-couverture-v1' \
-F 'file=@couverture.png'
201 Created :
{
"data": {
"id": "med_01k4b8z6u3w0j7q9x1z3a5c7e9",
"kind": "image",
"filename": "couverture.png",
"mime_type": "image/jpeg",
"size": 184320,
"width": 1200,
"height": 630,
"duration_ms": null,
"has_poster": null,
"status": "ready",
"usable": true,
"failure": null,
"checksum": "9f2c1e7a4b8d3f60a1c5e29b7d40f83615ac9e2b74d0916f3a8c5b2e7d419c06",
"created_at": "2026-10-01T09:12:44+00:00"
}
}
Ce que devient le fichier
L'image n'est pas stockée telle quelle. Avant toute écriture :
- Son type est reconnu à sa signature binaire, pas à son extension ni au type annoncé. Un fichier renommé en
.jpgqui n'est pas une image est refusé, et aucun octet n'atteint le disque. - Elle est convertie en JPEG, ramenée à 1 440 pixels de large au plus et à 4 Mo au plus. C'est le format que les cinq réseaux acceptent : Instagram ne prend que le JPEG, Facebook plafonne le poids à 4 Mo, Instagram et Threads la largeur à 1 440 pixels. Un JPEG déjà léger et déjà conforme n'est pas réencodé.
- Ses métadonnées sont retirées, position GPS comprise.
L'original n'est pas conservé. mime_type, size, width, height et checksum décrivent le fichier réellement stocké ; filename garde le nom d'origine.
Vidéo
Une vidéo MP4 ou MOV de 250 Mio au plus, de 3 secondes à 5 minutes, passe par la même requête. Elle n'est pas prête à la réponse : elle est préparée en file d'attente (MP4 H.264 et AAC, redressée, 1 920 pixels au plus sur le grand côté, sans métadonnées, avec une couverture). La réponse est alors 202 Accepted, avec kind: "video", status: "processing" et un en-tête Location vers le média ; relisez GET /media/{id} jusqu'à ready, ou failed avec la raison dans failure. Un rejeu de la même Idempotency-Key rend le 202 du premier envoi, périmé : suivez son Location plutôt que son corps. HEIC et AVIF sont refusés (422 media_not_acceptable).
Une vidéo prête porte duration_ms (sa durée en millisecondes) et has_poster. Elle se joint seule à une publication, et seulement aux destinations dont les capabilities déclarent video ou reel : Facebook (vidéo de Page), Instagram (Reel), Threads, LinkedIn et Pinterest (Pin vidéo, avec la couverture). Trente jours après sa dernière publication, son fichier est effacé et elle passe expired.
Déduplication
Si la marque possède déjà une image identique au fichier stocké, l'API rend le média existant avec le statut 200 au lieu de 201. Le corps est le même : c'est le code qui dit que rien n'a été créé. checksum permet de reconnaître un fichier déjà envoyé.
Refus
Un fichier qui ne peut pas devenir un média répond 422 media_not_acceptable :
{
"error": {
"code": "media_not_acceptable",
"message": "This file is not a JPEG, PNG or WebP image.",
"errors": ["This file is not a JPEG, PNG or WebP image."]
}
}
| Message | Cause |
|---|---|
| « This file is empty. » | Zéro octet. |
| « This file weighs X MB; the limit is 8.0 MB. » | Plus de 8 Mio. |
| « This file is not a JPEG, PNG or WebP image. » | Signature non reconnue. |
| « This image is unreadable or incomplete. » | Signature reconnue, en-tête illisible : fichier tronqué ou fabriqué. |
| « This image has X million pixels; the limit is 50 million. » | Plus de 50 millions de pixels. |
En pratique, un fichier de plus de 8 Mio est arrêté plus tôt, par la validation de la requête : la réponse est alors un 422 sur le champ file, avec l'enveloppe de validation (voir Erreurs).
Le nom du fichier est vérifié au même endroit, avant toute inspection : un nom qui n'est pas de l'UTF-8 valide, qui dépasse 255 caractères ou qui contient un octet NUL répond 422 sur le champ file, et rien n'est stocké. Renommez le fichier et renvoyez-le ; le message suit la langue de l'API.
Codes : 200, 201, 202, 400, 401, 403, 409, 422, 429.
GET /media
La bibliothèque des marques visibles par le client, les plus récents d'abord.
Périmètre requis : media:read.
| Paramètre | Type | Note |
|---|---|---|
brand_id |
brd_… |
Ne rend que les médias de cette marque. Une marque hors de portée rend une liste vide. |
per_page |
entier | Entre 1 et 100, 25 par défaut. |
page |
entier |
Codes : 200, 401, 403, 429.
GET /media/{id}
Périmètre requis : media:read.
La même ressource que la création. L'API ne rend pas d'adresse de téléchargement du fichier.
Codes : 200, 401, 403, 404, 429.
DELETE /media/{id}
Périmètre requis : media:create.
curl -X DELETE https://quietsocial.dev/api/v1/media/med_01k4b8z6u3w0j7q9x1z3a5c7e9 \
-u "$QUIET_CLIENT_ID:$QUIET_CLIENT_SECRET"
204 No Content, sans corps.
La suppression retire le média de la bibliothèque. Le fichier reste trente jours sur le disque, pour ne pas casser l'affichage des publications déjà parties qui l'utilisent, puis il est effacé. Un second appel sur le même identifiant répond 404.
Un média supprimé n'est plus utilisable : une nouvelle publication qui le nomme est refusée, et une publication déjà programmée qui le joint échoue au départ sur ses destinations, avec un message qui nomme l'image.
Codes : 204, 401, 403, 404, 429.
Statuts d'un média
| Valeur | Utilisable dans une publication |
|---|---|
ready |
oui |
published |
oui |
uploaded, validating, processing, failed, expired, deleted |
non |
usable rend directement ce prédicat. Une image déposée par l'API sort en ready ; une vidéo, en processing, puis ready ou failed. Une vidéo passe expired trente jours après sa dernière publication.