> ## Documentation Index
> Fetch the complete documentation index at: https://docs.motion.so/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

```json theme={null}
{
  "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:

```bash theme={null}
# 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`:

```json theme={null}
{
  "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"
}
```

```bash theme={null}
# 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`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.