使用帮助

POST https://51kik.com/v1/chat/completions（OpenAI Chat Completions）。请求与响应格式与 OpenAI 一致。未在下表列出的顶层字段在允许时会传给上游。

认证

Authorization: Bearer YOUR_API_KEY — 必填。

建议请求头

请求头	说明
`Content-Type`	`application/json`
`Accept`	非流式用 `application/json`；`stream: true` 时用 `text/event-stream`
`x-trace-id`	可选，业务追踪 ID（最长 256 字符）
`x-user-id`	可选，你们系统中的终端用户 ID
`x-agent-name`	可选，Agent 名称（写入用量）

请求体

字段	必填	说明
`model`	是	`GET /models` 返回的 `id`
`messages`	是	数组，至少 1 条
`stream`	否	`true` 时返回 SSE（`chat.completion.chunk`）
`max_tokens`	否	最大输出 token
`temperature`, `top_p`	否	采样
`stop`	否	字符串或字符串数组
`frequency_penalty`, `presence_penalty`	否	与 OpenAI 一致
`seed`	否	整数种子（上游支持时）
`tools`	否	最多 64 个 function tools
`tool_choice`	否	`none` / `auto` / `required` 或 `{ type: "function", function: { name } }`
`pdf_preprocess`	否	网关 PDF 扩展（见下文）
`extra_body`	否	JSON 对象，并入上游请求（OpenAI 兼容线路）
`stream_options`	否	网关对流式固定启用 `include_usage`

限制： JSON 请求体最大 32 MB。

`messages[]`

`role`	说明
`system`, `user`, `assistant`, `developer`	常规角色
`tool`	必须带非空 `tool_call_id`，与先前 `tool_calls` 对应
`assistant`	可含 `tool_calls`；仅 tools 时 `content` 可为 `null`

content 可为字符串、null（视为空），或多模态 part 数组。

用户 `content` 数组（part 类型）

`type`	说明
`text`	文本
`image_url`	`{ "url": "...", "detail": "auto" }`
`input_audio`	音频输入（OpenAI API 字段）
`file`	文件输入，使用嵌套 `file` 对象：`{ "file": { "file_data": "...", "filename": "..." } }`

`pdf_preprocess`（网关扩展）

{ "engine": "native" }

`engine`	行为
`native`	默认，原样转发
`ocr`	OCR 后送上游
`markdown`	提取为 Markdown

可选：max_pages（≤ 50）、merge_pages。

非流式示例

curl -sS "https://51kik.com/v1/chat/completions" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_MODEL_ID",
    "messages": [{"role": "user", "content": "用一句话说明边缘网关。"}]
  }'

流式

设置 "stream": true 且 Accept: text/event-stream。详见流式响应、流式快速开始。

Tools 示例

curl -sS "https://51kik.com/v1/chat/completions" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_MODEL_ID",
    "messages": [{"role": "user", "content": "巴黎天气怎么样？"}],
    "tools": [{
      "type": "function",
      "function": {
        "name": "get_weather",
        "description": "查询城市天气",
        "parameters": {
          "type": "object",
          "properties": { "city": { "type": "string" } },
          "required": ["city"]
        }
      }
    }],
    "tool_choice": "auto"
  }'

模型返回 tool_calls 后，追加带 tool_calls 的 assistant 消息与 role: "tool" 的结果，再发起下一轮。

多模态（文件）

用户消息 content 数组中使用 file type 传入文件，字段嵌套在 file 对象内：

`file` 字段	说明
`file_data`	内联 base64 数据，支持 `data:<mime>;base64,...` 格式
`filename`	文件名，用于推断 MIME 类型（如 `spec.pdf`）

内联文件示例

curl -sS "https://51kik.com/v1/chat/completions" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"model\": \"YOUR_MODEL_ID\",
    \"messages\": [{
      \"role\": \"user\",
      \"content\": [
        { \"type\": \"text\", \"text\": \"列出文档中的关键需求\" },
        { \"type\": \"file\", \"file\": { \"filename\": \"spec.pdf\", \"file_data\": \"data:application/pdf;base64,$(base64 spec.pdf | tr -d '\n')\" } }
      ]
    }]
  }"

图片示例

image_url（OpenAI 兼容方式）：

{ "type": "image_url", "image_url": { "url": "https://example.com/photo.jpg" } }

或使用 file + 内联 base64：

{ "type": "file", "file": { "filename": "photo.jpg", "file_data": "data:image/jpeg;base64,..." } }

详见文件与上下文。

响应（非流式）

响应为 OpenAI 格式 chat.completion，含 choices[].message、usage、id。

错误

{
  "error": {
    "message": "...",
    "type": "invalid_request_error",
    "param": "messages[0].content",
    "code": null
  }
}

状态码	常见原因
400	校验失败（messages、content parts、体积）
401	API Key 无效或过期
403	模型未授权、余额、IP、上游密钥耗尽
429	租户或上游限流
502/503	上游故障

见错误响应 · OpenAI 差异。

认证