Attachments

Attachments let you provide source material for a Mosaic Motion job.

The API accepts up to 10 attachments per job. Each attachment must be a publicly accessible signed URL.

Request shape

{
  "attachments": [
    {
      "url": "https://storage.example.com/signed/reference.png",
      "name": "Hero reference",
      "type": "image",
      "content_type": "image/png"
    }
  ]
}

Fields

Field	Required	Description
url	Yes	Publicly accessible signed URL. Maximum 4096 characters.
name	No	Human readable label. Maximum 240 characters.
type	No	One of image, video, audio, or file.
content_type	No	MIME type hint, such as image/png or video/mp4.

URL requirements

Signed URLs must be reachable by Motion servers without additional headers, cookies, or authentication.

Use URLs with enough time to live for ingestion and generation. For long video files, prefer a generous expiry.

Local file paths (such as file:///C:/Users/you/video.mp4) are rejected with 400 Invalid request — Motion servers cannot read files on your machine. Upload local files first (see below).

Uploading local files

If your file only exists locally, use POST /uploads to get a signed upload URL, push the bytes, and attach the returned URL:

# 1. Create an upload ticket
curl -sS -X POST "https://api.motion.so/api/motion/uploads" \
  -H "Authorization: Bearer $MOTION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"filename": "reference.mp4", "content_type": "video/mp4"}'

The response contains upload_url, upload_fields, and attachment_url:

{
  "upload_id": "b3c1...",
  "upload_url": "https://storage.googleapis.com/...",
  "upload_method": "POST",
  "upload_fields": { "key": "...", "policy": "...", "...": "..." },
  "upload_url_expires_in_seconds": 3600,
  "attachment_url": "https://storage.googleapis.com/...signed...",
  "attachment_url_expires_in_seconds": 604800,
  "max_file_size_bytes": 5368709120,
  "content_type": "video/mp4",
  "filename": "reference.mp4"
}

# 2. Upload the file: every upload_fields entry as a form field, file LAST.
#    A 204 response means success.
curl -sS -o /dev/null -w "%{http_code}" "$UPLOAD_URL" \
  -F "key=..." -F "policy=..." \
  -F "file=@./reference.mp4"

# 3. Use attachment_url in the attachments array of your job request.

MCP agents get the same flow through the upload_asset tool.

Size limits by type: video 5 GB, audio 500 MB, images 50 MB. The upload URL is valid for 1 hour; the attachment_url is valid for 7 days.

Rate limit: at most 30 uploads per user per 5 hours (429 rate_limited beyond that). Uploaded files are automatically deleted after 14 days — this flow is for attaching source material to Motion jobs, not for file storage.

Limits

• Maximum attachments per job: 10.
• Maximum URL length: 4096 characters.
• Maximum attachment name length: 240 characters.
• The API rejects more than 10 attachments with 400 Invalid request.