Ir al contenido
Quiet Social

Medios

Esta documentación está traducida del francés. Si ambas versiones difieren, prevalece la versión francesa.

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:

  1. Su tipo se reconoce por su firma binaria, no por su extensión ni por el tipo declarado. Un archivo renombrado a .jpg que no es una imagen se rechaza, y ningún byte llega al disco.
  2. 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.
  3. 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.