Chat Completions

使用 OpenAI 兼容协议发起文本、图片和文件对话，并处理非流式与 SSE 响应。

端点：POST /openapi/v1/chat/completions

该接口适合复用 OpenAI SDK 或已有的 Chat Completions 客户端。它兼容常用请求和响应结构，但实际执行能力、模型与权限由 Poco API Key 的配置决定。

请求头

Authorization: Bearer sk-xxxxxxxxxxxxxxxxxxxx
Content-Type: application/json

也可使用 x-api-key: sk-...。

请求参数

参数	类型	必填	说明
`model`	string	是	协议兼容字段，用于响应回显；不覆盖 API Key 的模型配置
`messages`	array	是	至少一条消息；当前只执行最后一条 `user` 消息
`stream`	boolean	否	默认 `false`；设为 `true` 时返回 SSE
`metadata.session_id`	UUID string	否	续聊当前用户有权访问且绑定 Key 匹配的会话
`idempotency_key`	string	否	同一会话内标识同一次业务请求，最长 128 个字符
`n`	integer	否	当前只支持 `1`；其他值返回 HTTP 400
`max_tokens`	integer	否	协议兼容字段；当前不会覆盖 Agent 运行配置
`temperature`、`top_p`	number	否	协议兼容字段；当前不会覆盖 Agent 运行配置
`stop`	string / string[]	否	协议兼容字段；当前不会覆盖 Agent 运行配置
`user`	string	否	协议兼容字段，不用于鉴权或切换用户身份

没有在表中列出的额外 OpenAI 字段可能会被请求模型接收，但不会自动获得对应语义。接入方不应依赖未明确说明的字段。

执行目标和能力来源见 API Key 管理。协议 model 用于兼容与回显，实际模型按 Key、专家或团队配置解析。非流式等待和 SSE 错误帧见错误处理。

非流式文本对话

curl -X POST 'https://<poco-host>/openapi/v1/chat/completions' \
  -H 'Authorization: Bearer sk-xxxxxxxxxxxxxxxxxxxx' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "gpt-4o",
    "stream": false,
    "messages": [
      {"role": "user", "content": "你好"}
    ]
  }'

{
  "id": "chatcmpl-xxx",
  "object": "chat.completion",
  "created": 1739529600,
  "model": "gpt-4o",
  "choices": [
    {
      "index": 0,
      "message": { "role": "assistant", "content": "你好！" },
      "logprobs": null,
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 20,
    "completion_tokens": 10,
    "total_tokens": 30
  }
}

响应头 X-Session-Id 标识会话，X-Run-Id 标识本轮运行。建议业务系统同时保存这两个值。

继续已有会话

{
  "model": "gpt-4o",
  "stream": false,
  "messages": [{ "role": "user", "content": "继续上一轮" }],
  "metadata": {
    "session_id": "<existing-session-uuid>"
  }
}

不传 session_id 通常创建新会话；首次请求也支持创建幂等。续聊会检查用户归属和绑定 Key，相同用户换另一把 Key 也不能读取已绑定的会话。自有未绑定 Key 的普通会话可以在 API 续聊时转为 API 会话并绑定当前 Key；外嵌会话不可续聊。

图片输入

支持 image_url 和 input_image，URL 可以是 HTTP(S) 地址或 data:image/...;base64,...：

{
  "model": "gpt-4o",
  "stream": false,
  "messages": [
    {
      "role": "user",
      "content": [
        { "type": "text", "text": "请描述这张图" },
        {
          "type": "image_url",
          "image_url": { "url": "https://example.com/demo.png" }
        }
      ]
    }
  ]
}

HTTP(S) 图片地址在受理请求时由 Backend 下载，无法访问或返回的不是图片时返回 HTTP 400，规则与 Messages 图片和文件相同。

文件输入

Poco 扩展支持 file 和 document 内容块，来源可使用 base64、Data URL 或 attachments/...：

{
  "model": "gpt-4o",
  "stream": false,
  "messages": [
    {
      "role": "user",
      "content": [
        { "type": "text", "text": "请总结这个 PDF" },
        {
          "type": "file",
          "file_name": "spec.pdf",
          "source": {
            "type": "base64",
            "media_type": "application/pdf",
            "data": "<BASE64_PDF>"
          }
        }
      ]
    }
  ]
}

当前不支持 OpenAI 原生 file_id 上传或引用流程。

流式响应

将 stream 设为 true 后，响应类型为 text/event-stream。每条消息以 data: {json} 发送，最后以 data: [DONE] 结束：

data: {"id":"chatcmpl-xxx","object":"chat.completion.chunk","created":1739529600,"model":"gpt-4o","choices":[{"index":0,"delta":{"role":"assistant"},"finish_reason":null}]}

data: {"id":"chatcmpl-xxx","object":"chat.completion.chunk","created":1739529600,"model":"gpt-4o","choices":[{"index":0,"delta":{"content":"你"},"finish_reason":null}]}

data: {"id":"chatcmpl-xxx","object":"chat.completion.chunk","created":1739529600,"model":"gpt-4o","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}

data: [DONE]

客户端应逐条拼接 choices[0].delta.content，并在收到 [DONE] 后结束。HTTP 连接中断不等于运行失败；需要确认最终状态时，可使用 X-Session-Id 查询会话。

该协议当前不提供结构化输出。需要 JSON Schema 约束结果时，请改用 Messages 结构化输出。