API 接入文档

兼容 OpenAI 接口规范,把 base_url 换掉即可,SDK 代码不用改。

v1稳定版
Base URL https://api.lanyuapi.live/v1

概览

蓝隅中转站提供与 OpenAI 一致的 HTTP 接口。你只需要把 SDK 里的 base_url 指向本站,其余参数、返回结构、流式协议都保持原样。

方法路径说明
POST/v1/chat/completions对话补全,支持流式与非流式
GET/v1/models当前可用模型与价格
所有请求必须是 application/json,字符集 UTF-8;时间戳为 Unix 秒。

认证

在控制台「我的密钥」里创建密钥,然后在请求头中携带。密钥只在创建时完整显示一次。

Authorization: Bearer sk-live-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

未携带或密钥无效时返回 401 invalid_api_key。密钥可以单独设置日额度、IP 白名单与过期时间。

模型列表

GET https://api.lanyuapi.live/v1/models Authorization: Bearer $NEXUS_API_KEY

返回每个模型的对外名称、上下文长度与单价(元 / 百万 token):

{ "object": "list", "data": [ { "id": "deepseek-v4.1-flash", "object": "model", "created": 1794879119, "owned_by": "nexus", "context_length": 128000, "pricing": { "currency": "CNY", "unit": "1M_tokens", "input": "0.300000", "output": "1.200000" } } ] }

调用时 model 填这里的 id 即可;填上游原始模型名(如 nvidia/...)也能识别。

对话补全

POST https://api.lanyuapi.live/v1/chat/completions Content-Type: application/json Authorization: Bearer $NEXUS_API_KEY { "model": "deepseek-v4.1-flash", "messages": [ {"role": "system", "content": "你是一个严谨的中文助手。"}, {"role": "user", "content": "用一句话解释什么是向量数据库。"} ], "temperature": 0.7, "max_tokens": 512, "stream": false }

请求参数

参数类型说明
modelstring必填,模型 ID 或别名
messagesarray必填,role 支持 system / user / assistant;content 可以是字符串,也可以是文本+图片数组
temperaturenumber0–2,默认 1,越大越发散
top_pnumber0–1,与 temperature 二选一调整
max_tokensinteger最大输出长度,受模型上限限制
streambooleantrue 时以 SSE 逐块返回
stream_optionsobject支持 {"include_usage": true},在末尾补一帧用量
stopstring / array遇到这些字符串停止生成
presence_penaltynumber-2 到 2
frequency_penaltynumber-2 到 2
userstring终端用户标识,用于日志排查

响应

{ "id": "chatcmpl-8f2c1f0e", "object": "chat.completion", "created": 1794879200, "model": "deepseek-v4.1-flash", "choices": [ { "index": 0, "message": {"role": "assistant", "content": "向量数据库是……"}, "finish_reason": "stop" } ], "usage": {"prompt_tokens": 32, "completion_tokens": 96, "total_tokens": 128} }

推理类模型还会在 message.reasoning_content 里返回思考过程,不使用时可忽略。

流式响应

设置 "stream": true 后,服务端以 text/event-stream 返回,每个事件是一行 data:,最后以 data: [DONE] 结束。

data: {"id":"chatcmpl-8f2c1f0e","choices":[{"index":0,"delta":{"role":"assistant","content":"向"}}]} data: {"id":"chatcmpl-8f2c1f0e","choices":[{"index":0,"delta":{"content":"量"}}]} data: {"id":"chatcmpl-8f2c1f0e","choices":[{"index":0,"delta":{"content":"数据"}}]} data: [DONE]

处理建议:

  • 按行读取,只处理以 data: 开头的行,忽略空行与注释行。
  • 客户端断开连接时,服务端会中止上游请求;已经产生的 token 仍会计费。
  • 不要假设首个 chunk 就带内容,有些模型首帧只有 role。

错误码

错误统一使用下面的结构,code 是稳定值,适合在代码里判断;message 是给人看的说明。

{ "error": { "message": "今日额度已用完,明日 0 点恢复", "type": "insufficient_quota", "param": null, "code": "daily_quota_exceeded" } }
状态码code含义与处理
400invalid_request参数缺失或格式错误,检查请求体
401invalid_api_key密钥无效、被停用或已过期
402insufficient_quota余额不足,去控制台充值或兑换
402daily_quota_exceeded今日金额额度用完,次日 0 点恢复
402daily_requests_exceeded今日请求次数用完
403model_not_allowed当前账号无权使用该模型
403ip_not_allowed来源 IP 不在密钥白名单内
404model_not_found模型不存在或未上架
429rate_limit_exceeded触发 RPM / TPM / 并发限制,退避后重试
502upstream_error上游返回异常,message 里带上游原文
503no_available_account上游账号全在冷却,30 秒后重试
504upstream_timeout上游超时,建议降低 max_tokens 或重试

限流与计费

  • RPM:每分钟请求数;TPM:每分钟 token 数;并发:同时在跑的请求数。
  • 额度按天计算:金额额度与请求次数都在每天 0 点重置。
  • 计费公式:(输入 token × 输入单价 + 输出 token × 输出单价) ÷ 1,000,000,单位人民币。
  • token 由上游返回的 usage 决定;上游没给时按本地估算,日志里会标注来源。
  • 命中请求缓存时不扣费。

响应头

响应头说明
X-Request-Id本次请求 ID,排查问题时提供它
X-Model实际使用的上游模型
X-Cost-Cny本次费用(元)
X-Token-Sourceupstream 或 estimated
X-RateLimit-Remaining-Requests本分钟剩余请求数
X-Cache命中缓存时为 hit

客户端示例

Python(openai SDK)

from openai import OpenAI client = OpenAI( base_url="https://api.lanyuapi.live/v1", api_key="sk-live-xxxxxxxx", ) stream = client.chat.completions.create( model="deepseek-v4.1-flash", messages=[{"role": "user", "content": "你好"}], stream=True, ) for chunk in stream: delta = chunk.choices[0].delta.content if delta: print(delta, end="", flush=True)

Node.js

import OpenAI from 'openai'; const client = new OpenAI({ baseURL: 'https://api.lanyuapi.live/v1', apiKey: process.env.NEXUS_API_KEY, }); const res = await client.chat.completions.create({ model: 'deepseek-v4.1-flash', messages: [{ role: 'user', content: '你好' }], }); console.log(res.choices[0].message.content);

cURL

curl https://api.lanyuapi.live/v1/chat/completions \ -H "Authorization: Bearer $NEXUS_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "deepseek-v4.1-flash", "messages": [{"role": "user", "content": "你好"}] }'

常见问题

为什么偶尔返回 502?

说明上游这次调用失败了,message 里会带上游的原始报错。客户端按指数退避重试 1–2 次即可;连续多次失败请把 X-Request-Id 发给我们。

429 之后该等多久?

看响应头 Retry-After;没有就按 2s、4s、8s 退避。并发限制是按人算的,多个进程共用一个密钥时尤其容易触发。

模型名用哪个?

以 GET /v1/models 返回的 id 为准。别名和上游全名都支持,但别名更稳定——上游改版本时我们可以平滑切换。

怎么核对费用?

两个地方:响应头 X-Cost-Cny 是单次费用;控制台「用量」页可以按天看汇总,并导出 CSV。

还有问题?把请求 ID、模型名、发生时间和错误响应贴给管理员,能最快定位。