Skip to content
Quiet Social

Media

This documentation is translated from French. Should the two versions differ, the French version prevails.

An image is uploaded to a brand's library, then attached to a publication by its med_… identifier. The upload takes a single request.

POST /media

Required scope: media:create. Required header: Idempotency-Key. Content type: multipart/form-data.

Field Type Required Note
file file yes JPEG, PNG or WebP, 8 MiB at most. Name in UTF-8, 255 characters at most, without a null byte.
brand_id brd_… depends Required if the client covers the whole workspace.
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"
  }
}

What happens to the file

The image is not stored as is. Before anything is written:

  1. Its type is recognized from its binary signature, not from its extension or the declared type. A file renamed to .jpg that is not an image is refused, and not a single byte reaches the disk.
  2. It is converted to JPEG, reduced to 1,440 pixels wide at most and 4 MB at most. This is the format all five networks accept: Instagram only takes JPEG, Facebook caps the weight at 4 MB, Instagram and Threads cap the width at 1,440 pixels. A JPEG that is already light and already compliant is not re-encoded.
  3. Its metadata is removed, GPS location included.

The original is not kept. mime_type, size, width, height and checksum describe the file actually stored; filename keeps the original name.

Video

An MP4 or MOV video of 250 MiB at most, lasting 3 seconds to 5 minutes, goes through the same request. It is not ready in the response: it is prepared in a queue (MP4 H.264 and AAC, turned upright, 1,920 pixels at most on the longest side, without metadata, with a cover). The response is then 202 Accepted, with kind: "video", status: "processing" and a Location header pointing to the media; read GET /media/{id} again until ready, or failed with the reason in failure. A replay of the same Idempotency-Key returns the first upload's 202, which is stale: follow its Location rather than its body. HEIC and AVIF are refused (422 media_not_acceptable).

A ready video carries duration_ms (its length in milliseconds) and has_poster. It is attached to a publication on its own, and only to destinations whose capabilities declare video or reel: Facebook (Page video), Instagram (Reel), Threads, LinkedIn and Pinterest (video Pin, with the cover). Thirty days after its last publication, its file is erased and it becomes expired.

Deduplication

If the brand already has an image identical to the stored file, the API returns the existing media with status 200 instead of 201. The body is the same: it is the code that tells you nothing was created. checksum lets you recognize a file that was already uploaded.

Rejections

A file that cannot become a media item responds 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. » Zero bytes.
« This file weighs X MB; the limit is 8.0 MB. » More than 8 MiB.
« This file is not a JPEG, PNG or WebP image. » Signature not recognized.
« This image is unreadable or incomplete. » Signature recognized, header unreadable: truncated or forged file.
« This image has X million pixels; the limit is 50 million. » More than 50 million pixels.

In practice, a file larger than 8 MiB is stopped earlier, by request validation: the response is then a 422 on the file field, with the validation envelope (see Errors).

The file name is checked at the same point, before any inspection: a name that is not valid UTF-8, exceeds 255 characters or contains a null byte answers 422 on the file field, and nothing is stored. Rename the file and send it again; the message follows the language of the API.

Codes: 200, 201, 202, 400, 401, 403, 409, 422, 429.

GET /media

The library of the brands visible to the client, most recent first.

Required scope: media:read.

Parameter Type Note
brand_id brd_… Returns only the media of this brand. A brand out of scope returns an empty list.
per_page integer Between 1 and 100, 25 by default.
page integer

Codes: 200, 401, 403, 429.

GET /media/{id}

Required scope: media:read.

The same resource as on creation. The API does not return a download URL for the file.

Codes: 200, 401, 403, 404, 429.

DELETE /media/{id}

Required scope: media:create.

curl -X DELETE https://quietsocial.dev/api/v1/media/med_01k4b8z6u3w0j7q9x1z3a5c7e9 \
  -u "$QUIET_CLIENT_ID:$QUIET_CLIENT_SECRET"

204 No Content, with no body.

Deletion removes the media from the library. The file stays on disk for thirty days, so as not to break the display of already-sent publications that use it, then it is erased. A second call on the same identifier responds 404.

A deleted media item can no longer be used: a new publication that names it is refused, and an already scheduled publication that attaches it fails at departure on its destinations, with a message that names the image.

Codes: 204, 401, 403, 404, 429.

Media statuses

Value Usable in a publication
ready yes
published yes
uploaded, validating, processing, failed, expired, deleted no

usable returns this predicate directly. An image uploaded through the API comes out as ready; a video as processing, then ready or failed. A video becomes expired thirty days after its last publication.