接入文档
迅流API 完整兼容 OpenAI 接口协议。任何支持自定义 baseURL 的 SDK、
框架、客户端都能直接接入——只改两行配置,不学新协议。
https://xunliu.fun/v1
三步接入
-
注册并创建密钥
在控制台「API 密钥」页新建 API Key,格式为
sk-xl-开头。密钥只在创建时完整显示一次,请立即保存。 -
把 baseURL 指向迅流
保留官方 SDK 不动,把
https://api.openai.com/v1换成https://xunliu.fun/v1。 -
把 model 换成迅流的模型名
模型名见价格页,大小写与连字符需完全一致,例如
Qwen3.8-Max、DeepSeek-V4.1-Flash。
认证方式
所有请求在请求头带上 Bearer Token:
Authorization: Bearer sk-xl-xxxxxxxxxxxxxxxx
Content-Type: application/json
密钥泄露后请立刻在控制台删除并新建;服务端不会以任何形式回显完整密钥。 请勿把密钥写进前端代码或公开仓库。
对话补全
curl https://xunliu.fun/v1/chat/completions \
-H "Authorization: Bearer $XUNLIU_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "Qwen3.8-Max",
"messages": [
{"role": "system", "content": "你是一个简洁的技术助手。"},
{"role": "user", "content": "用一句话解释什么是向量数据库。"}
],
"temperature": 0.7,
"max_tokens": 512
}'
import os
from openai import OpenAI
client = OpenAI(
base_url="https://xunliu.fun/v1",
api_key=os.environ["XUNLIU_API_KEY"],
)
resp = client.chat.completions.create(
model="Qwen3.8-Max",
messages=[{"role": "user", "content": "你好,介绍一下你自己"}],
)
print(resp.choices[0].message.content)
print(resp.usage) # 输入/输出 token 用量,按此扣费
import OpenAI from "openai";
const ai = new OpenAI({
baseURL: "https://xunliu.fun/v1",
apiKey: process.env.XUNLIU_API_KEY,
});
const res = await ai.chat.completions.create({
model: "DeepSeek-V4.1-Flash",
messages: [{ role: "user", content: "Hello!" }],
});
console.log(res.choices[0].message.content);
流式输出
传入 "stream": true 即可按 SSE 逐块接收。首字延迟与输出速度随模型档位不同
(约 0.4–3.6 秒首字、30–170 tokens/s),由所选模型决定。
支持思考的模型会先发 delta.reasoning_content,再发正文
delta.content:
stream = client.chat.completions.create(
model="Kimi-K3.1-Pro",
messages=[{"role": "user", "content": "写一首关于下雨的五言绝句"}],
stream=True,
)
for chunk in stream:
delta = chunk.choices[0].delta
reasoning = getattr(delta, "reasoning_content", None)
if reasoning:
print(reasoning, end="", flush=True) # 思考过程
if delta.content:
print(delta.content, end="", flush=True) # 正式回答
模型清单
共 45 个模型,覆盖通义千问、智谱 GLM、Kimi、DeepSeek、字节 Seed、腾讯混元、MiniMax、阶跃星辰、小米 MiMo、OpenAI GPT 等 11 家厂商。完整单价、上下文长度与推理档位见模型价格页。 也可以直接查询接口:
curl https://xunliu.fun/v1/models \
-H "Authorization: Bearer $XUNLIU_API_KEY"
错误码
| HTTP | error.code | 含义 | 是否扣费 |
|---|---|---|---|
| 400 | invalid_request_error | 参数缺失、messages 为空、max_tokens 超上限、文本模型传图 | 否 |
| 400 | context_length_exceeded | 超过所选模型的上下文上限 | 否 |
| 401 | invalid_api_key | 未带 Bearer、格式不是 sk-xl-、密钥无效或已停用 | 否 |
| 402 | insufficient_quota | 账户余额不足,需先充值 | 否 |
| 402 | token_quota_exceeded | 该密钥自身的额度已用完(后台可为单个密钥设额度) | 否 |
| 403 | account_disabled | 账号已被停用 | 否 |
| 404 | model_not_found | 模型名不存在(大小写、连字符需完全一致) | 否 |
| 429 | rate_limit_exceeded | 超出密钥的 RPM 或每日请求上限 | 否 |
| 502 | upstream_error | 上游推理异常,可退避重试 | 否 |
| 503 | upstream_not_configured | 服务端尚未配置可用的上游通道 | 否 |
错误响应统一为 {"error": {"message", "code"}},HTTP 状态码与 code 同时给出,
既有 SDK 的异常处理逻辑无需改动。
限流与配额
- 限流:密钥默认不限流;管理员可在后台为单个密钥设置 RPM 与每日请求上限,超限返回 429。
- 上下文上限:全系 128K 起步,旗舰档 1M(见价格页),超限直接 400 且不扣费。
- 请求超时:非流式按上游通道超时执行(默认 120 秒,后台可在 5~300 秒间调整); 流式会按所选模型的速度节流输出,单次请求最长约 240 秒。
- 退避建议:收到 429 时指数退避重试(1s / 2s / 4s),不要固定间隔轰炸。
常见问题
能直接用官方 SDK 吗?
可以。OpenAI 官方 SDK、LangChain、LlamaIndex、Dify、Cherry Studio、NextChat 等只要支持自定义 baseURL 就能接入,不需要改协议层代码。
为什么返回的 model 字段和我请求的不完全一样?
响应里的 model 是实际处理请求的服务快照标识,可能与请求名存在版本后缀差异,不影响协议兼容性与计费口径。
余额怎么算的?会过期吗?
按接口返回的 usage 中 prompt_tokens / completion_tokens 实扣,分别乘对应单价。余额永久有效,不清零、不设最低消费。
支持 function calling / JSON mode / 视觉输入吗?
支持。能力随模型档位不同:标注「多模态」「视觉」的模型支持图片输入,全部模型支持 tools 与 response_format。