文档 · LarkAx

简介#

网关对外暴露单一的 https://api.larkax.com/v1 端点，同时兼容 OpenAI、Anthropic 与 Gemini 三种请求格式。任一格式进来，都可以路由到任意已接入的模型。

一个端点全部模型共用同一份凭证与同一个 base_url。

协议互转三种请求与响应格式在网关内自动转换。

自动故障转移上游 429 或 5xx 时切换到同模型的备用渠道。

统一计量按 Key、模型、渠道三个维度统计 token 与费用。

迁移成本：现有 OpenAI SDK 只需要改动 base_url 与 API Key 两处，模型名、消息结构、流式开关均保持不变。

快速开始#

从零到发出第一个请求，通常不超过两分钟。

1

创建 API Key在控制台新建密钥，可同时设定额度上限、可用模型与有效期。

2

指向网关地址把客户端的 base_url 改为 https://api.larkax.com/v1。

3

发起调用切换模型只需修改 model 字段。

curl

bash

curl https://api.larkax.com/v1/chat/completions \
  -H "Authorization: Bearer $LARKAX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5",
    "messages": [{ "role": "user", "content": "你好" }]
  }'

Python

python

from openai import OpenAI

client = OpenAI(
    api_key="sk-larkax-...",
    base_url="https://api.larkax.com/v1",
)

resp = client.chat.completions.create(
    model="claude-sonnet-4",
    messages=[{"role": "user", "content": "你好"}],
)
# 换模型只改 model，其余代码无需调整
print(resp.choices[0].message.content)

Node.js

javascript

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.LARKAX_API_KEY,
  baseURL: "https://api.larkax.com/v1",
});

const resp = await client.chat.completions.create({
  model: "gemini-2.5-pro",
  messages: [{ role: "user", content: "你好" }],
});

认证#

所有请求都需要在 HTTP 头中携带 API Key。网关同时接受两种写法，便于现有客户端直接迁移。

http

# OpenAI 风格
Authorization: Bearer sk-larkax-xxxxxxxxxxxx

# Anthropic 风格（等价）
x-api-key: sk-larkax-xxxxxxxxxxxx

子 Key 支持在创建时附加以下限制，任一条件触发即拒绝请求：

限制项	说明
额度上限	累计消费达到上限后拒绝新请求
模型白名单	仅允许调用列表内的模型
来源 IP	限定调用方出口 IP 或网段
有效期	到期自动失效，可手动吊销

密钥泄露处理：控制台可即时吊销任意 Key。吊销后该 Key 发出的请求立即返回 401，不受缓存影响。

对话补全#

POST /v1/chat/completions 是使用频率最高的接口，兼容 OpenAI 的同名接口。

请求参数

参数	类型	必填	说明
model	string	必填	模型 ID，见模型列表
messages	array	必填	对话消息数组
stream	boolean	可选	是否流式返回，默认 false
temperature	number	可选	采样温度，默认 1
max_tokens	integer	可选	最大生成 token 数
tools	array	可选	可供模型调用的工具定义
tool_choice	string	可选	工具选择策略

响应

json

{
  "id": "chatcmpl-larkax-8f2a",
  "object": "chat.completion",
  "model": "gpt-5",
  "choices": [{
    "index": 0,
    "message": { "role": "assistant", "content": "你好，有什么可以帮忙的？" },
    "finish_reason": "stop"
  }],
  "usage": { "prompt_tokens": 9, "completion_tokens": 12, "total_tokens": 21 }
}

usage 字段：网关优先透传上游返回的 usage。上游未返回时按字符数估算，并在响应头 x-larkax-usage-estimated: true 中标记。

流式输出#

传入 "stream": true 后，响应以 SSE 形式逐块返回，格式与 OpenAI 一致。

sse

data: {"choices":[{"delta":{"role":"assistant"},"index":0}]}

data: {"choices":[{"delta":{"content":"你"},"index":0}]}

data: {"choices":[{"delta":{"content":"好"},"index":0}]}

data: {"choices":[{"delta":{},"finish_reason":"stop"}]}

data: [DONE]

故障切换边界：首个 token 返回之前，上游失败会自动重试到备用渠道。已经开始输出后不做中途切换，而是结束该流并在 usage 与调用日志中记录中断原因。

工具调用#

工具定义使用 OpenAI 的 tools 结构。网关会把它转换成上游模型所需的格式，并把返回的工具调用还原为标准结构。

json

{
  "model": "claude-sonnet-4",
  "messages": [{ "role": "user", "content": "北京现在天气如何" }],
  "tools": [{
    "type": "function",
    "function": {
      "name": "get_weather",
      "description": "查询指定城市的天气",
      "parameters": {
        "type": "object",
        "properties": { "city": { "type": "string" } },
        "required": ["city"]
      }
    }
  }],
  "tool_choice": "auto"
}

