API 文档

简介

MaaS 平台 在众多上游(OpenAI、Anthropic、Gemini、DeepSeek 等)之上提供统一的 OpenAI 兼容 API。无需为每家供应商分别管理密钥与端点:在模型广场任选模型,用统一规范名经同一个 baseURL 调用,请求按优先级、权重与健康度路由并自动故障转移。在用 Anthropic / Gemini SDK?原生格式入口同样内置。

鉴权

在 控制台 → API Keys 创建密钥(仅显示一次,前缀 sk-ra-)。在 Authorization 头以 Bearer 方式携带。一个密钥可用于所有模型与所有入口格式。密钥按账号与用户组隔离;切勿放入前端代码。

Authorization: Bearer sk-ra-your-key

三行接入

把 OpenAI SDK 的 base_url 指向 https://mass.hzxmfg.com/v1、api_key 换成你的密钥 —— 迁移到此为止。然后像调用 OpenAI 一样调用 /v1/chat/completions,换模型只换名字。

curl https://mass.hzxmfg.com/v1/chat/completions \
  -H "Authorization: Bearer sk-ra-..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-v4-pro",
    "messages": [{"role": "user", "content": "Hello"}]
  }'

接入你的工具

多数 AI 工具都支持自定义接入,MaaS 平台 有两种接法:OpenAI 兼容 base URL(适配绝大多数客户端、IDE 与 CLI)或 Anthropic 兼容端点(给 Claude Code 等 Claude 格式 CLI)。同一个 sk-ra- 密钥两种都能用 —— 先填下面的值,再看每个工具的具体设置位置。任何支持自定义 OpenAI / Anthropic 兼容接口的工具都能用,即使未列出。

Base URL   https://mass.hzxmfg.com/v1
API key    sk-ra-...
Model      deepseek-v4-pro   (or any name from the marketplace)

export ANTHROPIC_BASE_URL="https://mass.hzxmfg.com"
export ANTHROPIC_AUTH_TOKEN="sk-ra-..."
# then use a Claude model, e.g. claude-sonnet-4-6

按任务分的端点

MaaS 平台 并非单一端点 —— 能力按任务拆成不同路由,你的同一个 sk-ra- 密钥在所有端点通用。文本(对话)与 embedding 是同步的 OpenAI 兼容调用;图片、视频、语音生成则不同:它们是异步任务 —— 先提交请求,再轮询取结果。文本转语音(TTS)与语音转文本(ASR)各有独立的 OpenAI 风格音频端点。所以:生成图片/视频/语音与对话补全、embedding **不是同一个端点**。下表给出每类任务对应的端点。

对话补全

POST /v1/chat/completions 与 OpenAI 完全一致。传入模型名(统一规范名,路由到能服务它的上游)与 messages 数组。

curl https://mass.hzxmfg.com/v1/chat/completions \
  -H "Authorization: Bearer sk-ra-..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-v4-pro",
    "messages": [{"role": "user", "content": "Hello"}]
  }'

流式

设 stream: true 即可收到 SSE。每个事件是 OpenAI 风格的 delta chunk;流以 data: [DONE] 结束。计费按实际产出 token 结算。

stream = client.chat.completions.create(
    model="deepseek-v4-pro",
    messages=[{"role": "user", "content": "Hello"}],
    stream=True,
)
for chunk in stream:
    print(chunk.choices[0].delta.content or "", end="")

Anthropic / Gemini 原生

已在用 Anthropic 或 Gemini SDK?调用 POST /v1/messages(Anthropic Messages)或 POST /v1beta/models/{model}:generateContent(Gemini),保留现有代码 —— 网关在内部格式间互转并同样计费。

Anthropic · /v1/messages

from anthropic import Anthropic

client = Anthropic(base_url="https://mass.hzxmfg.com", api_key="sk-ra-...")
msg = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=256,
    messages=[{"role": "user", "content": "Hello"}],
)
print(msg.content[0].text)

Gemini · /v1beta

curl "https://mass.hzxmfg.com/v1beta/models/gemini-1.5-pro:generateContent" \
  -H "x-goog-api-key: sk-ra-..." -H "Content-Type: application/json" \
  -d '{"contents":[{"role":"user","parts":[{"text":"Hello"}]}]}'

Embeddings(向量)

