Files

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.

Get a signed upload link

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.

PUT the bytes

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

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.

Get started

Concepts