通过统一 API 接入模型流式输出

开启流式

把 stream 设为 true。-N 参数让 curl 不做缓冲，分块到达即打印。从 /models 选择支持流式、且详情列出 POST /v1/chat/completions 的对话模型：

curl -N https://api.router.one/v1/chat/completions \
  -H "Authorization: Bearer sk-your-router-one-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "<model-id-from-/models>",
    "messages": [{"role": "user", "content": "写一首俳句"}],
    "stream": true
  }'

网络上实际传输的是什么

响应是 text/event-stream：每条 SSE 行携带一个 chat.completion.chunk 对象，choices[].delta 里是片段——第一块通常带 role，后续块携带 content 片段，最后以字面量 [DONE] 结束：

data: {"object":"chat.completion.chunk","choices":[{"delta":{"role":"assistant"},"index":0}]}

data: {"object":"chat.completion.chunk","choices":[{"delta":{"content":"秋"},"index":0}]}

data: {"object":"chat.completion.chunk","choices":[{"delta":{"content":"月"},"index":0}]}

data: {"object":"chat.completion.chunk","choices":[{"delta":{},"finish_reason":"stop","index":0}]}

data: [DONE]

客户端写法

官方 Python SDK 负责解析 SSE，应用仍需记录生成如何结束。先在环境变量中设置 ROUTER_ONE_API_KEY。下面是单个 choice 的纯文本示例：主动请求 usage，在 choices 为空时也保留它，并从响应头读取 request_id。SDK 异常会继续抛出，finally 保留诊断信息，已打印的部分正文也不会丢弃。这里关闭 SDK 自动重试，让再次请求成为显式决定：

from openai import OpenAI
import os
import sys

client = OpenAI(
    base_url="https://api.router.one/v1",
    api_key=os.environ["ROUTER_ONE_API_KEY"],
    max_retries=0,
)

request_id = finish_reason = usage = None
try:
    with client.chat.completions.create(
        model="<model-id-from-/models>",
        messages=[{"role": "user", "content": "写一首俳句"}],
        stream=True,
        stream_options={"include_usage": True},
    ) as stream:
        request_id = stream.response.headers.get("x-request-id")
        for chunk in stream:
            if chunk.usage is not None:
                usage = chunk.usage.model_dump()
            if not chunk.choices:
                continue
            choice = chunk.choices[0]
            if choice.delta.content:
                print(choice.delta.content, end="", flush=True)
            if choice.finish_reason is not None:
                finish_reason = choice.finish_reason
finally:
    print(f"\nrequest_id={request_id} finish_reason={finish_reason}",
          file=sys.stderr)
    print(f"usage={usage}", file=sys.stderr)

if finish_reason is None:
    raise RuntimeError("未收到 finish_reason；请保留部分输出。")
if finish_reason != "stop":
    print("先检查 finish_reason，再决定能否作为最终答案使用。",
          file=sys.stderr)

• 收到 finish_reason 后继续读取：仅包含 usage 的最终分块可能稍后到达。流被中断时，这块也可能永远收不到。usage 缺失表示未知，不能据此认定零计费；结算请查看控制台 → 日志。
• SDK 会在内部消费 [DONE]。这个示例要求收到 finish_reason 才把文本生成视为已结束，Python 迭代器退出本身不能证明这一点。示例不负责重建工具调用，也不验证答案是否满足应用要求。

超时、取消与长生成

• 分别记录建连、等待响应头、等待首个正文 Token、分块间隔和总耗时。推理模型可能正常停顿，但仅凭没有输出，无法判断它是在思考、排队还是已发生中断。
• 结合模型特性与应用等待预算设置客户端超时，并分别检查 SDK、反向代理和托管平台的限制：即使网关允许长等待，它们也可能先关闭流。避免过短的读取或空闲超时误杀正常推理；应用自己的 deadline 到期时，保留取消原因。
• 取消就是关闭 HTTP 连接——没有专门的 API。把 UI 的停止按钮接到请求的 abort 上即可。取消后怎么计费：在 POST /v1/chat/completions 与 POST /v1/responses 上，网关会继续读取上游最多 5 秒以拿到最终 usage，把请求记为 HTTP 499 client_cancelled，按上游报告的用量计费，释放预留余额中未用的部分，并且绝不会把已取消的请求转移到其他路由重试。窗口内没拿到最终 usage、而流已经输出过内容时，上游没有报告的部分按估算计费（截至 2026-10-13）——输出 Token 按已经流出的文本估算，输入 Token 按请求内容估算；在输出任何内容之前就取消、且没拿到任何 usage 的流不计费。控制台 → 日志显示实际结算的费用，Token 数只记上游报告的部分，所以按估算结算的请求可能显示 0 Token、费用却不为零。
• stream: false 的调用结算方式不同（截至 2026-10-09）：在 /v1/chat/completions、/v1/responses 与 /v1/messages 上，关闭连接不会让模型停下——网关会在非流式时间窗内继续等它；模型跑完，就按它报告的用量计费，并把请求记为 HTTP 499 client_cancelled、带上这部分 Token；模型失败或超出时间窗，则不计费。所以长时间的非流式调用即使 SDK 超时，也可能照常计费；SDK 超时后自动发出的重试是另一个独立的请求，也会单独计费——按 openai-python 3.29.0 的 README（2026-10-13 核对），超时的请求默认重试两次。需要几分钟的生成请用 stream: true，或把客户端超时设得比预计生成时间更长。
• 指定模型的原生 Responses 流不会因为「等太久」被网关掐断：这条路径没有网关侧的响应头超时或空闲超时，首个事件之前或事件之间的长时间等待，只会因客户端断开、请求 deadline 到期、上游报错或上游关闭流而结束。model:auto 的候选仍保留各自的时间预算。
• 控制台 → 日志显示每个请求的总耗时，产生过输出的流式请求还显示首字延迟（TTFT）。两者都从网关开始执行请求时起算，因此首字延迟包含故障转移前失败尝试的耗时。客户端测得的首个可见 Token 时间与日志中的首字延迟之差，来自你的网络、客户端和网关接收请求的环节；首字延迟本身就长，则指向排队、故障转移前的失败尝试或模型本身的等待。

怎样判断 SSE 响应真的完成了？

HTTP 200 只确认流已打开。要读取对应协议的终止信号，并持续处理错误直到流关闭。Chat Completions 和 Responses 使用不同的事件格式，不要把 Responses 事件交给 Chat Completions 的 delta 解析器。连接意外结束时，先保留部分输出与 request_id，再决定是否重试。

在请求日志中核对流式用量与结算

已入账的流式请求在控制台 → 日志展示模型、Token、结算费用、总耗时（流产生过输出时另有首字延迟）和状态，同样受 API Key 的预算约束。核账以记录的 usage、实际结算费用和详情中的折扣为准；等待定价的请求可能暂未出现在列表中。客户界面不展示供应商或中间尝试，仅凭状态也无法知道客户端实际收到多少 Token；排查时请保留流内错误与 request_id。

常见问题