此頁面目前僅提供簡體中文版本。導覽與選單已經是繁體中文。
上传文件
POST https://api.inoneapi.com/v1/files
上传一个文件，获取可在模型请求中引用的 InOneAPI file_id。此接口仅负责存储和类型检测，不进行 OCR、转码、文档解析或模型调用。
使用 Authorization: Bearer $INONEAPI_API_KEY，请求体为 multipart/form-data。文件仅属于上传时的 Key；同一用户或项目的其他 Key 也不能访问。文件操作不产生模型推理费用，不要求钱包余额，但仍受 Key 限流、并发限制和项目状态约束。
请求参数
| 字段 | 类型 | 要求 |
|---|---|---|
file | binary | 必填，恰好一个非空文件。文件名最多 255 个 Unicode 字符，不得含 NUL、换行或路径分隔符。 |
purpose | string | 必填，只能是 user_data，不能重复提交。 |
使用 cURL -F 或 FormData 自动生成 multipart boundary，不要手动设置 Content-Type。不支持 JSON/Base64 上传，也不支持 fine-tune、batch 等 purpose。
格式与配额
| 检测类型 | 支持格式 | 单文件上限 |
|---|---|---|
| image | PNG、JPEG、WebP、GIF | 10 MiB |
| video | MP4、WebM、MOV | 32 MiB |
| audio | MP3、WAV、OGG、AAC、FLAC、M4A、音频 WebM | 10 MiB |
| document | PDF、纯文本、CSV、JSON | 10 MiB |
类型依据内容检测，不能通过修改后缀或声明 MIME 扩大支持范围。容器及文本子类型以响应为准。每个 Key 最近 24 小时创建的现存文件记录最多 1000 个、合计 1 GiB，包含未完成上传。
请求示例
JavaScript 示例运行于 Node.js 20+ 的服务端环境；密钥不可放入浏览器。
curl https://api.inoneapi.com/v1/files \
-H "Authorization: Bearer $INONEAPI_API_KEY" \
-F purpose=user_data \
-F file=@./sample.pdf成功响应
{
"id": "file_ioa_0123456789abcdef0123456789abcdef",
"object": "file",
"filename": "sample.pdf",
"mime_type": "application/pdf",
"media_type": "document",
"bytes": 1024,
"status": "ready",
"created_at": 1789430400,
"purpose": "user_data"
}成功返回 HTTP 200 和文件元数据。id 为平台文件 ID；object 固定为 file；filename 为文件名；mime_type 为检测出的 MIME；media_type 为 image/video/audio/document；bytes 为原始字节数；status 为 ready；created_at 为 Unix 秒；purpose 固定为 user_data。不返回对象 key、内容、签名 URL 或 expires_at。
错误与重试
| HTTP / code | 处理方式 |
|---|---|
400 INVALID_FILE_REQUEST | 检查 multipart、必填字段、文件数量和文件名。 |
400 UNSUPPORTED_FILE_TYPE | 改用支持的真实文件格式。 |
413 FILE_TOO_LARGE | 减小文件；multipart 请求总大小也受限制。 |
429 FILE_QUOTA_EXCEEDED | 清理不再使用的文件或等待配额窗口滚动。 |
503 FILE_STORAGE_UNAVAILABLE | 存储或元数据操作失败，先查询文件列表再决定重试。 |
网络超时并不证明上传未完成。接口没有通用幂等保证，直接重试可能重复占用配额。中断可能留下 uploading 记录，可从列表找回，创建满 5 分钟后删除。认证和通用限流错误参见错误码文档。
保存与后续使用
公共 API 文件通过 COS 1 天生命周期规则清理，异步执行；ready 不保证对象此刻仍存在。每次上游尝试生成的签名 URL 有效 5 分钟。上传属于持久化存储，不属于零数据模式。模型是否接受文件类型由上游能力决定。