Media

Upload, import or inline images and video, then reference the resulting media ID in a post.

Preview

Preview: the API and MCP server are in private beta; details may change.

Media is uploaded once, processed into a ready media_id, then referenced from one or more posts. IMMA AI stores media in Cloudflare R2 and serves it from media.getimma.com.

Required scope: posts:write (media is created in the course of building a post).

Endpoints

Method	Path	Description
POST	`/media`	Import from a public URL, send inline base64/data URL image data, or a small multipart upload
POST	`/media/uploads`	Get a presigned URL for a large file upload
GET	`/media/{id}`	Get a media asset's status, metadata and per-platform compatibility

Import from a URL

Request parameters

Name	Type	Required	Description
`url`	string	Yes	Public `http`/`https` URL of the file. Private IP ranges are rejected
`profile_id`	string	Yes	The profile this media belongs to

curl -X POST https://api.getimma.com/v1/media \
  -H "Authorization: Bearer imma_live_xxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/rendang.mp4",
    "profile_id": "prof_01J..."
  }'

Inline data from an AI agent

Used when an agent (Claude, ChatGPT, or another AI your own product's user is subscribed to) generates an image itself and sends the result directly, instead of hosting it at a public URL first.

{
  "data": "data:image/png;base64,iVBORw0KGgoAAAANSU...",
  "profile_id": "prof_01J..."
}

Name	Type	Required	Description
`data`	string	Yes	Raw base64, or a data URL (`data:<mime>;base64,...`)
`profile_id`	string	Yes	The profile this media belongs to

Images only, not video; send video through url or /media/uploads. The image is stored in R2 and validated (MIME detected from the file's own bytes, not the claimed data: header) exactly like any other upload; there is no different treatment just because the source is an AI. Size and MIME limits are the same as any other upload path (see below).

Large uploads

For files too large for a single request, get a presigned URL first:

curl -X POST https://api.getimma.com/v1/media/uploads \
  -H "Authorization: Bearer imma_live_xxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "profile_id": "prof_01J...", "filename": "rendang.mp4", "content_type": "video/mp4" }'

Upload directly to the returned presigned URL, then confirm completion at POST /media/uploads/{id}/complete. The presigned URL is valid for 1 hour.

Get a media asset

curl https://api.getimma.com/v1/media/med_01J... \
  -H "Authorization: Bearer imma_live_xxxxxxxxxxxxxxxxxxxx"

Response:

{
  "id": "med_01J...",
  "status": "ready",
  "mime": "video/mp4",
  "bytes": 48213344,
  "width": 1080,
  "height": 1920,
  "duration_ms": 42000,
  "public_url": "https://media.getimma.com/ws/ws_01J.../med_01J.../original.mp4",
  "thumbnail_url": "https://media.getimma.com/ws/ws_01J.../med_01J.../thumb.webp",
  "compatibility": {
    "instagram_reel": "ok",
    "tiktok": "ok",
    "threads": "ok",
    "facebook_page": "ok"
  }
}

status is one of processing, ready or failed. compatibility is a quick per-platform summary; final validation still happens when the post is built, since TikTok's limits depend on the target account's own creator_info.

Size and format limits

Type	Formats accepted	Max size
Image	JPEG, PNG, WebP, HEIC	20MB
Video	MP4, MOV, WebM	1GB (4GB on the Agency plan)

An inline data payload over the encoded size limit returns 413 payload_too_large. An unrecognized or disallowed MIME type returns 422 unsupported_format.

Errors

Code	HTTP	When
`unauthorized`	401	Missing or invalid API key
`payload_too_large`	413	Inline base64 media exceeded the size limit
`unsupported_format`	422	MIME type not accepted, or `data` did not decode to a valid image
`not_found`	404	Media does not exist, or belongs to another workspace

See Errors for the shared error shape.

Platform notes

Instagram: only accepts JPEG; PNG, WebP and HEIC are automatically converted server side, so you can upload any accepted image format and IMMA AI handles the conversion.
TikTok: photos are always delivered via PULL_FROM_URL; video defaults to chunked FILE_UPLOAD. Maximum video duration comes from the target account's own creator_info, not a fixed platform-wide number.
URLs from tiktok.com, instagram.com, facebook.com and threads.net are rejected when importing by url; only import content you own.
IMMA AI never adds a watermark or logo to uploaded media.