对话补全

POST /v1/chat/completions 接受标准 OpenAI 参数:messages、temperature、max_tokens、tools、response_format、stream 等,具体支持范围取决于所选模型(模型库的能力标签可查)。在此之上多三个可选字段:models、reasoning,以及响应里的 provider。

请求与响应

非流式请求
curl https://inferstream.cn/v1/chat/completions \
  -H "Authorization: Bearer $INFERSTREAM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-chat",
    "messages": [
      {"role": "system", "content": "你是一个简洁的助手。"},
      {"role": "user", "content": "用一句话介绍杭州。"}
    ]
  }'
响应
{
  "provider": "Deepseek",
  "id": "chatcmpl-…",
  "object": "chat.completion",
  "created": 1789000000,
  "model": "deepseek-chat",
  "choices": [{
    "index": 0,
    "message": { "role": "assistant", "content": "…" },
    "finish_reason": "stop"
  }],
  "usage": {
    "prompt_tokens": 32,
    "completion_tokens": 48,
    "total_tokens": 80,
    "prompt_tokens_details": { "cached_tokens": 0 },
    "completion_tokens_details": { "reasoning_tokens": 0 }
  }
}

usage 里的 prompt_tokens_details.cached_tokens 是按缓存价计费的输入 token,completion_tokens_details.reasoning_tokens 是推理 token(计入输出)。计价规则见计费。

流式

把 stream 设为 true 即以 SSE 逐段返回。加上 stream_options.include_usage 后,最后一个 chunk 会带 usage(此时 choices 为空数组),流式与非流式都能精确核对 token 用量。provider 只出现在第一个 chunk。

流式(Python,openai SDK)
from openai import OpenAI

client = OpenAI(base_url="https://inferstream.cn/v1", api_key="sk-...")

stream = client.chat.completions.create(
    model="deepseek-chat",
    messages=[{"role": "user", "content": "用一句话介绍杭州。"}],
    stream=True,
    stream_options={"include_usage": True},
)
for chunk in stream:
    if chunk.choices:
        print(chunk.choices[0].delta.content or "", end="")
    if chunk.usage:
        print("\n", chunk.usage)
SSE 原始数据(节选)
data: {"provider":"Deepseek","id":"chatcmpl-…","object":"chat.completion.chunk","model":"deepseek-chat","choices":[{"index":0,"delta":{"role":"assistant"},"finish_reason":null}]}

data: {"id":"chatcmpl-…","object":"chat.completion.chunk","model":"deepseek-chat","choices":[{"index":0,"delta":{"content":"杭州"},"finish_reason":null}]}

data: {"id":"chatcmpl-…","object":"chat.completion.chunk","model":"deepseek-chat","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}

data: {"id":"chatcmpl-…","object":"chat.completion.chunk","model":"deepseek-chat","choices":[],"usage":{"prompt_tokens":32,"completion_tokens":48,"total_tokens":80}}

data: [DONE]

首字节前出错时返回普通 JSON 错误;已开始输出后出错,错误以 SSE 事件发出。中途断开按已生成的 token 计费,是否重发由调用方决定。

多模型回退

请求里加可选字段 models,给出候选模型的顺序(最多 5 个,重复项自动去掉)。有 models 时,model 只是第一个候选的别名;两者都给且不一致时以 models[0] 为准。/v1/chat/completions、/v1/responses 与 /claude/v1/messages 都支持。

POST /v1/chat/completions
{
  "model": "gpt-4o",
  "models": ["gpt-4o", "claude-sonnet-4", "deepseek-v3"],
  "messages": [{"role": "user", "content": "用一句话介绍杭州。"}],
  "stream": true
}

切换只发生在首字节之前:一个候选在返回任何内容前失败、且错误可重试(上游 5xx、429、超时,以及该模型没有可用渠道或当前用户组无权调用)时,网关换下一个候选;一旦流式响应已经开始,就不再切换,调用方不会收到拼接的内容。每个候选内部仍会先在同一模型的多条渠道之间重试。

按实际服务的模型计费,响应体里的 model 与 X-InferStream-Model 都是实际服务的模型名;对当前用户组不可见或被 Key 的模型限制排除的候选直接跳过。候选名在平台上不存在时整个请求返回 400 invalid_models,防止拼写错误悄悄落到别的模型。

推理参数

各家推理模型的开关和预算参数名都不一样。统一用可选字段 reasoning 表达,网关翻译成对应上游的原生参数;不支持推理的模型静默忽略。原生参数(reasoning_effort、enable_thinking、thinking)也接受,两者都给时以 reasoning 为准。

请求
{
  "model": "deepseek-chat",
  "messages": [{"role": "user", "content": "27 × 43 等于多少?"}],
  "reasoning": { "effort": "medium", "max_tokens": 4096, "exclude": false }
}
上游翻译成
OpenAIreasoning_effort
Anthropicthinking: { type: "enabled", budget_tokens };max_tokens 缺省时按 effort 取 2k / 8k / 16k
百炼 / 通义 / DeepSeekenable_thinking: true + thinking_budget(OpenAI 兼容口)
Geminithinking_config.thinking_budget
其他静默忽略,不报错

effort 取 low / medium / high;max_tokens 是推理预算;exclude: true 时不返回推理文本,但推理 token 照常计费。响应里非流式在 message.reasoning,流式在 delta.reasoning;原有的 reasoning_content 字段保留并同时给出。推理 token 计入输出 token,数量见 usage.completion_tokens_details.reasoning_tokens。

响应(节选)
{
  "choices": [{
    "message": {
      "role": "assistant",
      "content": "1161。",
      "reasoning": "27 × 40 = 1080,27 × 3 = 81,相加得 1161。"
    },
    "finish_reason": "stop"
  }],
  "usage": {
    "prompt_tokens": 18,
    "completion_tokens": 52,
    "total_tokens": 70,
    "completion_tokens_details": { "reasoning_tokens": 34 }
  }
}

服务方与请求号

同一个模型名背后可能是不同的供应商。每个成功响应都标明实际服务方:JSON 响应与 SSE 的第一个 chunk 带顶层字段 provider(模型库里的供应商名,如 OpenAI、Qwen、Deepseek),同时给出三个响应头。

响应头含义
X-InferStream-Provider实际服务的供应商,与 provider 字段相同
X-InferStream-Model实际服务的模型名(多模型回退后可能不是请求里的第一个)
X-Request-Id网关请求号,成功响应才有;错误响应看 X-Oneapi-Request-Id 头或 message 末尾
响应(节选)
HTTP/1.1 200 OK
X-InferStream-Provider: Qwen
X-InferStream-Model: qwen-plus
X-Request-Id: 20260910110743325678000tMNbU2xW

{
  "provider": "Qwen",
  "id": "chatcmpl-…",
  "model": "qwen-plus",
  "choices": [ … ]
}

provider 是额外字段,OpenAI SDK 会原样保留在响应对象上(Python 里用 resp.model_extra["provider"]),不影响严格按 schema 校验的客户端解析 choices。事后拿响应 id 查费用查询接口,结果里也有 provider。