Upload media: single file and parts

Every video, cover and photo goes through /v1/media before it can be used in a post. There are two paths, depending on size.

Accepted types and sizes

image is the photo of an image post. The server checks that the file really is a JPEG (422 invalid_image if not: on a single upload, before storing; on a multipart upload, on complete) and reads the width and height from the header (width and height on the media item). It does not convert: export the photo as sRGB JPEG (Praeko Studio does that).

A single photo on Instagram

Upload the photo with type: image and create the post with kind: image and one image in media.images (several would be a carousel, which does not exist yet: 422 carousel_not_supported). Only Instagram takes a photo for now, through Buffer or directly through Meta; YouTube and TikTok answer 422 kind_not_supported_by_network.

{
  "kind": "image",
  "title": "Tip: small PRs",
  "media": {
    "images": [
      {
        "media": "01KA3V9...",
        "alt": "Slide with the title of the tip"
      }
    ]
  },
  "texts": {
    "instagram": {
      "text": "One PR, one idea. #devbrasil"
    }
  },
  "items": [
    {
      "network": "instagram",
      "via": "meta",
      "queue": true
    }
  ]
}

Warnings come back in items[].warnings (each with a stable code and message) and do not stop the creation. Through Meta the alt goes in the photo container; through Buffer, which has no documented alt text, it is ignored and the item warns. The post comes back with kind and media.images; the image of an image post cannot be replaced by PATCH (cancel and create again).

Single file

curl -X POST https://praeko.app/v1/media \
  -H "Authorization: Bearer $PRAEKO_KEY" -H "X-Praeko-Contract: en" \
  -H "Content-Type: application/json" \
  -d '{ "type": "video", "name": "v.mp4", "mime": "video/mp4", "size": 8123456, "simple": true }'
curl -X PUT https://praeko.app/v1/media/$MEDIA_ID/content \
  -H "Authorization: Bearer $PRAEKO_KEY" -H "Content-Type: video/mp4" \
  --data-binary @v.mp4

With simple: true and a size above 50 MiB, creation is rejected (422 file_too_large): use parts. The PUT body must be exactly the agreed size (422 size_mismatch).

Multipart upload

The POST /v1/media response (without simple) has minPartSize (5 MiB), maxPartSize (95 MiB) and suggestedPartSize (16 MiB). Number the parts from 1 to 10000, send each one with PUT /v1/media/:id/parts/:part as raw bytes, and finish with POST /v1/media/:id/complete.

• All parts have the same size; only the last one can be smaller (422 parts_unequal). Every part except the last must be at least 5 MiB (422 part_too_small); none can exceed 95 MiB (413 part_too_large).
• Sending the same part again is safe: it is overwritten.
• If a part is missing from the sequence, complete returns 422 parts_missing; if the total does not match the agreed size, 422 size_mismatch.
• An upload that is not finished within 24 hours is discarded (the media leaves the library).

# 16 MiB per part; the last one takes the rest
split -b 16m v.mp4 part_
n=1; for f in part_*; do
  curl -X PUT "https://praeko.app/v1/media/$MEDIA_ID/parts/$n" \
    -H "Authorization: Bearer $PRAEKO_KEY" -H "Content-Type: video/mp4" \
    --data-binary @"$f"
  n=$((n+1))
done
curl -X POST https://praeko.app/v1/media/$MEDIA_ID/complete \
  -H "Authorization: Bearer $PRAEKO_KEY" -H "X-Praeko-Contract: en"

State and use

Media starts as uploading and becomes ready when the upload finishes. ready videos carry durationMs, width and height when the file header provides them (older videos get them on first read), and GET /v1/media/:id also returns publicUrl. Only use ready media in a post (otherwise 409 media_not_ready). DELETE /v1/media/:id refuses media used by a pending post (409 media_in_use).

durationMs is the duration in milliseconds read from the file. Do not confuse it with duration in GET /v1/youtube/videos, which is the duration YouTube reports, in ISO 8601 (for example, PT58S).