Skip to content
Sign in Waitlist
Docs/API reference/Media/Create media

Create media

POST /v1/media scope write

Starts a media upload (video, cover or image: the photo of an image post, JPEG only). With simple: true and up to 50 MB, send the whole file at once with PUT /v1/media/:id/content; otherwise upload it in parts and finish with POST /v1/media/:id/complete.

HeadersAuthorization: Bearer praeko_… and X-Praeko-Contract: en. Always send both.

Legacy Portuguese alias (still answered, marked as deprecated): /v1/midia.

Parameters

Name In Description
Idempotency-Key header Idempotency key (1 to 255 visible characters, for example a UUID). Repeating the SAME request with the same key within 24 h returns the stored response (with Idempotent-Replayed: true) without running it again; a different request with the same key returns 422 idempotency_key_reuse; a request still in progress returns 409 idempotency_in_progress. 5xx errors are not stored. The key is scoped per workspace and per route. See Retry a request safely.

Request body

JSON. Required fields must be sent; the others can be left out.

Field Type Description
type required string Media type: video, cover or image (the photo of an image post). Values: video, cover, image.
name required string File name (stored with safe characters only). 1 to 200 characters.
mime required string File type. Video: video/mp4 or video/quicktime. Cover: image/png or image/jpeg. Image: image/jpeg only (Studio exports sRGB JPEG; the server does not convert). Values: video/mp4, video/quicktime, image/png, image/jpeg.
size required integer Size in bytes. Video up to 5 GiB; cover and image up to 20 MiB (Instagram takes photos up to 8 MB: that is checked when the post is created). 1 to 5368709120.
simple (optional) boolean true sends the whole file in one PUT /v1/media/:id/content (only up to 50 MB). Without it, the upload is done in parts. Default: false.
sha256 (optional) string SHA-256 hash of the file, if you want it stored.
Body example
{
  "type": "video",
  "name": "day-06-the-failing-test.mp4",
  "mime": "video/mp4",
  "size": 48230114,
  "simple": true
}

Example

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": "day-06-the-failing-test.mp4",
  "mime": "video/mp4",
  "size": 48230114,
  "simple": true
}'

Response

Success status When
200 Success.
Response 200
{
  "id": "01KA3VQ7M2T9XE4HB8N5RZ6C0D",
  "state": "uploading",
  "uploadHint": "PUT /v1/media/01KA3VQ7M2T9XE4HB8N5RZ6C0D/content"
}

With simple: true the response is just id, state and uploadHint. Without it (upload in parts) it also includes minPartSize (5242880), maxPartSize (99614720) and suggestedPartSize (16777216), in bytes, and uploadHint points to PUT /v1/media/:id/parts/<n>.

Errors

Status code When
400 empty_body The request body is empty.
400 invalid_json The request body is not a JSON object.
413 body_too_large The request body is larger than 1 MB.
422 invalid_field Invalid type, mime, name or size.
422 file_too_large simple: true with more than 50 MB.
422 invalid_image An image media item whose file is not a JPEG (checked on upload; for uploads in parts, on complete).
422 idempotency_key_reuse The Idempotency-Key was already used with a different request (different method, path, query or body).
409 idempotency_in_progress A request with the same Idempotency-Key is still in progress (retry in a moment).
409 idempotency_response_too_large The original response was larger than 256 KB and was not stored; fetch the resource with GET instead.

Errors on any route

Status code When
401 unauthorized The Authorization: Bearer … header is missing.
401 invalid_api_key The key does not exist.
401 revoked_api_key The key has been revoked.
401 expired_api_key The key has expired.
403 forbidden The key's scope is not enough for this route (see the scope badge).
429 rate_limited The per-minute request limit was exceeded.

The body of every error is { "error": { "code", "message", "details"? } }. See all error codes.

Try it

Try it

The live test uses your key and your account. It stays off when you are not signed in.

Sign in to try it
Question or mistake on this page? contato@praeko.appView .md

Type to search pages, routes and error codes.