Media processing & limits

Every image, video, GIF, audio file, and document you publish is first uploaded as a media asset — directly from your client to object storage via a presigned URL, so large files never pass through the API. This page covers the asset lifecycle (thestatus an asset moves through from upload to publish-ready) and the per-platform media requirements we validate against before a post is accepted. For the upload/confirm endpoints themselves, see the Media API.

The asset lifecycle

An asset is created in pending_upload when you request an upload URL, and reaches ready once the bytes are in storage and any processing (video cover-frame extraction) has finished. Only a ready asset — or a still-processing one that is otherwise valid — can be attached to a post; videos must be fully ready before they publish.

How an asset reaches ready

After POST /media/upload the asset is pending_upload. You PUT the bytes to the presigned URL, then call POST /media/{id}/confirm. Confirm verifies the object exists, records its size, and re-checks the size cap. From there the path branches by kind:

• Images & GIFs become ready immediately on confirm — an image is its own thumbnail.
• Videos return processing on confirm while a cover frame is extracted asynchronously; poll GET /media/{id} until it flips to ready, at which point thumbnail_url is populated.

A resumable upload (see below) additionally surfaces uploading while chunks stream and uploaded once they all land; you still call confirm to advance it into processing/ready. See Media for the full request/response shapes and thumbnail controls.

Upload size caps

Each media kind has a maximum upload size. The cap is enforced twice: it is bound into the presigned PUT signature (as an x-goog-content-length-range constraint, so storage rejects an over-cap upload with a 400), and re-checked against the stored object’s real size at confirm — so a backend that doesn’t honor the range still can’t let an oversized object through. An over-cap object is rejected at confirm with 413 Payload Too Large (carrying max_bytes and size) and deleted from storage.

Per-platform media requirements

Before a post is accepted, attached media is validated against the target platform’s published constraints. The conservative public limits per platform are below — where a platform tiers limits (e.g. verified vs. standard accounts), PostFuze encodes the standard tier so a passing asset is safe for every account class. Counts are the maximum attachable to one post; aspect bounds are width-to-height ratios.

Images

Video

* YouTube accepts up to 12 h / 128 GB at the API, but unverified accounts are capped at 15 minutes; verify the channel to lift it. Across all platforms, video is accepted with H.264 (and, where supported, HEVC) codecs.

Example: poll a video to ready

async function waitForReady(mediaId: string): Promise<void> {
  for (;;) {
    const res = await fetch(`https://api.postfuze.com/api/v1/media/${mediaId}`, {
      headers: { Authorization: `Bearer ${process.env.POSTFUZE_API_KEY}` },
    });
    const media = (await res.json()) as { status: string };
    if (media.status === 'ready') return;
    if (media.status === 'failed' || media.status === 'deleted') {
      throw new Error(`media ${mediaId} ended in ${media.status}`);
    }
    // pending_upload / uploading / uploaded / processing — keep polling.
    await new Promise((r) => setTimeout(r, 2000));
  }
}