- Documentación
- API · Versión 1.0
- Medios
Medios
En esta página
Una imagen se deposita en la biblioteca de una marca y luego se adjunta a una publicación mediante su identificador med_…. El depósito se hace en una sola petición.
POST /media
Permiso requerido: media:create.
Cabecera requerida: Idempotency-Key.
Tipo de contenido: multipart/form-data.
| Campo | Tipo | Requerido | Nota |
|---|---|---|---|
file |
archivo | sí | JPEG, PNG o WebP, 8 MiB como máximo. Nombre en UTF-8, de 255 caracteres como máximo, sin byte nulo. |
brand_id |
brd_… |
según el caso | Obligatorio si el cliente cubre todo el espacio de trabajo. |
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"
}
}
Qué ocurre con el archivo
La imagen no se almacena tal cual. Antes de cualquier escritura:
- Su tipo se reconoce por su firma binaria, no por su extensión ni por el tipo declarado. Un archivo renombrado a
.jpgque no es una imagen se rechaza, y ningún byte llega al disco. - Se convierte a JPEG, reducida a 1 440 píxeles de ancho como máximo y a 4 MB como máximo. Es el formato que aceptan las cinco redes: Instagram solo admite JPEG, Facebook limita el peso a 4 MB, Instagram y Threads la anchura a 1 440 píxeles. Un JPEG ya ligero y ya conforme no se vuelve a codificar.
- Se eliminan sus metadatos, posición GPS incluida.
El original no se conserva. mime_type, size, width, height y checksum describen el archivo realmente almacenado; filename conserva el nombre original.
Vídeo
Un vídeo MP4 o MOV de 250 MiB como máximo, de 3 segundos a 5 minutos, pasa por la misma petición. No está listo en la respuesta: se prepara en una cola (MP4 H.264 y AAC, enderezado, 1920 píxeles como máximo en el lado mayor, sin metadatos, con una portada). La respuesta es entonces 202 Accepted, con kind: "video", status: "processing" y una cabecera Location hacia el medio; vuelva a leer GET /media/{id} hasta ready, o failed con el motivo en failure. Una repetición de la misma Idempotency-Key devuelve el 202 del primer envío, ya caducado: siga su Location en lugar de su cuerpo. HEIC y AVIF se rechazan (422 media_not_acceptable).
Un vídeo listo lleva duration_ms (su duración en milisegundos) y has_poster. Se adjunta solo a una publicación, y únicamente a los destinos cuyas capabilities declaran video o reel: Facebook (vídeo de página), Instagram (Reel), Threads, LinkedIn y Pinterest (Pin de vídeo, con la portada). Treinta días después de su última publicación, su archivo se borra y pasa a expired.
Deduplicación
Si la marca ya tiene una imagen idéntica al archivo almacenado, la API devuelve el medio existente con el estado 200 en lugar de 201. El cuerpo es el mismo: es el código el que indica que no se ha creado nada. checksum permite reconocer un archivo ya enviado.
Rechazos
Un archivo que no puede convertirse en un medio responde 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."]
}
}
| Mensaje | Causa |
|---|---|
| « This file is empty. » (Este archivo está vacío.) | Cero bytes. |
| « This file weighs X MB; the limit is 8.0 MB. » (Este archivo pesa X MB; el límite es de 8,0 MB.) | Más de 8 MiB. |
| « This file is not a JPEG, PNG or WebP image. » (Este archivo no es una imagen JPEG, PNG o WebP.) | Firma no reconocida. |
| « This image is unreadable or incomplete. » (Esta imagen es ilegible o está incompleta.) | Firma reconocida, cabecera ilegible: archivo truncado o fabricado. |
| « This image has X million pixels; the limit is 50 million. » (Esta imagen tiene X millones de píxeles; el límite es de 50 millones.) | Más de 50 millones de píxeles. |
En la práctica, un archivo de más de 8 MiB se detiene antes, en la validación de la petición: la respuesta es entonces un 422 sobre el campo file, con el sobre de validación (consulta Errores).
El nombre del archivo se comprueba en el mismo punto, antes de cualquier inspección: un nombre que no es UTF-8 válido, que supera los 255 caracteres o que contiene un byte nulo responde 422 sobre el campo file, y no se almacena nada. Cambia el nombre del archivo y vuelve a enviarlo; el mensaje sigue el idioma de la API.
Códigos: 200, 201, 202, 400, 401, 403, 409, 422, 429.
GET /media
La biblioteca de las marcas visibles para el cliente, los más recientes primero.
Permiso requerido: media:read.
| Parámetro | Tipo | Nota |
|---|---|---|
brand_id |
brd_… |
Solo devuelve los medios de esta marca. Una marca fuera de alcance devuelve una lista vacía. |
per_page |
entero | Entre 1 y 100, 25 por defecto. |
page |
entero |
Códigos: 200, 401, 403, 429.
GET /media/{id}
Permiso requerido: media:read.
El mismo recurso que en la creación. La API no devuelve ninguna dirección de descarga del archivo.
Códigos: 200, 401, 403, 404, 429.
DELETE /media/{id}
Permiso requerido: media:create.
curl -X DELETE https://quietsocial.dev/api/v1/media/med_01k4b8z6u3w0j7q9x1z3a5c7e9 \
-u "$QUIET_CLIENT_ID:$QUIET_CLIENT_SECRET"
204 No Content, sin cuerpo.
La eliminación retira el medio de la biblioteca. El archivo permanece treinta días en el disco, para no romper la visualización de las publicaciones ya enviadas que lo utilizan, y después se borra. Una segunda llamada sobre el mismo identificador responde 404.
Un medio eliminado ya no se puede utilizar: una nueva publicación que lo nombra se rechaza, y una publicación ya programada que lo adjunta falla al salir en sus destinos, con un mensaje que nombra la imagen.
Códigos: 204, 401, 403, 404, 429.
Estados de un medio
| Valor | Utilizable en una publicación |
|---|---|
ready |
sí |
published |
sí |
uploaded, validating, processing, failed, expired, deleted |
no |
usable devuelve directamente este predicado. Una imagen depositada por la API sale en ready; un vídeo, en processing, y después ready o failed. Un vídeo pasa a expired treinta días después de su última publicación.