此頁面目前僅提供簡體中文版本。導覽與選單已經是繁體中文。

Chat Completions

如需引用文件，先通过 文件 API 上传素材，再使用返回的 file_id。网关负责转换，服务商是否接受由上游返回结果。

在 messages[].content 使用 {"type":"file","file":{"file_id":"..."}}。图片展开为 image_url，视频为 InOneAPI 扩展 video_url，音频为 input_audio，文档为 file.file_data。普通文字仍使用 type: text，保持原顺序。

使用 POST /v1/chat/completions 调用 OpenAI 兼容的对话、工具调用、JSON 输出和流式生成。InOneAPI 保持公开请求形态稳定，并根据 model 路由到已启用的供应商映射。

接口地址

https://api.inoneapi.com/v1/chat/completions

# -H "X-APP-NAME: Your App Name"
# -H "X-APP-URL: https://your-app.example.com"
curl "https://api.inoneapi.com/v1/chat/completions" \
  -H "Authorization: Bearer $INONEAPI_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "YOUR_MODEL_ID",
  "messages": [
    {
      "role": "user",
      "content": "Hello"
    }
  ]
}'

参数

字段类型必填说明
modelstring是InOneAPI 公共模型 ID，网关会映射到已启用的上游模型。
messagesarray是有序消息数组，常用角色包括 system、user、assistant、tool。
temperaturenumber否采样随机性。供应商范围不同，通常使用 0-2。
top_pnumber否核采样。通常和 temperature 二选一调整。
max_tokensnumber否生成上限。部分供应商使用 max_completion_tokens，映射会在支持时转换。
streamboolean否为 true 时返回 SSE 格式的 chat completion chunks。
toolsarray否OpenAI 兼容工具定义。是否可用取决于模型和映射。
tool_choicestring/object否控制自动、强制或指定工具调用。
response_formatobject否支持模型可用于 JSON object 或 JSON schema 输出。
stopstring/array否停止序列，支持数量由供应商决定。
userstring否终端用户标识，用于滥用追踪。不要放密钥或个人敏感信息。

消息内容

纯文本消息可以直接使用字符串 content。多模态模型可以使用 content parts，例如 text 和 image_url；不支持的类型会按映射能力拒绝或转换。

{
  "role": "user",
  "content": [
    { "type": "text", "text": "描述这张图片。" },
    { "type": "image_url", "image_url": { "url": "https://example.com/image.png" } }
  ]
}

响应

非流式响应遵循 OpenAI chat completion 结构。Token 用量会在可行时本地计算，并按模型配置对齐官方供应商算法。

{
  "id": "chatcmpl_...",
  "object": "chat.completion",
  "created": 1760000000,
  "model": "YOUR_MODEL_ID",
  "choices": [
    {
      "index": 0,
      "message": { "role": "assistant", "content": "TTFT 是从请求开始到收到首个 token 的时间。" },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 18,
    "completion_tokens": 13,
    "total_tokens": 31
  }
}

流式响应

设置 stream: true 后，逐行解析每个 data: JSON chunk，直到 data: [DONE]。首个 chunk 是客户端侧 TTFT 的主要信号；响应头 X-Gateway-Trace-ID 可关联网关诊断。

错误处理

400 通常表示 JSON、参数或映射错误；401/403 表示密钥或权限问题；429 应遵循 Retry-After 并检查预算或速率；5xx 排查时保留 Trace ID。

  • 不要在已经收到部分流式输出后盲目重试。
  • API Key 只放服务端。
  • 日志记录 X-Gateway-Trace-ID、状态、模型和耗时，不记录完整提示词或输出。
Chat Completions · 文件 · InOneAPI