对话与消息

OneHop 说你的 SDK 本来就用的协议。把 base URL 指向对应家族、传一个 OneHop 模型 slug, 你现有的客户端无需改动即可工作。

工具调用、system 提示和消息结构的行为完全与供应商文档一致。采样与输出上限类参数是例外: 部分上游不接受这些字段,转发前会被剥掉。把 max_tokens 当成本护栏之前,先看 参数支持。

Chat completions(OpenAI)

curl https://api.onehop.ai/v1/chat/completions \
  -H "Authorization: Bearer $ONEHOP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-5.5",
    "messages": [{ "role": "user", "content": "用一句话解释预付费计费。" }]
  }'

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.ONEHOP_API_KEY,
  baseURL: "https://api.onehop.ai/v1",
});

const completion = await client.chat.completions.create({
  model: "openai/gpt-5.5",
  messages: [{ role: "user", content: "用 OneHop 打个招呼" }],
});

流式

设 stream: true,像往常一样读取 SSE。OneHop 直接把 chunk 转发,不缓冲整个响应, 并在上游结束后按真实用量结算。

curl https://api.onehop.ai/v1/chat/completions \
  -H "Authorization: Bearer $ONEHOP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-5.5",
    "stream": true,
    "messages": [{ "role": "user", "content": "流式写一首俳句" }]
  }'

Anthropic messages

推荐的 Anthropic 入口是 /anthropic/v1/messages。用 x-api-key 头,就和原生 Anthropic SDK 一样。

curl https://api.onehop.ai/anthropic/v1/messages \
  -H "x-api-key: $ONEHOP_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "anthropic/claude-opus-4.8",
    "max_tokens": 256,
    "messages": [{ "role": "user", "content": "用 OneHop 打个招呼" }]
  }'

Responses 与 Vertex

• Responses:POST /v1/responses(或短路径别名 POST /responses),适用于基于 OpenAI Responses 协议构建的客户端。
• **Vertex / Gemini:**指向 https://api.onehop.ai/vertex-ai,以 path 里的模型调用 :generateContent / :streamGenerateContent。

要查看某个模型支持哪些协议,筛选目录即可 —— /v1/models?protocol=anthropic_messages。 完整筛选项见 模型与发现。

参数支持

不是所有模型都会采纳输出上限与采样类参数。上游不接受时,OneHop 会剥掉该参数让请求正常完成 —— 但参数不生效,且按实际产生的 token 计费。

在 OpenAI 兼容端点上,max_tokens 不是可靠的花费上限。 需要硬性花费上限,请改用 API key 的月度额度限制。

2026-07-25 在 POST /v1/chat/completions 上的实测结果:

Anthropic 每一代 Claude 都在收紧采样参数,官方 API 对已废弃的那些直接返回 400。OneHop 会在 转发前剥掉它们,让请求正常完成而不是报错,并在 x-onehop-ignored-params 里列出剥掉了什么。 2026-07-26 对官方 API 的实测:

复用 anthropic_messages 协议的非 Anthropic 模型(zai/*、moonshot/* 等)不受此规则约束, 采样参数原样转发。逐模型的真实情况以 GET /v1/models 的 supported_parameters 为准。

推理模型会让这件事比看上去更费钱:reasoning token 按输出 token 计费,却从不出现在流里。 实测 openai/gpt-5.6-sol 的一次请求,2201 个输出 token 里有 1540 个花在 reasoning 上。

请求里带了不会生效的参数时,响应会带上 x-onehop-ignored-params 头列出它们:

x-onehop-ignored-params: max_completion_tokens,temperature

如果你的应用依赖这些参数,建议在集成测试里检查这个头。上表未列出的参数一律原样转发。

预估 token 数

POST /v1/messages/count_tokens 在真正发起请求前预估输入 token 数。这个端点免费 —— 不扣额度、日志里也不留记录 —— 但它会真的打到上游,因此计入你的速率限制。

curl https://api.onehop.ai/v1/messages/count_tokens \
  -H "x-api-key: $ONEHOP_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "minimax/minimax-m3",
    "messages": [{"role": "user", "content": "Hello"}]
  }'

{ "input_tokens": 6 }

该端点接受 model、messages、system、tools、tool_choice、thinking。 其余字段(max_tokens、temperature、stream 等)官方 schema 一律拒收,OneHop 会剥掉它们 并在 x-onehop-ignored-params 里说明,而不是让你的请求失败。

并非所有模型都支持,anthropic/claude-* 目前就不支持。 token 计数只能由上游作答,而服务 Claude 的账号不提供这个能力,那些模型会返回上游错误而不是计数结果。请把 count_tokens 当尽力而为的能力用: 它报错时回退到你自己的估算,别让用户的请求跟着失败。

响应里的 model 字段

响应的 model 字段回显你请求时用的那个模型 id,包含 author/model 前缀 —— 请求 anthropic/claude-fable-5 拿回的就是 anthropic/claude-fable-5,不是上游的裸名。 唯一例外是模型 fallback:你配置的后备模型真的接手了这次请求时,响应回显实际应答的那个模型 —— 回显别的就是对「哪个模型产出了这段内容」撒谎。