Questa pagina al momento è disponibile solo in cinese. Navigazione e menu sono già in italiano.

文件上传与引用

上传一次，在模型请求中引用 InOneAPI file_id。网关校验文件归属后，按目标协议转换为私有 COS 签名 URL 或文件内容，再执行服务商协议映射。网关不检查服务商是否支持该素材，模型兼容性错误由上游返回。

接口与权限

所有接口使用 Authorization: Bearer $INONEAPI_API_KEY。文件严格隔离到上传时使用的 API Key；同一用户或项目的其他 Key 不能读取、引用或删除。平台 ID 不可直接交给其他平台，控制台 Playground 附件 ID 也不能代替公共文件 ID。

文件操作不产生模型调用费用，不要求钱包有余额，但受 Key 限流、并发和项目状态限制。API 不提供模型微调、Batch、向量检索或上游 Files API 的透传。

上传文件

必填表单字段：file 为文件内容，purpose 固定为 user_data。不要手动设置 multipart boundary。

curl https://api.inoneapi.com/v1/files \
  -H "Authorization: Bearer $INONEAPI_API_KEY" \
  -F purpose=user_data \
  -F file=@./sample.mp4

{
  "id": "file_ioa_0123456789abcdef0123456789abcdef",
  "object": "file",
  "filename": "sample.mp4",
  "mime_type": "video/mp4",
  "media_type": "video",
  "bytes": 1048576,
  "status": "ready",
  "created_at": 1789430400,
  "purpose": "user_data"
}

图片、音频、文档单文件最多 10 MiB，视频最多 32 MiB；每个 Key 最近 24 小时创建的文件记录合计最多 1 GiB、1000 个，包含未完成上传。内容检测决定 mime_type 和 media_type，不依赖调用方声明的 MIME。支持 PNG/JPEG/WebP/GIF、MP4/WebM/MOV、MP3/WAV/OGG/AAC/FLAC/M4A，以及 PDF、纯文本、CSV、JSON。容器类型和文本子类型以返回的检测结果为准；不进行转码、OCR、文档解析或缩略图生成。

模型请求最多引用 32 次文件，按每次引用累计原始大小不超过 64 MiB，展开后仍受网关请求体限制。文件上传与模型接收素材是独立能力。

Chat Completions

在同一条消息的 content 中混合普通文字和文件：

{
  "model": "YOUR_MODEL_ID",
  "messages": [{
    "role": "user",
    "content": [
      {"type": "text", "text": "描述这段视频"},
      {"type": "file", "file": {"file_id": "file_ioa_0123456789abcdef0123456789abcdef"}}
    ]
  }]
}

统一通过 type: file 引用各类素材，以及 video_url 内容块，属于 InOneAPI 扩展，不是 OpenAI 标准视频协议。原有文字和 URL 原样保留，消息内容顺序不变。

Responses 与 Messages

Responses：将下面内容块放入 input[].content。文档转换为 input_file.file_url；图片转换为 input_image.image_url。

{"type":"input_file","file_id":"file_ioa_0123456789abcdef0123456789abcdef"}

图片也可以显式使用 {"type":"input_image","file_id":"..."}，此时文件必须是图片。通过 input_file 引用视频或音频属于扩展：视频展开为 {"type":"input_video","video_url":"COS 签名 URL"}，音频展开为上表中的 input_audio。

Messages：将下面内容块放入 messages[].content，/v1/messages/count_tokens 使用相同规则。

{"type":"document","source":{"type":"file","file_id":"file_ioa_0123456789abcdef0123456789abcdef"}}

type 必须匹配实际类型：document、image、audio 或 video。PDF 和图片转换为 URL source；纯文本、CSV、JSON 转换为 type: text 的 source。音频和视频是 InOneAPI 扩展，转换为对应类型的 URL source。

当 Responses 或 Messages 路由到 Chat 上游时，网关直接按 Chat 规则展开文件，再转换外层请求协议。不存在可跨平台透传的统一上游文件 ID。

视频、图片与语音生成

媒体 source.type 也接受 file_id 作为 file 的别名，两者都只接受平台文件 ID。

POST /v1/videos、POST /v1/images/generations、POST /v1/audio/speech 均可在 input_references 中引用素材：

{
  "input_references": [{
    "type": "image",
    "role": "first_frame",
    "source": {"type": "file", "file_id": "file_ioa_0123456789abcdef0123456789abcdef"}
  }]
}

该片段需合并到原接口请求中；model、prompt 或语音的 input、voice 等原有必填字段仍然必填。type 必须匹配文件的 image/audio/video 类型。网关只把 source 改为 {"type":"url","url":"COS 签名 URL"}，保留 role，再交给映射 DSL。图片和语音接口的 input_references 是 InOneAPI 扩展，不属于 OpenAI 原生 Images/Speech 参数。此功能不新增图片编辑、音频转写或音频翻译接口。

查询、删除与生命周期

列表返回 object: list、data、has_more、first_id、last_id；将 last_id 作为下一页 after。游标必须属于同一 Key。

curl https://api.inoneapi.com/v1/files \
  -H "Authorization: Bearer $INONEAPI_API_KEY"

curl -X DELETE https://api.inoneapi.com/v1/files/file_ioa_0123456789abcdef0123456789abcdef \
  -H "Authorization: Bearer $INONEAPI_API_KEY"

删除成功返回 {"id":"file_ioa_...","object":"file","deleted":true}。公共 API 文件保存 1 天，由 COS 生命周期规则清理；平台不单独设置或返回 expires_at，不运行定时清理任务。COS 生命周期异步执行，不保证上传满 24 小时立即删除。签名 URL 有效 5 分钟，每次上游尝试重新签名；URL 授权期限不是文件保存期限。异步服务商须在 URL 和文件都可用时取文件。

文件内容保存在私有 COS，数据库只保存对象 key 和元数据。上传文件不属于“内容不落地”的零数据模式。部署仅为 api-files/ 前缀配置 COS 1 天生命周期；不要匹配 playground/，Playground 上传文件没有这条生命周期规则。删除 Key 后其文件 ID 失效，剩余对象由 COS 生命周期回收。COS 自动删除不联动删除数据库元数据，列表中的 ready 只表示上传曾完成，不保证内容仍存在；对象删除后需重新上传。旧元数据不计入最近 24 小时配额，可通过删除接口移除。

上传中断可能留下 uploading 记录；列表可用于找回 ID，创建满 5 分钟后允许删除。只有 ready 文件可引用。主动删除不会撤回已发送给上游的文件内容。

文件错误

认证、Key 限流、模型路由和上游错误仍遵循各接口现有规则。