# Files & inputs

> Pass reference images, first frames, videos, or audio via public HTTPS URLs, /v1/files uploads, or small data URIs.

## Three ways to pass media inputs

Any file field in `input` (reference images, first/last frames, reference videos, audio) accepts:

1. **Public `https://` URLs** directly reachable by Kerox.
2. **Kerox file URLs** created via `POST /v1/files` (up to **200 MB** per file, retained for **7 days**).
3. **Inline base64 data URIs** (`data:image/png;base64,...`) up to **3 MB total** per request (entire request body must stay ≤ 4 MB).

## Presigned upload (recommended for large files)

Send file metadata as JSON to `POST /v1/files`. Kerox returns a presigned `upload_url` (valid for 15 minutes), the `upload_headers` to send with the upload, and the final `url` to pass into `POST /v1/tasks`. `PUT` the file to `upload_url` with those headers. The upload is signed for the `content_type` and `size` you declared, so `size` must be the file's exact size in bytes; a different size or type is refused.

```bash
# 1. Request a presigned PUT URL. "size" is the file's exact size in bytes.
RESPONSE=$(curl -s -X POST https://api.kerox.ai/v1/files \
  -H "Authorization: Bearer $KEROX_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"filename\": \"frame.png\",
    \"content_type\": \"image/png\",
    \"size\": $(wc -c < frame.png | tr -d ' ')
  }")
printf '%s\n' "$RESPONSE"

# 2. Take upload_url from the response and upload the bytes to it
UPLOAD_URL=$(printf '%s' "$RESPONSE" | sed -n 's/.*"upload_url": *"\([^"]*\)".*/\1/p')
curl -X PUT "$UPLOAD_URL" \
  -H "Content-Type: image/png" \
  --data-binary @frame.png
```
```python
import os
import requests

headers = {"Authorization": f"Bearer {os.environ['KEROX_API_KEY']}"}
with open("frame.png", "rb") as fh:
    data = fh.read()

file_obj = requests.post(
    "https://api.kerox.ai/v1/files",
    headers={**headers, "Content-Type": "application/json"},
    json={"filename": "frame.png", "content_type": "image/png", "size": len(data)},
    timeout=30,
).json()

requests.put(
    file_obj["upload_url"],
    headers=file_obj["upload_headers"],
    data=data,
    timeout=120,
).raise_for_status()

print("Use in task input:", file_obj["url"])
```
```javascript

const data = await fs.readFile('frame.png');
const res = await fetch('https://api.kerox.ai/v1/files', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.KEROX_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    filename: 'frame.png',
    content_type: 'image/png',
    size: data.byteLength,
  }),
});
const fileObj = await res.json();

const put = await fetch(fileObj.upload_url, {
  method: 'PUT',
  headers: fileObj.upload_headers,
  body: data,
});
if (!put.ok) throw new Error(`Upload failed: ${put.status}`);
console.log('Use in task input:', fileObj.url);
```

## Direct multipart upload (≤ 4 MB)

For files up to 4 MB, upload in a single `multipart/form-data` request with form field `file`. The response returns `status: "ready"` and the usable `url` immediately.

```bash
curl -X POST https://api.kerox.ai/v1/files \
  -H "Authorization: Bearer $KEROX_API_KEY" \
  -F "file=@frame.png"
```

## Checking status & retention

- Call `GET /v1/files/{id}` to check a presigned upload: `"pending"` until the bytes have arrived, then `"ready"`.
- Uploaded files are deleted automatically after **7 days**.
- Uploads accept these content types: `image/jpeg`, `image/jpg`, `image/png`, `image/webp`, `image/bmp`, `image/tiff`, `image/gif`, `image/avif`, `image/heic`, `image/heif`, `video/mp4`, `video/quicktime`, `video/webm`, `audio/wav`, `audio/x-wav`, `audio/wave`, `audio/vnd.wave`, `audio/mpeg`, `audio/mp4`. Any other `content_type` returns HTTP `422` (`invalid_parameter`). Each model takes only some of them: check the model's `input_schema` for its format and resolution limits.
