Media

Start an upload

Reserves a file and says how to send it: one PUT to uploadUrl up to 100 MB, or multipart parts for a larger video (give bytes).

POST/v1/media

TL;DR

Question	Answer
What does it do?	Start an upload.
What does it need?	An API key or an OAuth access token.
What does it take?	A JSON body with the fields below.
What does it return?	Status 201 with a body of type `MediaUpload`.
In the SDK?	`flung.media.create()`
What can go wrong?	`401` Missing, unknown, revoked or expired API key; `422` The request failed validation; `429` Too many requests for this credential; wait for `retry-after` seconds. Every failure has the same error shape.

What it does

Reserves a file and says how to send it: one PUT to uploadUrl up to 100 MB, or multipart parts for a larger video (give bytes). Use the id in mediaIds once the file is ready.

Example

1curl -X POST 'https://api.flung.dev/v1/media' \2  --header "Authorization: Bearer $FLUNG_API_KEY" \3  --header 'Content-Type: application/json' \4  --header "Idempotency-Key: $(uuidgen)" \5  --data '{6  "contentType": "image/jpeg"7}'

1import { Flung } from '@flung.dev/sdk'2
3const flung = new Flung({ apiKey: process.env.FLUNG_API_KEY! })4const result = await flung.media.create({5  contentType: 'image/jpeg',6})

1const response = await fetch('https://api.flung.dev/v1/media', {2  method: 'POST',3  headers: {4    'Authorization': `Bearer ${process.env.FLUNG_API_KEY}`,5    'Content-Type': 'application/json',6    'Idempotency-Key': crypto.randomUUID(),7  },8  body: JSON.stringify({9    contentType: 'image/jpeg',10  }),11})12if (!response.ok) throw new Error((await response.json()).error.message)13const result = await response.json()

A successful answer looks like this:

1{2  "id": "med_aaaaaaaaaaaaaaaaaaaaaaaa",3  "contentType": "image/jpeg",4  "filename": "string",5  "bytes": 1,6  "status": "pending",7  "preview": {8    "status": "processing",9    "thumbnailUrl": "string",10    "hlsUrl": "string",11    "dashUrl": "string",12    "durationSeconds": 113  },14  "createdAt": "2026-11-01T09:00:00.000Z"15}

Request body

The body has the type an object, with the fields below.

Field	Type	Required	Description
`contentType`	`any`	yes
`filename`	`string`	no	at least 1 character; at most 255 characters.
`bytes`	`integer`	no	The file's size. Required over 100 MB, which then uploads in parts. minimum 1.

Responses

Status	Meaning	Body
201	The reserved file and its upload address.	`MediaUpload`
401	Missing, unknown, revoked or expired API key.	`Error`
422	The request failed validation.	`Error`
429	Too many requests for this credential; wait for `retry-after` seconds.	`Error`

Response body

A 201 answer has the type MediaUpload.

Field	Type	Required	Description
`id`	`string`	yes
`contentType`	`MediaType`	yes	What the file really is, read from its first bytes once uploaded.
`filename`	`string \| null`	yes
`bytes`	`integer \| null`	yes
`status`	`"pending" \| "processing" \| "ready" \| "failed"`	yes	`pending` until its bytes arrive; `ready` once a post can use it.
`preview`	`object \| null`	yes	Videos only, where previews are set up: a thumbnail. Read the file again while `processing`.
`preview.status`	`"processing" \| "ready" \| "failed" \| "skipped"`	yes	`skipped` when the video is over 100 MB or this month's thumbnail allowance is used up. Posts never wait for a preview; they use the file as uploaded.
`preview.thumbnailUrl`	`string \| null`	yes	A JPEG frame one second in, 640 pixels wide, at an address that does not expire.
`preview.hlsUrl`	`string \| null`	yes	Always null for now: streaming versions are not made.
`preview.dashUrl`	`string \| null`	yes	Always null for now.
`preview.durationSeconds`	`number \| null`	yes	Always null for now.
`createdAt`	`string`	yes
`uploadUrl`	`string \| null`	yes	For a file up to 100 MB: PUT it here, with your credential and its Content-Length. Null for a multipart upload.
`multipart`	`object \| null`	yes	For a file over 100 MB: how to send it in parts.
`multipart.partSize`	`integer`	yes	Every part but the last is exactly this many bytes.
`multipart.partCount`	`integer`	yes
`multipart.partUrl`	`string`	yes	PUT each part to this address with `{partNumber}` replaced by 1 to partCount, in any order.
`multipart.completeUrl`	`string`	yes	POST here once every part is in.

Doc	Why
API reference	Every endpoint
Schemas	Every request and response type
Errors	Every error code and what to do about it