REST API
Media
Three calls to attach an image.
Files go straight from you to storage. They never pass through our API, so a large upload does not sit in a request.
POST/v1/media/presign
Ask for an upload URL and a media id.
| Name | Type | Description |
|---|---|---|
fileNameRequired | string | Original file name. |
contentTypeRequired | string | image/jpeg, image/png, image/webp, image/gif |
bytesRequired | number | File size in bytes. |
width | number | Pixel width, if you know it. |
height | number | Pixel height, if you know it. |
durationMs | number | Video length in milliseconds, if you know it. Leave it out and Uplika reads it from the MP4 or MOV header when you confirm the upload. |
altText | string | What the image shows, for screen readers. Applied to carousel items. |
aiGenerated | boolean | true when the file was generated or substantially changed with AI. Naver Blog photos get the AI usage label, and Instagram, YouTube and TikTok get their AI declaration unless the post sets it to false. |
What comes back
| Name | Type | Description |
|---|---|---|
id | string | Pass this to publish as a mediaId. |
uploadUrl | string | One-time PUT target. |
contentType | string | Send exactly this on the PUT. |
expiresIn | number | Seconds the uploadUrl stays valid. |
mediaExpiresAt | string | ISO 8601. After this the media id is reclaimed if it was never published. |
# 1. ask for a slot
curl -X POST https://api.uplika.com/v1/media/presign \
-H "authorization: Bearer $UPLIKA_KEY" \
-H "content-type: application/json" \
-d '{"fileName":"cover.jpg","contentType":"image/jpeg","bytes":184320,"altText":"A cat on a windowsill"}'
# -> { "id": "med_01H...", "uploadUrl": "https://...", "mediaExpiresAt": "2026-08-12T..." }
# 2. send the bytes straight to storage (no auth header)
curl -X PUT "$UPLOAD_URL" -H "content-type: image/jpeg" --data-binary @cover.jpg
# 3. confirm
curl -X POST https://api.uplika.com/v1/media/med_01H.../complete \
-H "authorization: Bearer $UPLIKA_KEY"Upload the bytes
PUT the file to the uploadUrl with the same Content-Type you declared. No auth header. The URL is already signed and it expires.
POST/v1/media/{id}/complete
Confirm the upload. We check the object really exists.
DELETE/v1/media/{id}
Remove a media item you uploaded by mistake. Anything a post still uses, or an original a copy in another workspace still shares, answers 409.
PATCH/v1/media/{id}
Mark or clear the AI-made flag. Every copy of the same file in your workspaces follows. Posts already out do not change.
| Name | Type | Description |
|---|---|---|
aiGeneratedRequired | boolean | true when the file was generated or substantially changed with AI. Naver Blog photos get the AI usage label, and Instagram, YouTube and TikTok get their AI declaration unless the post sets it to false. |
What if the file is already on the web?
Agents without a shell cannot PUT bytes, so the three step upload is out of reach for them. Give us the URL instead and we download the file, copy it into our storage and hand back a media id. We never pass someone else’s URL on to the channel. https only, and Google Drive or Dropbox share links do not work because they return an HTML preview instead of the file.
POST/v1/media/from-url
Copy a public file into your workspace in one call.
| Name | Type | Description |
|---|---|---|
urlRequired | string | Public https URL of the file itself. |
altText | string | What the image shows, for screen readers. |
aiGenerated | boolean | true when the file was generated or substantially changed with AI. Naver Blog photos get the AI usage label, and Instagram, YouTube and TikTok get their AI declaration unless the post sets it to false. |
What if the file is on the person’s device?
presign needs a client that can PUT the bytes, and from-url needs a public https address. When you have neither, open an upload link: a page where the person picks the files in their own browser. Give them the url, read the link with its token until status is ready, then publish the ids in media. The page stops taking files after expiresIn seconds; files that arrived before that stay listed.
POST/v1/media/upload-sessions
Open an upload page for the person. Returns its url and a token.
| Name | Type | Description |
|---|---|---|
note | string | One line shown on the upload page, e.g. what you need the person to upload. Long notes are cut short. |
What opening a link returns
| Name | Type | Description |
|---|---|---|
url | string | The upload page. Give it to the person. |
token | string | Read the link with it: GET /v1/media/upload-sessions/{token}. |
expiresIn | number | Seconds the page keeps taking files. |
maxFiles | number | Most files one link takes. |
accept | string[] | MIME types the page takes. PDF and HWP/HWPX are for DM automations; a post cannot carry them. |
GET/v1/media/upload-sessions/{token}
Read what the person has uploaded through that link so far.
What reading a link returns
| Name | Type | Description |
|---|---|---|
status | string | waiting, ready or expired. Files that arrived before the link expired are still listed. |
workspaceId | string | The workspace the files go to. |
workspaceName | string | Its name. |
showWorkspace | boolean | true when the account has more than one workspace, so the page names the workspace. |
note | string | null | The note you sent. |
maxFiles | number | Most files one link takes. |
expiresInMinutes | number | How long a new link lives, in minutes. |
accept | string[] | MIME types the page takes. |
stalePresigns | number | Only when earlier presigned uploads in this workspace never received their bytes: how many. |
warning | string | Comes with stalePresigns and says what to use instead. |
media | object[] | Every file uploaded through this link: id, duplicateOf, kind, fileName, bytes, publicUrl, width, height, durationMs. Publish the ids as mediaIds. duplicateOf names an earlier id with the same bytes; use one of the two. |
What we accept
| Name | Type | Description |
|---|---|---|
types | image | image/jpeg, image/png, image/webp, image/gif |
size | image | up to 20MB |
aspect ratio | image | up to 100:1 (any pixel width) |
count | image | up to 20 per post on Threads |
types | video | video/mp4, video/quicktime, video/webm |
size | video | up to 8192MB |
length | video | up to 43200 seconds |
width | video | up to 4096px |
carousel | mixed | 2-20 items on Threads, images and video can be mixed |
Common questions
How many calls does one image take?
Three. Presign for an id and an upload URL, PUT the bytes to that URL, then complete to confirm. Only after the third can publish use the id.
Does the file go through your API?
No. It goes straight from you to storage on a signed URL, so a large upload never sits inside one of our requests.
Can I put an image and a video in the same post?
On Threads, yes, in a carousel of two to twenty items. A channel that cannot mix them keeps the video and drops the images, and the target's warning says so. The limits endpoint tells you which channels mix.