# 文件与输入

> 通过公开 HTTPS 链接、/v1/files 上传接口或小体积 data URI 传入参考图、首尾帧、参考视频与音频。

## 传入媒体文件的三种方式

任务 `input` 中的任意文件类字段（参考图、视频首尾帧、参考视频、音频）都支持以下三种方式：

1. **公开 `https://` URL**：Kerox 可直接拉取的公开链接。
2. **通过 `POST /v1/files` 上传后的 URL**：单文件最大 **200 MB**，保留 **7 天**。
3. **内联 base64 data URI**（`data:image/png;base64,...`）：单次请求内所有内联文件合计不超过 **3 MB**（整包请求体不超过 4 MB）。

## 预签名直传（大文件推荐）

以 JSON 提交文件元信息到 `POST /v1/files`，接口会返回有效期 15 分钟的预签名 `upload_url`、上传时要带的请求头 `upload_headers`，以及后续可用的 `url`。带上这些请求头把文件 `PUT` 到 `upload_url` 后，就可以把 `url` 放进任务参数。上传地址是按你声明的 `content_type` 和 `size` 签名的，所以 `size` 必须是文件的准确字节数，大小或类型不一致会被拒绝。

```bash
# 1. 获取预签名 PUT 地址。"size" 是文件的准确字节数
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. 从返回里取出 upload_url，把文件内容 PUT 过去
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("任务输入 URL:", 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('任务输入 URL:', fileObj.url);
```

## 小文件直接表单上传（≤ 4 MB）

4 MB 以内的文件可直接以 `multipart/form-data` 提交，表单字段名为 `file`，接口会立即返回 `status: "ready"` 的文件对象。

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

## 状态查询与保留期

- 可调用 `GET /v1/files/{id}` 查看预签名上传的状态：文件传完之前是 `"pending"`，传完后变成 `"ready"`。
- 上传的文件会在 **7 天**后自动删除。
- 上传接口接受这些类型：`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`。其他 `content_type` 返回 HTTP `422`（`invalid_parameter`）。每个模型只支持其中一部分：格式和分辨率的限制见模型的 `input_schema`。