POST /v1/embeddings,OpenAI 兼容。传入 model 与 input(字符串或字符串数组),返回 data:[{embedding:[...]}] 及 usage。按输入 token 计费。用于搜索、RAG、聚类 —— 与对话补全是不同的端点。

curl https://mass.hzxmfg.com/v1/embeddings \
  -H "Authorization: Bearer sk-ra-..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "text-embedding-v3",
    "input": ["The quick brown fox", "jumps over the lazy dog"]
  }'

图片 / 视频 / 语音生成

生成类模型是异步任务,流程与对话不同。POST /v1/generations,传 model 与 prompt(以及模态字段:视频的 duration、图片的 size、语音的 text + voice),立即返回 { id, status:"queued" }。轮询 GET /v1/generations/{id}:进行中返回 "processing",随后是终态 —— "succeeded"(读 result_url,我方存储上的永久链接、不会过期),或 "failed" / "timed_out" / "canceled"。进行中的任务可用 POST /v1/generations/{id}/cancel 取消(冻结额度退回)。生成按次计费:每张图 / 每秒视频 / 每字符语音(响应头 X-RouteAll-Usage-Calls)。历史路径 /v1/video/generations 对所有模态仍可用。

# 1) Submit a generation job (image / video / audio model)
curl https://mass.hzxmfg.com/v1/generations \
  -H "Authorization: Bearer sk-ra-..." -H "Content-Type: application/json" \
  -d '{"model": "viduq2", "prompt": "A paper boat drifting down a stream", "duration": 4}'
# -> {"id": "1234", "status": "queued"}

# 2) Poll until done, then read the permanent result_url
curl https://mass.hzxmfg.com/v1/generations/1234 -H "Authorization: Bearer sk-ra-..."
# -> {"id":"1234","status":"succeeded","result_url":"https://.../v.mp4","charge":"225000"}

语音合成与转写

音频有专属的 OpenAI 风格端点。文本转语音:POST /v1/audio/speech,传 model、input 文本与 voice,返回音频字节(wav 或 mp3)—— 具备音频能力的模型也接受 OpenAI omni-audio 形态(经 /v1/chat/completions)。语音转文本:POST /v1/audio/transcriptions,以 multipart/form-data 传 file 与 model,返回 { text }。TTS 按字符计费,ASR 按 token 计费。

Text-to-speech · /v1/audio/speech

curl https://mass.hzxmfg.com/v1/audio/speech \
  -H "Authorization: Bearer sk-ra-..." -H "Content-Type: application/json" \
  -d '{"model": "qwen3-tts-flash", "input": "Hello from MaaS 平台", "voice": "Cherry", "response_format": "mp3"}' \
  --output speech.mp3

Speech-to-text · /v1/audio/transcriptions

curl https://mass.hzxmfg.com/v1/audio/transcriptions \
  -H "Authorization: Bearer sk-ra-..." \
  -F file=@audio.mp3 \
  -F model=qwen3-asr-flash
# -> {"text": "transcribed text ..."}

参数

常用参数:temperature(0–2)、top_p(0–1)、max_tokens、stop。不同模型支持不同 —— 推理模型可能忽略 temperature,视觉模型接受图片 part。未知参数在安全前提下透传上游。

计价:按 token、缓存与按次

多数模型按 token 计费。命中缓存输入 token 时按缓存读价计(缓存创建按缓存写价),响应头 X-RouteAll-Usage-Cached-Tokens 回命中数。推理模型产生的 thinking token 按该模型的 reasoning 价计(未配置则按 output 价),账单页回 reasoningTokens。部分模型还按次计费:图片生成按张收费(POST /v1/images/generations,响应头 X-RouteAll-Usage-Calls),web_search 类工具在 token 之上按每次搜索加费。你的价格 = 官方价 × 你的用户组倍率;绝不暴露成本。

X-RouteAll-Usage-Prompt: 972
X-RouteAll-Usage-Cached-Tokens: 896
X-RouteAll-Charge-Credit: 74

错误

错误用 OpenAI 信封:{ "error": { "type", "message", "code" } }。401=密钥无效/缺失,402=余额不足,429=超限,503=无可用渠道。可重试的上游错误会静默故障转移。

{ "error": { "type": "insufficient_balance", "message": "Insufficient balance", "code": 402 } }

限流

按 API Key 限速(每分钟请求数)。超限返回 429(OpenAI 风格)。请合理控制并发并在 429 时退避。