AB
AB
AiBoss

すべてのカテゴリ

チュートリアル

ZenMux

チュートリアル

用 ZenMux 统一接入四套 API 协议并查询用量

ZenMux 把多家模型供应商收进同一个端点，并同时兼容 OpenAI Chat Completions、OpenAI Responses、Anthropic Messages 与 Google Gemini 四套协议。本文从注册、选计费方式、创建密钥讲起，给出四种协议的完整调用代码，再用 Management API 查询单次调用明细、PAYG 余额、订阅配额与 Flow 汇率。

ZenMux 解决的是一个很具体的问题：当项目里同时要用 OpenAI、Anthropic、Google 等不同供应商的模型时，通常要维护多套 SDK、多个密钥、多份计费账单。ZenMux 把这些模型收拢到同一个平台，对外暴露四个兼容主流协议的端点，于是你可以继续用熟悉的 SDK，只改 base_url 和 api_key 两个参数就完成切换。它同时提供一组 Platform Management API，用来以编程方式查询单次调用明细、账户余额、订阅配额和 Flow 汇率，方便接进自己的监控与成本系统。如果你正在做多模型路由、成本核算或需要把调用日志纳入自有可观测体系，这套接口值得了解。站内也有对应的工具页可以一并参考：ZenMux。

下面按「准备 → 选计费方式 → 取模型 Slug → 四种协议调用 → 管理接口 → 完整示例 → 注意事项」的顺序展开。文中出现的价格、配额、模型名称等易变信息，请以官网当前页面为准。

准备工作

账号与登录方式

ZenMux 支持三种登录入口：邮箱登录、GitHub 账号登录、Google 账号登录。三者进入的是同一套账户体系，登录后看到的控制台一致。选择哪种取决于你团队已有的身份管理习惯，没有功能差异。

确定计费方式

登录之后第一件事不是拿密钥，而是决定用哪种计费方式，因为两种方式的密钥创建入口和调用限制完全不同。

对比维度Pay As You Go（按量付费）Builder Plan（订阅制）
适用场景生产环境、商业化产品、高并发应用个人开发、学习探索、快速原型
计费方式预充值 + 按实际消耗扣费，按 Token 精确计费固定月费，$20/月起
Rate Limit无限制10–15 RPM
并发限制无限制有 Weekly Limit
使用限制无特殊限制禁止用于生产环境

这里有一条硬性边界需要记住：项目已经上线或即将商业化，必须使用 Pay As You Go。订阅制只面向个人开发与学习场景，明确禁止用于生产环境。如果你的服务要对真实用户负责，不要为了省钱把线上流量压到订阅套餐上。

Pay As You Go 的流程是：进入对应的管理页面，先充值，再创建 API Key。Builder Plan 的流程是：进入定价页面选择套餐并订阅，然后在订阅管理页面创建密钥。两种方式的具体套餐档位、月费金额、Flow 换算比例都会调整，下单前请以官网定价页当前展示为准。

创建 API Key

普通调用用的 API Key 在所选计费方式对应的管理页面创建。如果你还要调用 Platform Management API 查询用量与余额，需要额外创建一个 Management API Key，入口在控制台的 Management 页面。两者用途不同：普通 Key 用于模型调用，Management Key 用于账户与用量查询，部分管理接口也接受普通 Key，但涉及余额、订阅这类账户级信息时应当使用 Management Key。

密钥只在创建时完整展示一次，请立即写入环境变量或密钥管理服务，不要硬编码进源码。本文示例统一用环境变量 ZENMUX_API_KEY 与 ZENMUX_MANAGEMENT_API_KEY 引用。

获取模型 Slug

ZenMux 上每个模型都有唯一 Slug，调用时 model 字段填的就是它。获取途径有两个：模型列表页可以浏览全部可用模型及其 Slug；某个模型的详情页也能看到该模型的 Slug。Slug 的常见形态是「供应商/模型名称」，例如 openai/gpt-5、google/gemini-3.1-pro-preview。模型上下架频繁，写代码前先去列表页确认当前可用的 Slug，不要凭记忆填。

安装 SDK

ZenMux 不要求安装专有 SDK，直接用各协议官方 SDK 即可。按你选用的协议安装对应包：

# OpenAI 协议（Chat Completions 与 Responses 共用）
pip install openai
npm install openai

# Anthropic 协议
pip install anthropic
npm install @anthropic-ai/sdk

# Google Gemini 协议
pip install google-genai
npm install @google/genai

操作步骤

第一步：认清四个端点

ZenMux 的四个协议对应四个 Base URL，其中 OpenAI 的两个协议共用一个地址。这是最容易出错的地方，务必对照下表填写。

