Media Upload API - Upload Images & Videos with Resumable Uploads

Overview

You have three ways to upload files.

Method	Best for	Ceiling
Multipart Upload	Big videos. Chunked, retryable per part.	Your video limit - 5 GB by default, higher on request
Direct Upload	One-shot uploads of moderate files.	5 GiB (single-request storage limit)
Simple Upload	Images and small clips.	90 MB

Recommendation: Use Multipart Upload for videos. It is the only method where a network drop costs you one 64 MiB chunk instead of the whole transfer - with Direct or Simple, a failure at 99% means starting over.

Method 1: Multipart Upload (The Pro Way)

The file is split into fixed 64 MiB chunks that you PUT independently, then we assemble them. Each chunk can be retried or re-signed on its own, so a long upload survives a flaky connection.

Step 1: Initialize

Endpoint: POST /api/v1/upload/multipart/init

// Request
{
  "fileName": "viral-video.mp4",
  "mimeType": "video/mp4",
  "fileSize": 8589934592,   // required - we reject oversized files here, not after the transfer
  "teamId": "..."
}

Response: an uploadId, the path, the partSize, and one presigned url per part.

{
  "uploadId": "2~abc123...",
  "path": "team-id/9f8e7d6c.mp4",
  "partSize": 67108864,
  "parts": [
    { "partNumber": 1, "url": "https://..." },
    { "partNumber": 2, "url": "https://..." }
  ]
}

Step 2: PUT each part - and keep every ETag

Slice the file at partSize boundaries and PUT each slice to its own URL. Every part except the last must be exactly partSize bytes - storage rejects the assembly at the end if they are not uniform. Read the ETag response header from each PUT. You need the full list to finish, and there is no way to recover it afterwards.

curl -X PUT "https://..." --upload-file ./chunk-001 -D -
# HTTP/1.1 200 OK
# ETag: "d41d8cd98f00b204e9800998ecf8427e"

Part URLs are valid for 6 hours. If one expires mid-upload, call POST /api/v1/upload/multipart/sign with { path, uploadId, partNumbers: [12] } to get a fresh URL for just those parts. Parts you already uploaded keep their ETags - do not re-send them.

Step 3: Complete

Endpoint: POST /api/v1/upload/multipart/complete

// Request
{
  "path": "team-id/9f8e7d6c.mp4",
  "uploadId": "2~abc123...",
  "parts": [
    { "partNumber": 1, "etag": "\"d41d8cd9...\"" },
    { "partNumber": 2, "etag": "\"a3f5b2e1...\"" }
  ],
  "teamId": "..."
}

Response: the upload object, including the id you pass when creating a post.

Handling errors on complete

This is worth wiring properly - it decides whether a failure costs you seconds or a full re-upload.

Response	Meaning	What to do
5xx	Something on our side failed, not your file - either we could not assemble the parts, or we assembled them and the step after that failed. Nothing is deleted in either case.	Retry the same `complete` call (a few attempts with backoff). It handles both: it will assemble the parts, or - if they were already assembled - adopt the existing object. Do not re-upload the bytes.
400 about the part list	A part number or ETag is wrong or missing. We discard the parts for you.	Fix the request and start a new upload.
400 about the file	Empty, wrong type, too large, or no readable preview. The bytes have been deleted.	Fix the file and start a new upload - there is nothing left to abort.
403 (quota, permissions)	Rejected before we assemble anything, so your parts are still open.	Call `abort` yourself, then fix the cause.
Success, but you never saw it	e.g. your request timed out after we finished.	Just call `complete` again - it returns the same upload and is not counted twice against your quota.

Giving up

Endpoint: POST /api/v1/upload/multipart/abort with { path, uploadId }. Call it whenever you abandon an upload - unfinished parts occupy storage and count against your usage. If your process dies before it can, transfers left untouched for 7 days are aborted automatically, but that is a backstop, not your cleanup path.

A single upload is capped at 10 000 parts, and the file still has to fit your plan’s video limit (see Limits).

Method 2: Direct Upload

One presigned PUT for the whole file. Simpler than multipart, but a failure means starting over, and the hard ceiling is 5 GiB (a single storage request cannot carry more). Above that we reject at init and point you to multipart.

Step 1: Initialize

Endpoint: POST /api/v1/upload/init

// Request
{
  "fileName": "viral-video.mp4",
  "mimeType": "video/mp4",
  "fileSize": 1073741824,   // optional, but send it - lets us reject oversized files up front
  "teamId": "..."
}

Response: a presigned url and a path.

{
  "url": "https://...",
  "path": "team-id/9f8e7d6c.mp4"
}

