Media

Media assets — images, videos, GIFs, audio, and documents — are uploaded directly from your client to object storage using a presigned URL, so large files never pass through our API. The flow is three steps: request an upload URL, PUT the bytes to that URL, then confirm the upload. Once a media asset is ready, reference its id from a post container.

Media has a 60-day retention window: each asset is automatically purged 60 days after it was created. Reference it from posts within that window, and re-upload if you need it again later.

The media object

Media status

An asset moves through a fixed set of states from upload to publish-ready. Only a ready asset is safe to attach to a post; videos in particular must be fully ready (their cover frame extracted) before they publish.

How an asset reaches ready: after POST /media/upload (state pending_upload) you PUT the bytes, then call POST /media/{id}/confirm. Confirm verifies the object, records its size, and re-checks the size cap. Images and GIFs become ready immediately; videos return processing while a cover frame is extracted, then flip to ready (poll GET /media/{id}). A resumable upload additionally reports uploading/uploaded while chunks are in flight. For the full lifecycle diagram and the per-platform media-requirements matrix, see Media processing & limits.

Thumbnails & covers

Thumbnails are a media-level derivative, not a per-platform setting. When you confirm a video upload, the asset enters processing while we extract a default cover frame; once done it becomes ready and exposes a thumbnail_url. Images are their own thumbnail and are ready immediately. The active thumbnail is then reused automatically at publish time— as the Instagram Reels cover, YouTube custom thumbnail, Facebook video cover, Pinterest video-pin cover, and TikTok cover frame — so you don’t set a cover per platform.

POST /media/{id}/thumbnail

Set or regenerate a thumbnail. Pass source_media_id (an existing image asset) to use a custom cover, or frame_time_ms to regenerate from a specific video frame (the two are mutually exclusive; an empty body regenerates the default frame). The asset re-enters processing and the new thumbnail becomes primary once the job runs.

# Use an uploaded image as a custom video cover
curl https://api.postfuze.com/api/v1/media/m_video123/thumbnail \
  -H "Authorization: Bearer sk_live_…" \
  -H "Content-Type: application/json" \
  -d '{ "source_media_id": "m_cover456" }'

# Or regenerate from a specific frame (1.5s in)
curl https://api.postfuze.com/api/v1/media/m_video123/thumbnail \
  -H "Authorization: Bearer sk_live_…" \
  -H "Content-Type: application/json" \
  -d '{ "frame_time_ms": 1500 }'

{ "id": "m_video123", "status": "processing" }

Request an upload URL

POST /media/upload

Creates a media record in pending_upload state and returns a presigned URL to PUT the file bytes to. The kind is inferred from the content type or filename when not supplied. The returned method and headers must be used exactly when performing the upload.

curl https://api.postfuze.com/api/v1/media/upload \
  -H "Authorization: Bearer sk_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "filename": "hero.png",
    "content_type": "image/png"
  }'

{
  "id": "m_9f8e7d6c",
  "upload_url": "https://storage.googleapis.com/postfuze-media/org/…/m_9f8e7d6c/hero.png?X-Goog-Signature=…",
  "method": "PUT",
  "headers": { "Content-Type": "image/png" },
  "expires_at": "2026-06-09T12:25:00.000Z"
}

Upload the bytes to the presigned URL using the returned method and headers:

curl -X PUT "https://storage.googleapis.com/postfuze-media/org/…/m_9f8e7d6c/hero.png?X-Goog-Signature=…" \
  -H "Content-Type: image/png" \
  --data-binary @hero.png

Confirm an upload

POST /media/{id}/confirm

Verifies the object exists in storage (via a HEAD request), records its size, and returns the media object with its public url. Images become ready immediately; videos return status: "processing" while a cover frame is extracted (poll GET /media/{id} until ready, then thumbnail_url is populated). Call this after the PUT completes. If the object is not found, the request fails with 400; if the stored object exceeds its kind’s size cap it is deleted and the request fails with 413 Payload Too Large (carrying max_bytes and size).

curl https://api.postfuze.com/api/v1/media/m_9f8e7d6c/confirm \
  -H "Authorization: Bearer sk_live_…" \
  -H "Content-Type: application/json" \
  -d '{}'

{
  "id": "m_9f8e7d6c",
  "kind": "image",
  "filename": "hero.png",
  "content_type": "image/png",
  "size": 184213,
  "status": "ready",
  "width": null,
  "height": null,
  "duration_ms": null,
  "created_at": "2026-06-09T12:24:00.000Z",
  "url": "https://cdn.postfuze.com/org/…/m_9f8e7d6c/hero.png",
  "thumbnail_url": "https://cdn.postfuze.com/org/…/m_9f8e7d6c/hero.png",
  "thumbnail": { "url": "https://cdn.postfuze.com/org/…/m_9f8e7d6c/hero.png", "width": null, "height": null, "frame_time_ms": null, "source": "original" }
}

Retrieve a media asset

GET /media/{id}

Returns a single media asset by id, including its public url. Returns 404 if not found or deleted.

curl https://api.postfuze.com/api/v1/media/m_9f8e7d6c \
  -H "Authorization: Bearer sk_live_…"

{
  "id": "m_9f8e7d6c",
  "kind": "image",
  "filename": "hero.png",
  "content_type": "image/png",
  "size": 184213,
  "status": "ready",
  "width": null,
  "height": null,
  "duration_ms": null,
  "created_at": "2026-06-09T12:24:00.000Z",
  "url": "https://cdn.postfuze.com/org/…/m_9f8e7d6c/hero.png"
}

List media

GET /media

Returns your media assets, newest first. Deleted assets are excluded. This endpoint uses offset pagination — pass limit (default 25, max 100) and offset, and filter by kind or status. The response carries a pagination block with the page parameters and the total matching count. See Pagination & filtering.

curl "https://api.postfuze.com/api/v1/media?kind=image&limit=25&offset=0" \
  -H "Authorization: Bearer sk_live_…"

{
  "data": [
    {
      "id": "m_9f8e7d6c",
      "kind": "image",
      "filename": "hero.png",
      "content_type": "image/png",
      "size": 184213,
      "status": "ready",
      "width": null,
      "height": null,
      "duration_ms": null,
      "created_at": "2026-06-09T12:24:00.000Z"
    }
  ],
  "pagination": { "limit": 25, "offset": 0, "total": 137 }
}

Delete a media asset

DELETE /media/{id}

Soft-deletes the asset and sets its status to deleted. Returns 404 if not found or already deleted.

curl -X DELETE https://api.postfuze.com/api/v1/media/m_9f8e7d6c \
  -H "Authorization: Bearer sk_live_…"

{
  "id": "m_9f8e7d6c",
  "deleted": true
}