이 페이지는 현재 중국어로만 제공됩니다. 내비게이션과 메뉴는 한국어로 표시됩니다.

文本 API 指南

从单次问答、多轮对话到流式输出和文件理解，文本请求都通过公共模型 ID 选择模型。先选择支持所需输入类型、上下文长度和协议的模型，再确定消息格式。文本输出模型并不一定支持图片、音频或视频输入。

选择接口

场景接口输入与输出
OpenAI 兼容对话、常见 SDK 集成POST /v1/chat/completionsmessages；读取 choices[].message。
Responses 格式的应用POST /v1/responsesinput；遍历 output[] 中的消息和内容块。
Anthropic Messages 格式的应用POST /v1/messagesmessages，顶层 system、必填 max_tokens；读取 content[]。

不同接口的事件、工具结果和结构化输出字段不能直接混用。网关会按已配置映射转换支持的协议，不代表所有服务商实现所有高级功能。Responses 的状态管理和工具能力以实际映射为准，不要假定服务端自动保存会话。

发送请求与多轮对话

先在控制台创建 API Key 并选择可用的公共模型 ID。示例的 YOUR_MODEL_ID 是占位符。INONEAPI_API_KEY 仅保存在服务端环境变量中；JSON 请求带 Content-Type: application/json。

以下 Node.js 20+ 示例保留第一轮 assistant 消息，再追加用户消息发送第二轮。应用负责保存和裁剪历史，控制上下文长度；每次传入的历史都可能参与输入计费。

curl  https://api.inoneapi.com/v1/chat/completions \
  -H "Authorization: Bearer $INONEAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_MODEL_ID",
    "messages": [
      {"role": "system", "content": "Answer concisely."},
      {"role": "user", "content": "Explain HTTP/2 in one sentence."}
    ],
    "stream": false
  }'

读取响应与流式输出

非流式先检查 HTTP 状态，再读取 choices[0].message.content；调用工具时内容可能为空，并在 tool_calls 中返回调用信息。finish_reason: length 表示可能被生成上限截断；检查 usage，但缺失用量不等于免费。

流式使用 SSE。cURL 的 -N 关闭输出缓冲，方便观察事件：

curl  -N https://api.inoneapi.com/v1/chat/completions \
  -H "Authorization: Bearer $INONEAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"YOUR_MODEL_ID","messages":[{"role":"user","content":"Explain HTTP/2."}],"stream":true}'

客户端按空行切分 SSE 事件，拼接 data: 行，再解析 JSON。网络 chunk 不等于一条完整事件；Chat 中读取 choices[].delta.content，收到 [DONE] 结束。工具参数也可能被拆成多个 delta。Responses 和 Messages 有各自事件类型，不能套用 Chat 解析器。连接断开只代表读取停止，不能保证上游生成取消或费用回滚。

引用文件与多模态输入

先使用同一 Key 上传素材，再把返回 ID 放入消息。以下是完整 Chat 请求体；实际模型必须支持文档输入。图片、音频、视频也可以使用该引用格式，网关按检测类型展开。统一 type: file 是 InOneAPI 扩展，不是跨平台通用文件协议。

{
  "model": "YOUR_MODEL_ID",
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "Summarize this document."
        },
        {
          "type": "file",
          "file": {
            "file_id": "file_ioa_0123456789abcdef0123456789abcdef"
          }
        }
      ]
    }
  ]
}

Responses 使用 input[].content 中的 {"type":"input_file","file_id":"..."}；Messages 使用匹配素材类型的内容块和 source: {"type":"file","file_id":"..."}。上传成功并不保证模型能解析 PDF 或媒体。每个模型请求最多 32 次文件引用，按每次引用计入原始大小，合计不超过 64 MiB；展开后仍受请求体限制。

文件上传与引用

工具调用与结构化输出

工具调用完整流程是：发送 tools 定义，读取 assistant 的 tool_calls，校验工具名称和参数，在业务服务端执行获准操作，再追加原 assistant 消息和带 tool_call_id 的 role: tool 结果，继续调用。模型提出调用不等于工具已经执行；为循环设置次数和时间上限。

需要 JSON 时，仅向支持的模型发送 response_format。服务端仍应解析并验证 JSON/schema，处理拒绝、截断和不符合结构的响应。temperature、top_p、token 上限和工具能力按模型配置选择，不能把所有可选字段同时套到所有模型。

上线检查与错误处理

400 优先检查消息结构、模型参数和上下文限制；401/403 检查密钥权限；402 检查余额与预算；429 检查限流并遵循 Retry-After；5xx 进行有上限的退避。对于超时或流式中断，先确认业务是否允许重复生成，避免无条件重试造成重复费用。

记录 HTTP 状态、模型 ID、耗时和 X-Gateway-Trace-ID，不要记录密钥或敏感提示词。将会话保存在应用自己的存储中，按用户权限隔离；不要把 file_id 当作永久文档库。

Chat Completions · Responses · Anthropic Messages

텍스트 · 문서 · InOneAPI