The pre-signed URL expires after 30 minutes. If you don’t start uploading within that window, you’ll need to initialize again.

Step 2: Push the Bytes

Send the raw binary file to the url we gave you. Use PUT.

Important: Do not wrap this in JSON or Multipart form. Just send the raw bytes.

curl -X PUT "https://..." \
  --upload-file ./viral-video.mp4

Step 3: Finalize

Tell us you’re done so we can register the file in our system. Endpoint: POST /api/v1/upload/finalize

// Request
{
  "path": "team-id/9f8e7d6c.mp4", // from Step 1
  "teamId": "..."
}

Response: You get an id (e.g., upload_abc123). This is the ID you use when creating a post.

Method 3: Simple Upload (The Lazy Way)

Good for images or small clips. Uses standard multipart/form-data. Endpoint: POST /api/v1/upload

curl -X POST "https://api.bundle.social/api/v1/upload" \
  -H "x-api-key: YOUR_KEY" \
  -F "file=@./meme.jpg" \
  -F "teamId=YOUR_TEAM_ID"

Response: Returns the id immediately.

Upload from a URL

Register media by passing a public HTTP(S) URL instead of uploading the bytes yourself: POST /api/v1/upload/from-url (also exposed in the SDKs and the MCP server). We fetch the asset server-side and register it like any other upload.

Detail	Value
Max size	1 GB
Download timeout	60 seconds
Best for	Small / medium files (typical short-form / feed content)
Not for	Large videos - we fetch the file server-side and cap it at 1 GB / 60 s. For bigger files, upload the bytes yourself with Multipart Upload.

The 1 GB / 60 s limit applies only to URL imports, because we download the file for you. Uploads where you send the bytes stream straight to storage and allow up to your full video limit.

Supported Formats & Limits

Type	Formats	Max Size
Images	JPG, PNG, GIF	25 MB
Videos	MP4, MOV	Platform-dependent (see Limits)
Documents	PDF	100 MB

The default video ceiling is 5 GB per file - talk to us if you need more, which is granted per organization and only applies to Multipart Upload. The max video size also depends on the platform you’re posting to: TikTok allows up to 1 GB, YouTube up to 5 GB, while Discord caps at 10 MB. Check Platform Limits for the exact numbers per platform.

Tip: If you are uploading a picture of your cat (or your mom, we don’t judge), Simple Upload is fine. For a 4K podcast clip, use Multipart.

Video Compression

You can enable automatic video compression on your organization. When enabled, we’ll compress videos larger than 10 MB before they’re stored and posted.

How to enable

Video compression is an organization-level setting. You can toggle it from your dashboard or contact us to enable it. Once on, it applies to all uploads across all teams in your org.

What happens

Setting	Value
Threshold	Videos > 10 MB
Output format	MP4 (H.264 + AAC)
Quality	CRF 30 (good balance of quality and size)
Preset	Medium

We’re smart about it - if the compressed file ends up larger than the original (rare, but it happens with already-compressed videos), we keep the original and toss the compressed version. You always get the smaller file.

This is great if your users upload raw or minimally compressed videos. A 500 MB screen recording can often shrink to under 100 MB with no visible quality loss. Your storage costs will thank you - and so will the upload speeds.

API Documentation

Platforms

Guides

Endpoints

Media Upload

Overview

Method 1: Multipart Upload (The Pro Way)

Step 1: Initialize

Step 2: PUT each part - and keep every ETag

Step 3: Complete

Handling errors on complete

Giving up

Method 2: Direct Upload

Step 1: Initialize

Step 2: Push the Bytes

Step 3: Finalize

Method 3: Simple Upload (The Lazy Way)

Upload from a URL

Supported Formats & Limits

Video Compression

How to enable

What happens

​Overview

​Method 1: Multipart Upload (The Pro Way)

​Step 1: Initialize

​Step 2: PUT each part - and keep every ETag

​Step 3: Complete

​Handling errors on complete

​Giving up

​Method 2: Direct Upload

​Step 1: Initialize

​Step 2: Push the Bytes

​Step 3: Finalize

​Method 3: Simple Upload (The Lazy Way)

​Upload from a URL

​Supported Formats & Limits

​Video Compression

​How to enable

​What happens

Overview

Method 1: Multipart Upload (The Pro Way)

Step 1: Initialize

Step 2: PUT each part - and keep every ETag

Step 3: Complete

Handling errors on complete

Giving up

Method 2: Direct Upload

Step 1: Initialize

Step 2: Push the Bytes

Step 3: Finalize

Method 3: Simple Upload (The Lazy Way)

Upload from a URL

Supported Formats & Limits

Video Compression

How to enable

What happens