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

# Files

> Upload an input file once, then use its id in any run.

Some tools take a file (an image to edit, audio to transcribe). Pass a public URL, or upload the file and pass its
`file_…` id wherever the tool's input expects a URL.

**1. Get a signed upload link**

```bash theme={null}
curl https://api.spiral.ai/v1/files \
  -H "Authorization: Bearer $SPIRAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "filename": "face.png", "mime_type": "image/png", "size_bytes": 1840221 }'
```

The answer holds the file `id`, an `upload_url`, the `upload_headers` to send and when the link expires.

**2. PUT the bytes**

Send the file to `upload_url` with exactly the `upload_headers`, and no `Authorization` header.

**3. Use the id**

Put the `file_…` id in the run's `input` where the tool expects a URL. There is no confirm call.

| Type | Formats | Largest file |
| - | - | - |
| Image | PNG, JPEG, GIF, WebP | 20 MiB |
| Video | MP4, QuickTime, WebM | 500 MiB |
| Audio | MPEG, WAV, MP4, OGG, FLAC | 200 MiB |
| Document | PDF | 50 MiB |

Uploads are input only: they cannot be downloaded back, and they expire after a day.


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