Media

Import a file from a URL

Flung fetches a public https file and keeps its own copy, ready to post.

POST/v1/media/import

TL;DR

Question	Answer
What does it do?	Import a file from a URL.
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 `Media`.
In the SDK?	`flung.media.import()`
As an MCP tool?	`import_media`
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

Flung fetches a public https file and keeps its own copy, ready to post. The simplest path for agents and for files already online.

Example

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

1import { Flung } from '@flung.dev/sdk'2
3const flung = new Flung({ apiKey: process.env.FLUNG_API_KEY! })4const result = await flung.media.import({5  url: 'https://example.com/launch.jpg',6})

1const response = await fetch('https://api.flung.dev/v1/media/import', {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    url: 'https://example.com/launch.jpg',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
`url`	`string`	yes	A public https address of the file. Flung fetches it once and keeps its own copy. at most 2048 characters.
`filename`	`string`	no	at least 1 character; at most 255 characters.

Responses

Status	Meaning	Body
201	The file, `ready`.	`Media`
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 Media.

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

Doc	Why
API reference	Every endpoint
Schemas	Every request and response type
Errors	Every error code and what to do about it
`import_media`	The same operation as an MCP tool