快速开始

这是一份面向研发联调的标准对接文档。当前网关提供 OpenAI Chat Completions 兼容接口，接入时统一使用 POST /v1/chat/completions。

如果你只想先验证链路，可直接复制下方 cURL 示例；如果要在服务中正式对接，优先参考 SDK 的 baseURL 配置说明和联调清单。

接口概览

• 请求方式：POST /v1/chat/completions
• 鉴权方式：Authorization: Bearer sk-xxxx
• 内容类型：application/json
• 响应模式：同步 JSON / 流式 SSE
• 模型参数：传入你已经开通并可用的模型 ID

接入前准备

1. 获取 API Key。请求头格式固定为 Authorization: Bearer sk-xxxx。
2. 确认可用模型。请求中的 model 必须替换为你实际开通的模型 ID。
3. 在服务端保存密钥。不要把生产密钥直接写进前端代码、仓库或公开配置文件。

环境变量示例

API_BASE_URL=https://your-domain.com
API_KEY=sk-your-api-key
MODEL_NAME=your-model-id

标准对接流程

1. 准备域名与密钥：确认网关域名、可用模型和 API Key。
2. 按 OpenAI 兼容方式发起请求：统一使用 POST /v1/chat/completions。
3. 根据业务选择同步或流式：普通请求读取 message.content，流式请求逐块处理 delta.content。
4. 联调验收并切生产配置：校验鉴权、模型、超时、重试和额度规则后再切正式环境。

请求头

请求体

cURL 最小联调请求

curl -X POST https://your-domain.com/v1/chat/completions \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "your-model-id",
    "messages": [
      {"role": "user", "content": "你好"}
    ]
  }'

SDK 示例

import OpenAI from 'openai'

const client = new OpenAI({
  apiKey: process.env.API_KEY,
  baseURL: 'https://your-domain.com/v1',
})

async function main() {
  const response = await client.chat.completions.create({
    model: process.env.MODEL_NAME || 'your-model-id',
    messages: [{ role: 'user', content: '你好' }],
  })

  console.log(response.choices[0]?.message?.content)
}

main().catch(console.error)

from openai import OpenAI
import os

client = OpenAI(
    api_key=os.environ["API_KEY"],
    base_url="https://your-domain.com/v1",
)

response = client.chat.completions.create(
    model=os.environ.get("MODEL_NAME", "your-model-id"),
    messages=[{"role": "user", "content": "你好"}],
)

print(response.choices[0].message.content)

流式请求

curl -N -X POST https://your-domain.com/v1/chat/completions \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "your-model-id",
    "stream": true,
    "messages": [
      {"role": "user", "content": "你好"}
    ]
  }'

import OpenAI from 'openai'

const client = new OpenAI({
  apiKey: process.env.API_KEY,
  baseURL: 'https://your-domain.com/v1',
})

async function main() {
  const stream = await client.chat.completions.create({
    model: process.env.MODEL_NAME || 'your-model-id',
    stream: true,
    messages: [{ role: 'user', content: '你好' }],
  })

  for await (const chunk of stream) {
    const text = chunk.choices[0]?.delta?.content
    if (text) process.stdout.write(text)
  }
}

main().catch(console.error)

响应格式

同步 JSON 响应

{
  "id": "chatcmpl-123",
  "object": "chat.completion",
  "created": 1712476800,
  "model": "your-model-id",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "你好，有什么可以帮你？"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 8,
    "completion_tokens": 10,
    "total_tokens": 18
  }
}

流式 SSE 响应

data: {"id":"chatcmpl-123","object":"chat.completion.chunk","created":1712476800,"model":"your-model-id","choices":[{"index":0,"delta":{"content":"你"},"finish_reason":null}]}

data: {"id":"chatcmpl-123","object":"chat.completion.chunk","created":1712476800,"model":"your-model-id","choices":[{"index":0,"delta":{"content":"好"},"finish_reason":null}]}

data: {"id":"chatcmpl-123","object":"chat.completion.chunk","created":1712476800,"model":"your-model-id","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}

data: [DONE]

流式处理说明

1. 响应头为 text/event-stream。
2. 每个 SSE 事件以 data: 开头。
3. 文本从 choices[0].delta.content 中逐步累积。
4. 收到 finish_reason: "stop" 或 data: [DONE] 后结束读取。
5. 服务端建议设置读取超时和中断兜底，避免长连接悬挂。

常见错误与排查

联调验收清单

• 能用 cURL 成功拿到第一条 200 响应。
• 服务端已正确保存 API Key，前端未直接暴露密钥。
• SDK baseURL 配置为网关地址加 /v1，而不是完整接口路径。
• 流式调用已按 SSE 逐事件解析，不会整段按 JSON 一次性反序列化。
• 生产环境已配置超时、重试、日志脱敏与错误告警。