指南
文件上传
文件上传一次,之后在 Messages、Responses、图片生成和视频生成请求中按 ID 引用。
文件上传一次,之后在模型请求中按 ID 引用,不必每次把同一份内容转成 base64 重发,也不必把文件放到公网 URL 上。
文件 ID 可用于 Messages、Responses、图片生成和视频生成,不能用于 Chat Completions。
开始之前
快速开始
1. 上传文件
curl "https://openapi.felo.ai/api/v1/files" \
-H "Authorization: Bearer ${FELO_API_KEY}" \
-F "file=@./report.pdf"上传成功返回 HTTP 200 和文件元数据:
{
"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. 在请求中引用
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:
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 或更高版本:
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
{
"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
| 文件 | 内容块 |
|---|---|
{"type": "input_file", "file_id": "..."} | |
| 图片 | {"type": "input_image", "file_id": "...", "detail": "auto"} |
带 file_id 的内容块不能同时带 URL 或 base64 数据。
图片生成
{
"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 响应和轮询见图片生成。
视频生成
首帧和尾帧放在 frame_images:
{
"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,每一项使用与素材类型对应的定位对象:
{
"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。 - 引用了文件的请求失败后不会自动切换到其他渠道。先看错误原因,不要直接换渠道重试。
- 引用同一文件的任务全部进入终态前,保留该文件。提前删除可能导致任务失败。
检查模型支持
文件上传成功,不代表所有模型都能使用它。模型必须在公开目录中声明对应的输入模态:
curl -s "https://openapi.felo.ai/api/platform/model-catalog/model?model=claude-haiku-4-5" \
| jq '.data.input_modalities'["text", "image", "file"]| 要发送 | input_modalities 必须包含 |
|---|---|
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。
| 类型 | 格式 | 可以引用的位置 |
|---|---|---|
| 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。
列出文件
curl "https://openapi.felo.ai/api/v1/files?limit=100" \
-H "Authorization: Bearer ${FELO_API_KEY}"{
"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 带入下一次请求。服务端不提供搜索或按类型筛选。
查询单个文件
curl "https://openapi.felo.ai/api/v1/files/${FILE_ID}" \
-H "Authorization: Bearer ${FELO_API_KEY}"删除文件
curl -X DELETE "https://openapi.felo.ai/api/v1/files/${FILE_ID}" \
-H "Authorization: Bearer ${FELO_API_KEY}"{"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 错误信封:
{
"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 是上表中的某一项。
鉴权、余额和限流错误见错误、限流与重试。