协议Base URL兼容 SDK说明
OpenAI Chat Completionshttps://zenmux.ai/api/v1OpenAI SDK最广泛使用的 Chat API
OpenAI Responseshttps://zenmux.ai/api/v1OpenAI SDKOpenAI 新一代 Responses API
Anthropic Messageshttps://zenmux.ai/api/anthropicAnthropic SDKClaude 系列原生协议
Google Geminihttps://zenmux.ai/api/vertex-aiGoogle GenAI SDKGemini 系列原生协议

ZenMux 的核心特性是协议无关：你可以用任意一个受支持的协议去调用任意一个模型。用 OpenAI SDK 调 Claude 模型、用 Anthropic SDK 调 Gemini 模型都是允许的。这意味着迁移时不必重写业务代码，只要换端点。

第二步：用 OpenAI Chat Completions 发起第一个请求

这个端点与 OpenAI Chat Completions API 完全兼容，只需修改 base_url 和 api_key。Python 版本：

from openai import OpenAI

client = OpenAI(
    base_url="https://zenmux.ai/api/v1",
    api_key="<你的 ZENMUX_API_KEY>",
)

completion = client.chat.completions.create(
    model="openai/gpt-5",
    messages=[
        {"role": "user", "content": "生命的意义是什么？"}
    ]
)

print(completion.choices[0].message.content)

TypeScript 版本：

import OpenAI from "openai";

const openai = new OpenAI({
  baseURL: "https://zenmux.ai/api/v1",
  apiKey: "<你的 ZENMUX_API_KEY>",
});

async function main() {
  const completion = await openai.chat.completions.create({
    model: "openai/gpt-5",
    messages: [
      { role: "user", content: "生命的意义是什么？" },
    ],
  });
  console.log(completion.choices[0].message.content);
}

main();

不想装 SDK 时用 cURL 验证连通性：

curl https://zenmux.ai/api/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ZENMUX_API_KEY" \
  -d '{
    "model": "openai/gpt-5",
    "messages": [
      { "role": "user", "content": "生命的意义是什么？" }
    ]
  }'

第三步：改用 OpenAI Responses 协议

Responses 是 OpenAI 新一代接口，Base URL 与 Chat Completions 相同，调用方式更简洁：输入用 input，输出取 output_text。

from openai import OpenAI

client = OpenAI(
    base_url="https://zenmux.ai/api/v1",
    api_key="<你的 ZENMUX_API_KEY>",
)

response = client.responses.create(
    model="openai/gpt-5",
    input="生命的意义是什么？"
)

print(response.output_text)

TypeScript 版本：

import OpenAI from "openai";

const openai = new OpenAI({
  baseURL: "https://zenmux.ai/api/v1",
  apiKey: "<你的 ZENMUX_API_KEY>",
});

async function main() {
  const response = await openai.responses.create({
    model: "openai/gpt-5",
    input: "生命的意义是什么？",
  });
  console.log(response.output_text);
}

main();

cURL 版本注意路径是 /responses 而不是 /chat/completions：

curl https://zenmux.ai/api/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ZENMUX_API_KEY" \
  -d '{
    "model": "openai/gpt-5",
    "input": "生命的意义是什么？"
  }'

第四步：用 Anthropic Messages 协议调用

Anthropic 协议的 Base URL 是 https://zenmux.ai/api/anthropic，与 OpenAI 协议不同，不要混用。这个协议可以无缝集成到 Claude Code、Cursor 等工具中，是让这些工具走 ZenMux 的关键。

from anthropic import Anthropic

client = Anthropic(
    base_url="https://zenmux.ai/api/anthropic",
    api_key="<你的 ZENMUX_API_KEY>",
)

message = client.messages.create(
    model="google/gemini-3.1-pro-preview",
    max_tokens=1024,
    messages=[
        {"role": "user", "content": "生命的意义是什么？"}
    ]
)

print(message.content[0].text)

TypeScript 版本：

import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic({
  baseURL: "https://zenmux.ai/api/anthropic",
  apiKey: "<你的 ZENMUX_API_KEY>",
});

async function main() {
  const message = await client.messages.create({
    model: "google/gemini-3.1-pro-preview",
    max_tokens: 1024,
    messages: [
      { role: "user", content: "生命的意义是什么？" },
    ],
  });
  console.log(message.content[0].text);
}

main();

cURL 调用时注意两点：路径是 /api/anthropic/v1/messages，鉴权头用 x-api-key 而不是 Authorization，并且必须带 anthropic-version。

curl https://zenmux.ai/api/anthropic/v1/messages \
  -H "content-type: application/json" \
  -H "x-api-key: $ZENMUX_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "google/gemini-3.1-pro-preview",
    "max_tokens": 1024,
    "messages": [
      { "role": "user", "content": "生命的意义是什么？" }
    ]
  }'

