# 文件上传

文件上传一次，之后在 Messages、Responses、图片生成和视频生成请求中按 ID 引用。

文件上传一次，之后在模型请求中按 ID 引用，不必每次把同一份内容转成 base64 重发，也不必把文件放到公网 URL 上。

文件 ID 可用于 Messages、Responses、图片生成和视频生成，不能用于 Chat Completions。

## 开始之前

- API key。见[认证](https://openapi.felo.ai/zh-CN/docs/authentication.md)。
- Base URL：`https://openapi.felo.ai`。
- 一个接受对应文件类型的模型。见[检查模型支持](#检查模型支持)。

## 快速开始

### 1. 上传文件

```bash
curl "https://openapi.felo.ai/api/v1/files" \
  -H "Authorization: Bearer ${FELO_API_KEY}" \
  -F "file=@./report.pdf"
```

上传成功返回 HTTP `200` 和文件元数据：

```json
{
  "id": "felo_file_0179...",
  "type": "file",
  "source": "upload",
  "filename": "report.pdf",
  "mime_type": "application/pdf",
  "size_bytes": 482113,
  "created_at": "2026-11-10T02:25:41Z",
  "downloadable": false
}
```

保存 `id`。把它当作不透明字符串使用，不要自行构造或解析。

### 2. 在请求中引用

```bash
curl "https://openapi.felo.ai/api/v1/responses" \
  -H "Authorization: Bearer ${FELO_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.5",
    "input": [
      {
        "role": "user",
        "content": [
          {"type": "input_file", "file_id": "felo_file_0179..."},
          {"type": "input_text", "text": "Summarize the attached report."}
        ]
      }
    ]
  }'
```

同样的两步，用 Python：

```python
import os

import requests

BASE = "https://openapi.felo.ai"
HEADERS = {"Authorization": f"Bearer {os.environ['FELO_API_KEY']}"}


def upload(path: str) -> str:
    with open(path, "rb") as file:
        response = requests.post(
            f"{BASE}/api/v1/files",
            headers=HEADERS,
            files={"file": file},
            timeout=300,
        )
    response.raise_for_status()
    return response.json()["id"]


file_id = upload("./report.pdf")

response = requests.post(
    f"{BASE}/api/v1/responses",
    headers=HEADERS,
    json={
        "model": "gpt-5.5",
        "input": [
            {
                "role": "user",
                "content": [
                    {"type": "input_file", "file_id": file_id},
                    {"type": "input_text", "text": "Summarize the attached report."},
                ],
            }
        ],
    },
    timeout=120,
)
response.raise_for_status()
print(response.json())
```

用 Node.js 20 或更高版本：

```javascript
import { openAsBlob } from "node:fs";
import { basename } from "node:path";

const BASE = "https://openapi.felo.ai";
const headers = { Authorization: `Bearer ${process.env.FELO_API_KEY}` };

async function upload(path) {
  const form = new FormData();
  form.append("file", await openAsBlob(path), basename(path));
  const response = await fetch(`${BASE}/api/v1/files`, { method: "POST", headers, body: form });
  if (!response.ok) throw new Error(`Upload failed: ${response.status} ${await response.text()}`);
  return (await response.json()).id;
}

const fileId = await upload("./report.pdf");
```

### 上传规则

- 请求体是 `multipart/form-data`，只能有一个名为 `file` 的部分。附带其他部分（包括 `purpose`）会返回 `invalid_file`。
- `Content-Type` 交给 HTTP 客户端生成。手动设置会丢失 multipart boundary。
- 上传 URL 不要带查询参数。
- 直接用 HTTP 上传，不要用 SDK 的 Files 方法。OpenAI SDK 的 `files.create()` 总会附带 `purpose`，无法调用这个 endpoint。
- 上传超时或连接中断时，文件可能已经保存。重新上传前先查看文件列表。

## 文件 ID 可以放在哪里

| Endpoint | 文件类型 | 需要的输入模态 | 字段 |
|---|---|---|---|
| `POST /api/v1/messages` | PDF、图片 | `file`、`image` | `messages[].content[]` |
| `POST /api/v1/responses` | PDF、图片 | `file`、`image` | `input[].content[]` |
| `POST /api/v1/images/generations` | 图片 | `image` | `input_references[]` |
| `POST /api/v1/videos/generations` | 图片 | `image` | `frame_images[]` |
| `POST /api/v1/videos/generations` | 图片、MP4、音频 | `image`、`video`、`audio` | `input_references[]` |
| `POST /api/v1/chat/completions` | 不支持 | | |

### Messages

```json
{
  "model": "claude-haiku-4-5",
  "max_tokens": 1024,
  "messages": [
    {
      "role": "user",
      "content": [
        {"type": "document", "source": {"type": "file", "file_id": "felo_file_0179..."}},
        {"type": "text", "text": "Summarize the attached report."}
      ]
    }
  ]
}
```

图片使用 `{"type": "image", "source": {"type": "file", "file_id": "..."}}`。

### Responses

| 文件 | 内容块 |
|---|---|
| PDF | `{"type": "input_file", "file_id": "..."}` |
| 图片 | `{"type": "input_image", "file_id": "...", "detail": "auto"}` |

带 `file_id` 的内容块不能同时带 URL 或 base64 数据。

### 图片生成

```json
{
  "model": "gemini-3-pro-image",
  "prompt": "Keep the product and framing. Replace the background with a sunlit marble countertop.",
  "input_references": [
    {"type": "image_url", "image_url": {"file_id": "felo_file_0179..."}}
  ]
}
```

请求的其余字段、`202` 响应和轮询见[图片生成](https://openapi.felo.ai/zh-CN/docs/guides/image-generation.md)。

### 视频生成

首帧和尾帧放在 `frame_images`：

```json
{
  "model": "YOUR_VIDEO_MODEL",
  "prompt": "The camera slowly pushes in. Keep the colors and composition.",
  "duration": 5,
  "resolution": "720p",
  "frame_images": [
    {
      "type": "image_url",
      "frame_type": "first_frame",
      "image_url": {"file_id": "felo_file_0179..."}
    }
  ]
}
```

需要尾帧时，追加一项 `"frame_type": "last_frame"`。有尾帧就必须有首帧。

参考素材放在 `input_references`，每一项使用与素材类型对应的定位对象：

```json
{
  "input_references": [
    {"type": "image_url", "image_url": {"file_id": "felo_file_IMAGE"}},
    {"type": "video_url", "video_url": {"file_id": "felo_file_VIDEO"}},
    {"type": "audio_url", "audio_url": {"file_id": "felo_file_AUDIO"}}
  ]
}
```

可以提交哪些组合取决于模型和渠道。`frame_images` 与 `input_references` 不能出现在同一个请求里。

### 定位规则

- 图片和视频请求中，每个 `image_url`、`video_url`、`audio_url` 对象只能有 `file_id` 或 `url` 其中一个字段，不能有其他字段。
- 同一个数组里，可以有的条目用 `file_id`，有的条目用 `url`。
- 图片和视频生成只接受你自己上传的文件。要复用生成的图片，传它的输出 `url`。
- 引用了文件的请求失败后不会自动切换到其他渠道。先看错误原因，不要直接换渠道重试。
- 引用同一文件的任务全部进入终态前，保留该文件。提前删除可能导致任务失败。

## 检查模型支持

文件上传成功，不代表所有模型都能使用它。模型必须在公开目录中声明对应的输入模态：

```bash
curl -s "https://openapi.felo.ai/api/platform/model-catalog/model?model=claude-haiku-4-5" \
  | jq '.data.input_modalities'
```

```json
["text", "image", "file"]
```

| 要发送 | `input_modalities` 必须包含 |
|---|---|
| PDF | `file` |
| 图片 | `image` |
| MP4 | `video` |
| 音频 | `audio` |

列表为空或缺失，表示该模型尚未开通文件 ID，请求会返回 `file_model_unsupported`。不要根据模型名称推断是否支持。

## 限制

| 限制 | 值 |
|---|---|
| 上传大小 | 单个文件 100 MiB（104,857,600 字节）；空文件会被拒绝 |
| 单次模型请求引用的总字节数 | 50,000,000 字节 |
| 单次模型请求的引用次数 | 100 |
| 文件名长度 | 255 个字符 |

同一文件引用两次，两项请求限制都按两次计。50 MB 到 100 MiB 之间的文件可以上传，但不能在模型请求中引用。模型或渠道的限制可能更小。

### 文件类型

类型按文件内容识别，不看扩展名，也不看该部分的 `Content-Type`。

| 类型 | 格式 | 可以引用的位置 |
|---|---|---|
| PDF | PDF | Messages、Responses |
| 图片 | PNG、JPEG、GIF、WebP | Messages、Responses、图片生成、视频生成 |
| 视频 | MP4 | 视频生成 |
| 音频 | MP3、WAV、FLAC、OGG | 视频生成 |
| Office | DOCX、XLSX、PPTX | 仅存储 |
| 文本 | UTF-8 文本，按 `text/plain` 保存 | 仅存储 |

其他内容返回 `invalid_file`。

### 文件名

文件名不能包含 `<`、`>`、`:`、`"`、`|`、`?`、`*`、`\` 和控制字符。可以用 `/` 分段，但不能有空段、`.` 或 `..`。

## 管理文件

文件归属于账号。同一账号下的所有 API key 看到的是同一批文件；其他账号不能使用你的文件 ID。

### 列出文件

```bash
curl "https://openapi.felo.ai/api/v1/files?limit=100" \
  -H "Authorization: Bearer ${FELO_API_KEY}"
```

```json
{
  "data": [
    {
      "id": "felo_file_0179...",
      "type": "file",
      "source": "upload",
      "filename": "report.pdf",
      "mime_type": "application/pdf",
      "size_bytes": 482113,
      "created_at": "2026-11-10T02:25:41Z",
      "downloadable": false
    }
  ],
  "first_id": "felo_file_0179...",
  "last_id": "felo_file_0179...",
  "cursor": "felo_file_0179...",
  "has_more": false
}
```

结果从旧到新排列。`has_more` 为 `true` 时，把返回的 `cursor` 带入下一次请求。服务端不提供搜索或按类型筛选。

### 查询单个文件

```bash
curl "https://openapi.felo.ai/api/v1/files/${FILE_ID}" \
  -H "Authorization: Bearer ${FELO_API_KEY}"
```

### 删除文件

```bash
curl -X DELETE "https://openapi.felo.ai/api/v1/files/${FILE_ID}" \
  -H "Authorization: Bearer ${FELO_API_KEY}"
```

```json
{"id": "felo_file_0179...", "type": "file_deleted"}
```

删除立即生效，无法恢复。返回 `503` 表示删除没有完成，重新发送 `DELETE` 即可。

### 下载

上传的文件不能下载。`GET /api/v1/files/{file_id}/content` 返回 `400 file_not_downloadable`；上传响应的 `Location` 头指向文件元数据，不是文件内容。上传的内容请自行保留副本。

下载生成的媒体，使用任务 `outputs` 中的签名 URL。

## 接口说明

所有 endpoint 使用 `Authorization: Bearer YOUR_API_KEY`。成功响应是 JSON 对象本身，没有外层包装。

| 方法 | 路径 | 返回 |
|---|---|---|
| `POST` | `/api/v1/files` | [文件对象](#文件对象) |
| `GET` | `/api/v1/files` | [一页文件](#列表参数) |
| `GET` | `/api/v1/files/{file_id}` | [文件对象](#文件对象) |
| `DELETE` | `/api/v1/files/{file_id}` | `{"id": "...", "type": "file_deleted"}` |
| `GET` | `/api/v1/files/{file_id}/content` | `400 file_not_downloadable` |

`POST`、`DELETE` 和单个文件的 `GET` 带任何查询参数都会返回 `invalid_query`。

### 文件对象

| 字段 | 类型 | 说明 |
|---|---|---|
| `id` | string | 文件 ID，以 `felo_file_` 开头，用作 `file_id` |
| `type` | string | 固定为 `file` |
| `source` | string | `upload` 表示你上传的文件，`generated` 表示模型输出 |
| `filename` | string | 上传时提交的文件名 |
| `mime_type` | string | 按内容识别出的类型 |
| `size_bytes` | integer | 字节数 |
| `created_at` | string | ISO 8601 UTC 时间 |
| `downloadable` | boolean | 上传的文件为 `false` |

### 上传请求

| 部分 | 必填 | 说明 |
|---|---|---|
| `file` | 是 | 文件本身，作为 `multipart/form-data` 的文件部分发送，并带文件名 |

响应带 `Location` 头，值为该文件元数据的 URL。

### 列表参数

| 参数 | 默认值 | 说明 |
|---|---|---|
| `limit` | `100` | 每页数量，1 到 1000 |
| `cursor` | | 上一页返回的 `cursor` |
| `after`、`after_id` | | `cursor` 的别名。三者只能传一个 |
| `order` | `asc` | 只支持 `asc` |

| 响应字段 | 类型 | 说明 |
|---|---|---|
| `data` | array | 文件对象，从旧到新 |
| `first_id` | string 或 null | 本页第一个文件的 ID |
| `last_id` | string 或 null | 本页最后一个文件的 ID |
| `cursor` | string 或 null | 下一页请求的 `cursor` 值 |
| `has_more` | boolean | 是否还有下一页 |

## 错误

Files endpoint、Responses、图片生成和视频生成使用 OpenAI 错误信封：

```json
{
  "error": {
    "message": "This model does not accept this attachment type",
    "type": "invalid_request_error",
    "param": "frame_images.0.image_url",
    "code": "file_model_unsupported"
  }
}
```

Files endpoint 自身的错误，`param` 为 `null`。Messages 返回 Anthropic 的错误格式，没有 `error.code`。Request ID 在 `X-Request-Id` 响应头里。

上传和管理文件时的错误：

| HTTP | `error.code` | 含义 |
|---|---|---|
| 400 | `invalid_content_type` | 请求体不是 `multipart/form-data` |
| 400 | `invalid_file` | 缺少 `file` 部分、有多余的部分、文件为空，或内容类型不支持 |
| 400 | `invalid_filename` | 文件名过长，或包含不允许的字符 |
| 413 | `file_too_large` | 文件超过 100 MiB |
| 400 | `invalid_query` | 带了不支持的查询参数，或 `order` 不是 `asc` |
| 400 | `invalid_limit` | `limit` 不在 1 到 1000 之间 |
| 400 | `invalid_cursor` | 游标格式不对，或同时传了多个游标 |
| 400 | `file_not_downloadable` | 请求了 `/content` |
| 404 | `file_not_found` | 文件不存在、已删除，或属于其他账号 |
| 503 | `file_storage_unavailable` | 文件存储暂时不可用，稍后重试 |
| 503 | `file_upload_expired` | 上传没有在规定时间内完成，重新上传 |

在模型请求中引用文件时的错误：

| HTTP | `error.code` | 含义 |
|---|---|---|
| 400 | `invalid_file_input` | ID 格式不对、同一个定位对象里同时有 `file_id` 和 `url`，或引用超过 100 次 |
| 400 | `unsupported_file_type` | 文件类型与所在位置不匹配，例如把 MP4 放进文档块 |
| 400 | `file_model_unsupported` | 模型没有声明所需的输入模态 |
| 400 | `file_input_too_large` | 引用的文件合计超过 50,000,000 字节 |
| 400 | `file_protocol_unsupported` | 向 Chat Completions 发送了文件 ID |
| 404 | `file_not_found` | 文件不存在、已删除、属于其他账号，或把生成的文件用于图片、视频生成 |

图片和视频生成中，文件也可能在返回 `202` 之后才校验失败。此时任务以 `failed` 结束，`error.code` 是上表中的某一项。

鉴权、余额和限流错误见[错误、限流与重试](https://openapi.felo.ai/zh-CN/docs/guides/errors-and-limits.md)。

## 相关

- [协议与 SDK](https://openapi.felo.ai/zh-CN/docs/guides/protocols.md)
- [图片生成](https://openapi.felo.ai/zh-CN/docs/guides/image-generation.md)
- [异步任务](https://openapi.felo.ai/zh-CN/docs/guides/async-tasks.md)
- [Model API 参考](https://openapi.felo.ai/zh-CN/docs/model-api)
