Images and videos

Any public URL works in media. If the file is on your machine or in private storage, upload it to Marsial in two steps:

1. Ask for an upload URL

curl

curl -X POST "https://api.marsial.dev/v1/media/upload-url" \
  -H "Authorization: Bearer $MARSIAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filename": "jacket.mp4",
    "contentType": "video/mp4",
    "size": 48211234
  }'

Node

const res = await fetch('https://api.marsial.dev/v1/media/upload-url', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.MARSIAL_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "filename": "jacket.mp4",
    "contentType": "video/mp4",
    "size": 48211234
  }),
});
const { data } = await res.json();

Python

import os, requests

res = requests.post(
    "https://api.marsial.dev/v1/media/upload-url",
    headers={"Authorization": f"Bearer {os.environ['MARSIAL_API_KEY']}"},
    json={
        "filename": "jacket.mp4",
        "contentType": "video/mp4",
        "size": 48211234
    },
)
data = res.json()["data"]

200 OK

{
  "data": {
    "uploadUrl": "https://…",
    "publicUrl": "https://…/jacket.mp4",
    "kind": "video",
    "expiresIn": 900
  }
}

2. PUT the file

curl -X PUT "$UPLOAD_URL" \
  -H "Content-Type: video/mp4" \
  --data-binary @jacket.mp4

Then use publicUrl in the post’s media.

Formats and sizes

Type	Formats	Max
Image	JPEG, PNG, WebP	20 MB
GIF	GIF	20 MB
Video	MP4, MOV, WebM	1 GB

In the post

Each media item has a type (image, video, gif or document), a url and, optionally, altText for accessibility. Up to 35 per post. Each network applies its own limits (for example 10 images in an Instagram carousel, 4 on X).