第五步：用 Google Gemini 协议调用

Gemini 协议走 Vertex AI 兼容路径，Base URL 是 https://zenmux.ai/api/vertex-ai。初始化客户端时必须显式设置 vertexai=True，并通过 http_options 指定 api_version 为 v1 和自定义 base_url，否则 SDK 会指向 Google 官方端点。

from google import genai
from google.genai import types

client = genai.Client(
    api_key="<你的 ZENMUX_API_KEY>",
    vertexai=True,
    http_options=types.HttpOptions(
        api_version='v1',
        base_url='https://zenmux.ai/api/vertex-ai'
    )
)

response = client.models.generate_content(
    model="google/gemini-3.1-pro-preview",
    contents="生命的意义是什么？"
)

print(response.text)

TypeScript 版本：

import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({
  apiKey: "<你的 ZENMUX_API_KEY>",
  vertexai: true,
  httpOptions: {
    apiVersion: "v1",
    baseUrl: "https://zenmux.ai/api/vertex-ai",
  },
});

async function main() {
  const response = await ai.models.generateContent({
    model: "google/gemini-3.1-pro-preview",
    contents: "生命的意义是什么？",
  });
  console.log(response.text);
}

main();

第六步：查询单次调用明细

每次 API 调用都会返回一个 generation_id。用这个 ID 调 Management API，可以拿到该次调用的 Token 用量、耗时、计费明细，适合做逐条对账或排查异常请求。

GET https://zenmux.ai/api/v1/management/generation?id=<generation_id>
curl https://zenmux.ai/api/v1/management/generation?id=gen_01abc123def456 \
  -H "Authorization: Bearer $ZENMUX_API_KEY"

返回结构包含这些字段：api 表示调用的是哪个接口（如 chat.completions）；generationId 是本次调用 ID；model 是实际使用的模型 Slug；generationTime 是生成耗时；latency 是延迟；nativeTokens 内含 prompt_tokens、completion_tokens、total_tokens；usage 是本次计费金额。示例返回：

{
  "api": "chat.completions",
  "generationId": "gen_01abc123def456",
  "model": "openai/gpt-4o",
  "generationTime": 3200,
  "latency": 500,
  "nativeTokens": {
    "completion_tokens": 128,
    "prompt_tokens": 32,
    "total_tokens": 160
  },
  "usage": 0.0052
}

这里有一个必须知道的时序差异：Token 计量信息随请求同步返回，但计费信息（usage、ratingResponses 等）要等请求完成后 3–5 分钟才能查到。如果你在请求刚结束时立刻查 usage，很可能拿到空值或旧值，对账脚本要留出这段延迟窗口。

第七步：查询 PAYG 余额

按量付费账户可以用这个接口查余额，返回总额、充值额与赠送额三部分：

GET https://zenmux.ai/api/v1/management/payg/balance
curl https://zenmux.ai/api/v1/management/payg/balance \
  -H "Authorization: Bearer $ZENMUX_MANAGEMENT_API_KEY"
{
  "success": true,
  "data": {
    "currency": "usd",
    "total_credits": 482.74,
    "top_up_credits": 35.0,
    "bonus_credits": 447.74
  }
}

total_credits 是可用总额，top_up_credits 是你自己充值的部分，bonus_credits 是赠送部分。做余额告警时建议以 total_credits 为准，同时留意赠送额度的有效期规则。

第八步：查询订阅详情与配额

订阅制账户用这个接口查套餐等级、账户状态和两个时间窗口的配额用量：

GET https://zenmux.ai/api/v1/management/subscription/detail
curl https://zenmux.ai/api/v1/management/subscription/detail \
  -H "Authorization: Bearer $ZENMUX_MANAGEMENT_API_KEY"
{
  "success": true,
  "data": {
    "plan": {
      "tier": "ultra",
      "amount_usd": 200,
      "interval": "month"
    },
    "account_status": "healthy",
    "quota_5_hour": {
      "max_flows": 800,
      "used_flows": 57.2,
      "remaining_flows": 742.8,
      "usage_percentage": 0.0715,
      "remaining_resets": 1
    },
    "quota_7_day": {
      "max_flows": 6182,
      "used_flows": 416.11,
      "remaining_flows": 5765.89
    }
  }
}

字段含义：plan.tier 是套餐档位，plan.amount_usd 是月费金额，plan.interval 是计费周期；account_status 是账户健康状态；quota_5_hour 是 5 小时窗口的配额，含上限 max_flows、已用 used_flows、剩余 remaining_flows、使用比例 usage_percentage 和剩余重置次数 remaining_resets；quota_7_day 是 7 天窗口的配额，字段结构相同。两个窗口同时生效，任一触顶都会受限，所以监控脚本要同时看两边。

