Working with local files

The MCP server does not accept local file paths directly. If your image or video is on your laptop, a server, or any non-public location, you have a few options.

Quick decision

My media is…	What to do
At a public HTTPS URL	Pass `mediaUrls` in `create_post` — no upload needed
On my laptop or server	Upload to VoxBurst first, get a `mediaId`, pass as `mediaIds`
In Google Drive	Use `POST /v1/media/import-from-drive` (authenticated import)
Already in VoxBurst	Use the `mediaId` you already have

Option 1 — Public URL (simplest)

If your file is hosted at a public HTTPS URL (CDN, cloud storage with public access, etc.):


create_post(
  content: "Check this out",
  accountIds: ["acc_instagram_abc123"],
  contentType: "IMAGE",
  mediaUrls: ["https://cdn.example.com/photo.jpg"]
)

The MCP server registers the URL with VoxBurst automatically. No upload step needed.

Requirements: URL must be publicly accessible (no auth headers required). HTTPS only. Supports JPEG, PNG, WebP, GIF, MP4, MOV.

Option 2 — Upload first, then post (local files)

MCP does not accept local file paths like /Users/you/photo.jpg. You must upload the file to VoxBurst storage first, then reference the resulting media ID.

Request a presigned upload URL


curl -X POST https://api.voxburst.io/v1/media/upload \
  -H "Authorization: Bearer vb_live_xxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "filename": "photo.jpg",
    "contentType": "image/jpeg",
    "sizeBytes": 204800
  }'

Response:


{
  "mediaId": "media_abc1234567890abc12345678",
  "uploadUrl": "https://s3.amazonaws.com/...",
  "uploadHeaders": { "Content-Type": "image/jpeg" },
  "expiresAt": "2026-06-01T10:15:00Z"
}

PUT your file directly to S3


curl -X PUT "https://s3.amazonaws.com/..." \
  -H "Content-Type: image/jpeg" \
  --data-binary @/path/to/photo.jpg

Poll until the media is READY


curl https://api.voxburst.io/v1/media/media_abc1234567890abc12345678 \
  -H "Authorization: Bearer vb_live_xxxxxxxxxxxxx"

Poll every 2–3 seconds until "status": "READY". Processing typically takes 2–10 seconds for images, longer for video.

Create the post using the media ID


create_post(
  content: "Check this out",
  accountIds: ["acc_instagram_abc123"],
  contentType: "IMAGE",
  mediaIds: ["media_abc1234567890abc12345678"]
)

Option 3 — Register an external URL (CDN reference)

If your file is hosted externally but you want VoxBurst to store a reference to it without re-hosting:


curl -X POST https://api.voxburst.io/v1/media/register \
  -H "Authorization: Bearer vb_live_xxxxxxxxxxxxx" \
  -d '{
    "url": "https://cdn.example.com/photo.jpg",
    "contentType": "image/jpeg",
    "filename": "photo.jpg"
  }'

Response includes a mediaId. Use that ID in mediaIds when creating your post.

Option 4 — Import from Google Drive

If your file is in Google Drive (requires an OAuth access token with Drive read scope):


curl -X POST https://api.voxburst.io/v1/media/import-from-drive \
  -H "Authorization: Bearer vb_live_xxxxxxxxxxxxx" \
  -d '{
    "fileId": "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs",
    "filename": "campaign-photo.jpg",
    "mimeType": "image/jpeg",
    "accessToken": "ya29.your_google_oauth_token"
  }'

Poll GET /v1/media/import/:jobId/status until status: complete.

Tell your AI agent to handle the upload

If you are working with an AI agent and have a local file, give it this instruction:

“Before posting, I need to upload a local file. The file is at /path/to/photo.jpg. Use the VoxBurst media upload API to get a presigned URL, upload the file, wait for it to be ready, then use the media ID when creating the post.”

The agent will call the REST Media API endpoints to complete the upload flow, then use create_post with mediaIds.

Summary

Approach	When to use	Requires direct API calls?
`mediaUrls`	File is at a public HTTPS URL	No — MCP handles it
Upload flow	File is local or private	Yes — use REST Media API
`register`	CDN file, just want a reference	Yes — one REST call
Drive import	File is in Google Drive	Yes — REST + Google OAuth