Attachments

Attachments let you provide source material for a video job. The API accepts up to 100 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 profiles that expose upload_asset use the same flow. Check your connected profile’s tool list before uploading. 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 100 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: 100.
Maximum URL length: 4096 characters.
Maximum attachment name length: 240 characters.
The API rejects more than 100 attachments with 400 Invalid request.

Getting Started

Working in Motion

Team administration

AI Agents

Guides

Request shape

Fields

URL requirements

Uploading local files

Limits

​Request shape

​Fields

​URL requirements

​Uploading local files

​Limits

Request shape

Fields

URL requirements

Uploading local files

Limits