第九步：查询 Flow 汇率

订阅制的用量以 Flow 为单位计量，这个接口返回 Flow 与美元的换算关系：

GET https://zenmux.ai/api/v1/management/flow_rate
curl https://zenmux.ai/api/v1/management/flow_rate \
  -H "Authorization: Bearer $ZENMUX_MANAGEMENT_API_KEY"
{
  "success": true,
  "data": {
    "currency": "usd",
    "base_usd_per_flow": 0.03283,
    "effective_usd_per_flow": 0.03283
  }
}

base_usd_per_flow 是基础汇率，effective_usd_per_flow 是当前实际生效汇率。两者可能因活动或套餐差异而不同，做成本折算时应当用 effective_usd_per_flow。汇率会变动，不要把它写死进代码，每次核算前现查。

一个完整示例

下面把前面的步骤串成一个可运行的最小流程：用 OpenAI 协议发起一次调用，拿到 generation_id，等待计费信息落库后查询明细，最后查一次余额。假设环境变量 ZENMUX_API_KEY 与 ZENMUX_MANAGEMENT_API_KEY 已配置好。

import os
import time
import requests
from openai import OpenAI

API_KEY = os.environ["ZENMUX_API_KEY"]
MGMT_KEY = os.environ["ZENMUX_MANAGEMENT_API_KEY"]

# 1. 发起调用
client = OpenAI(
    base_url="https://zenmux.ai/api/v1",
    api_key=API_KEY,
)

completion = client.chat.completions.create(
    model="openai/gpt-5",
    messages=[{"role": "user", "content": "用一句话解释什么是协议无关的模型网关。"}],
)
print(completion.choices[0].message.content)

# 2. 从响应中取出 generation_id（字段名以实际返回为准）
gen_id = getattr(completion, "generation_id", None)
print("generation_id:", gen_id)

# 3. 计费信息有 3-5 分钟延迟，先等一会儿
if gen_id:
    time.sleep(300)
    detail = requests.get(
        "https://zenmux.ai/api/v1/management/generation",
        params={"id": gen_id},
        headers={"Authorization": f"Bearer {API_KEY}"},
        timeout=30,
    )
    print(detail.json())

# 4. 查一次 PAYG 余额
balance = requests.get(
    "https://zenmux.ai/api/v1/management/payg/balance",
    headers={"Authorization": f"Bearer {MGMT_KEY}"},
    timeout=30,
)
print(balance.json())

这个脚本覆盖了日常最常用的三件事：调模型、对单次调用对账、看账户余额。把它改成定时任务，就能得到一条最简的用量监控链路。如果用的是订阅制，把第 4 步换成 /management/subscription/detail，并额外读一次 /management/flow_rate 把 Flow 折算成美元。

注意事项

端点与鉴权头不要混用

四个协议的 Base URL 各不相同，Anthropic 与 Gemini 的地址和 OpenAI 完全不在一个路径下。Anthropic 协议用 x-api-key 头，OpenAI 与 Gemini 用 Authorization: Bearer。混用会直接返回鉴权失败，而不是模型不存在，排查时容易误判。

Gemini 协议必须显式声明 vertexai

Google GenAI SDK 默认指向 Google 官方端点。只填 api_key 而不设 vertexai=True 与 http_options.base_url，请求会发到 Google 而不是 ZenMux，表现为密钥无效或模型不存在。这是接入 Gemini 协议最常见的失败原因。

计费信息有 3–5 分钟延迟

Token 计量随请求同步返回，但 usage、ratingResponses 这类计费字段要等请求完成后 3–5 分钟才可查询。对账任务不要设计成请求结束立即校验，否则会大量出现空值。建议把对账窗口设在请求后 5 分钟以上。

订阅制的配额是双窗口

订阅账户同时受 5 小时窗口和 7 天窗口约束，任一窗口触顶都会影响调用。监控时两个窗口都要看，只看其中一个会漏掉另一条限制。此外订阅制有 10–15 RPM 的速率限制和 Weekly Limit，不适合高并发场景。

订阅制禁止用于生产环境

这是平台明确写出的使用限制。个人开发、学习探索、快速原型可以用订阅制；项目上线或商业化必须切到 Pay As You Go。用订阅额度承载线上流量属于违规使用，可能导致账户受限。

模型 Slug 会变

模型上下架频繁，Slug 也可能调整。不要把 Slug 硬编码在多个位置，集中到配置文件中管理，并在启动时做一次可用性校验。上线前到模型列表页确认当前 Slug。

价格与配额以官网为准

本文提到的月费起点、RPM 区间、Flow 汇率、配额上限等数字都会随套餐调整而变化。实际采购与容量规划请以官网定价页和控制台当前展示为准，不要以本文数字做预算依据。

戻る