流式场景下，工具调用会以 delta.tool_calls 分片返回，需要按 index 拼接后再执行。

向量化#

POST /v1/embeddings 用于文本向量化，当前接入 6 个向量模型。

json

{
  "model": "text-embedding-3-large",
  "input": ["第一段文本", "第二段文本"]
}

批量限制：单次请求最多 2048 条输入，单条最长按模型的最大上下文限制。超出时返回 400。

Anthropic 入口#

POST /v1/messages 接受 Anthropic 原生格式，可直接配合官方 anthropic SDK 使用。目标模型不限于 Anthropic 系列，网关会转换后转发。

python

from anthropic import Anthropic

client = Anthropic(
    api_key="sk-larkax-...",
    base_url="https://api.larkax.com",
)

msg = client.messages.create(
    model="gpt-5",          # 目标模型任意
    max_tokens=1024,
    messages=[{"role": "user", "content": "你好"}],
)

Gemini 入口#

POST /v1beta/models/{model}:generateContent 接受 Gemini 原生格式。函数调用与多模态内容块的字段会双向映射。

bash

curl https://api.larkax.com/v1beta/models/deepseek-v3:generateContent \
  -H "x-goog-api-key: $LARKAX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{ "parts": [{ "text": "你好" }] }]
  }'

格式转换规则#

跨协议调用时，网关按以下方式映射字段。未列出的字段以目标模型支持的范围为准，不支持时返回 400 并指出具体字段。

概念	OpenAI	Anthropic	Gemini
系统提示	messages[0].role=system	system	systemInstruction
用户消息	role=user	role=user	role=user
最大输出	max_tokens	max_tokens	generationConfig.maxOutputTokens
工具定义	tools[].function	tools[].input_schema	tools[].functionDeclarations
结束原因	finish_reason	stop_reason	finishReason

模型列表#

GET /v1/models 返回当前可用的模型目录，字段与 OpenAI 一致。

json

{
  "object": "list",
  "data": [
    { "id": "gpt-5",            "object": "model", "owned_by": "openai" },
    { "id": "claude-sonnet-4",   "object": "model", "owned_by": "anthropic" },
    { "id": "gemini-2.5-pro",    "object": "model", "owned_by": "google" },
    { "id": "deepseek-v3",       "object": "model", "owned_by": "deepseek" }
  ]
}

模型	上下文	输入 / 1M	输出 / 1M	状态
gpt-5	400K	¥0.18	¥1.08	可用
claude-sonnet-4	1M	¥0.21	¥1.05	可用
gemini-2.5-pro	1M	¥0.14	¥0.69	可用
deepseek-v3	128K	¥0.02	¥0.08	可用
qwen3-max	256K	¥0.06	¥0.24	维护中

错误码#

错误响应体沿用 OpenAI 的 error 结构，其中 type 字段可直接用于程序判断。

状态码	type	含义与处理
400	invalid_request_error	参数不合法或目标模型不支持该字段，按返回信息调整
401	authentication_error	密钥无效或已吊销，检查 Authorization 头
402	insufficient_quota	额度用尽，充值或在控制台提升上限
403	permission_error	该 Key 无权调用目标模型，检查模型白名单
429	rate_limit_error	触发限流。网关内部已在渠道间重试，持续返回表示全部渠道受限
500	api_error	网关内部错误，可重试
502	upstream_error	全部候选渠道均失败，响应体含最后一次的上游信息
504	timeout_error	超过配置的超时预算，可提高超时或改用更快的渠道

重试建议：429 与 5xx 适合指数退避重试；4xx 中的其余状态码属于请求本身的问题，重试不会改变结果。

用量与计费#

费用为上游官方价格乘以渠道倍率，按实际 token 用量结算，无月费与最低消费。

维度	说明
按 Key	每个子 Key 的独立消耗与余额
按模型	区分输入与输出 token 的用量
按渠道	用于比对不同上游的实际成本

调用日志保留 usage、命中渠道、延迟与结束原因，可在控制台按时间范围筛选并导出明细对账。

估算标记：上游未返回 usage 时，网关按字符数估算并在明细中标注，此类记录不计入账单争议范围。

LarkAx 接入文档

简介#

快速开始#

curl

Python

Node.js

认证#

对话补全#

请求参数

响应

流式输出#

工具调用#

向量化#

Anthropic 入口#

Gemini 入口#

格式转换规则#

模型列表#

错误码#

用量与计费#