API123 .store · 大模型中转站

1. 接口概述

FA API 同时兼容 OpenAI Chat Completions 与 Anthropic Messages 两套协议，一次接入即可调用模型广场中的全部模型。所有请求经由中转站网关转发，无需自行管理各厂商的 API Key 与地址差异。

# 网关地址（应用发布域名下；OpenAI 与 Anthropic 共用同一主机）
POST https://api123.store/v1/chat/completions
Content-Type: application/json
x-fa-key: sk-mh-你的完整密钥

{
  "model": "<模型 ID，见模型广场>",
  "messages": [
    { "role": "system", "content": "You are a helpful assistant." },
    { "role": "user", "content": "你好" }
  ],
  "stream": true
}

ⓘ 接口支持 stream: true（SSE 流式透传）与 false（服务端聚合为完整 JSON）。消息无需 system 开头——缺失时网关会自动补一条中性 system，标准 OpenAI 客户端的默认用法可直接跑通。调用必须携带 sk-mh- 密钥（x-fa-key / Authorization / x-api-key 任一，线上建议 x-fa-key），网关据此完成鉴权、扣费与用量统计。

2. 公开 API · 程序化调用（M10）

除网页调试外，FA API 提供 OpenAI 兼容公开接口：任意程序、脚本或第三方工具，使用你的 sk-mh- 密钥即可调用。服务端强制扣费与限流（每密钥 60 次/分钟，可在后台为密钥设置总量/月度配额）；密钥支持启停与过期时间。

# 网关地址（与站点同域）
POST https://api123.store/v1/chat/completions
x-fa-key: sk-mh-你的完整密钥        # 线上请用 x-fa-key（原因见下方说明）
Content-Type: application/json

{
  "model": "auto",
  "messages": [
    { "role": "system", "content": "You are a helpful assistant." },
    { "role": "user", "content": "你好" }
  ],
  "stream": true          # true = SSE 流式透传；false 或省略 = 返回完整 JSON（服务端聚合）
}

# 查看可用模型（OpenAI 兼容格式）
GET https://api123.store/v1/models

ⓘ 与 OpenAI SDK 搭配：将 base_url 设为本地址、api_key 设为 sk-mh- 密钥即可。密钥在「API 密钥」页创建（仅创建时展示一次）。调用按模型分档扣积分，流水与月度账单在「我的钱包」可查。API 路由已开放跨域（CORS），浏览器端亦可直连。

⚠️ 关于鉴权头：本站所在平台的反向代理会重写客户端的 Authorization 头、并剥离 x-api-key（平台级行为，应用侧无法改变）。因此线上请使用自定义头 x-fa-key，或采用下一节介绍的「密钥内嵌路径」方式。本地/自建部署不受此限制，Authorization: Bearer 与 x-api-key 均可正常使用。

3. Anthropic 兼容 · Claude Code / Cursor / Cline 直连（M48）

网关原生实现 Anthropic Messages 协议（含流式事件流 message_start → content_block_delta → message_stop）。只认 Anthropic 协议的工具无需任何转换层即可接上本站。因平台边缘层会重写 / 剥离常规鉴权头（见上一节说明），线上请用下列两种方式之一：

# 方式一（推荐）：自定义头 x-fa-key —— 平台唯一原样透传的鉴权头
export ANTHROPIC_BASE_URL="https://api123.store"
export ANTHROPIC_CUSTOM_HEADERS="x-fa-key: sk-mh-你的完整密钥"
export ANTHROPIC_MODEL="<模型 ID，见模型广场>"

# 方式二：密钥内嵌进 baseURL 路径 —— 适用于无法自定义请求头的 SDK / 工具
export ANTHROPIC_BASE_URL="https://api123.store/k/sk-mh-你的完整密钥"
export ANTHROPIC_AUTH_TOKEN="placeholder"     # 任意非空占位；真实凭据已在路径中

# 端到端协议
POST https://api123.store/v1/messages
x-fa-key: sk-mh-你的完整密钥
anthropic-version: 2023-06-01

{
  "model": "auto",
  "max_tokens": 1024,
  "system": "You are a helpful assistant.",
  "messages": [{ "role": "user", "content": "你好" }],
  "stream": true
}

# 令牌预估（Claude Code 上下文压缩决策会调用）
POST https://api123.store/v1/messages/count_tokens

ⓘ 支持文本 / 图片 / tool_use / tool_result 全量内容块与 tools、tool_choice、stop_sequences；max_tokens 省略时默认 4096（官方为必填，此处放宽以免打断客户端）。路径方式下密钥会出现在 URL 中，请避免在共享日志/截图里泄露；路径内密钥同样参与白名单与配额校验，不会放宽权限。

4. 模型自动降级（M48）

主模型不可用时，网关会按候选链自动切换到下一个可用模型，并在响应中回传实际服务的模型；只对真正跑起来的模型计费，失败尝试不扣积分。该能力对标 OpenRouter 的 fallback 路由。

# OpenAI 协议：models 数组按优先级依次尝试
{ "model": "<首选模型>", "models": ["<备用模型 1>", "<备用模型 2>"], "messages": [...] }

# Anthropic 协议：fallbacks 数组（最多 3 条）
{ "model": "<首选模型>", "fallbacks": [{ "model": "<备用模型>" }], "messages": [...] }

ⓘ 降级候选同样受密钥的模型白名单约束（受限密钥无法借降级链调用未授权模型）；每次失败尝试都会写入可靠性指标，可在模型广场的实时状态与管理后台的「模型健康看板」看到成功率变化。

5. 调用示例（JavaScript）

// 使用中转站 SDK
const cloud = WorkBuddyCloud.createWorkBuddyCloud({
  endpoint: 'https://api123.store',
  publishableKey: 'wbpk_H2zD2ouL0iJQR1rEj5gAvF_oYvKVWcuAU2hIw8aCa32zM4RWQX7jER8',
});

const models = await cloud.llm.models.list();   // 拉取模型列表

for await (const chunk of cloud.llm.chat.completions.create({
  model: 'glm-4.6',
  messages: [{ role: 'system', content: 'You are a helpful assistant.' },
              { role: 'user', content: '用一句话介绍你自己' }],
  stream: true,
  stream_options: { include_usage: true },
})) {
  process.stdout.write(chunk.choices[0]?.delta?.content ?? '');
}

6. 能力说明

· 多模型聚合：模型广场实时展示全部可用模型及上下文长度、多模态、推理能力等元信息。

· 统一用量：每次调用返回 usage（prompt / completion / total tokens），可在「用量统计」查看明细。

· 密钥管理：密钥采用 SHA-256 哈希加密存储，完整密钥仅创建时展示一次。

· 积分计费：按模型分档计价（站长在后台为各模型设定单价），未定价模型按 1 积分 / 1000 tokens；余额可在「我的钱包」查看并附月度账单，充值码兑换充值，流水可追溯。

· 多模态：在线调试支持附加图片（需选择支持多模态的模型），实现图片理解对话。

· 智能体：支持单 Agent 与多角色协作两种模式，任务进度落库、中断可恢复、可定时重跑。

· 安全：客户端限流（每分钟 30 次）、数据一键备份导出、暗色模式。

7. 错误码与重试策略（M48）

网关按语义透传状态码，请据此决定是否重试 —— 把「参数写错」当临时故障重试只会持续消耗配额。

# OpenAI 协议错误信封
{ "error": { "message": "...", "type": "invalid_request_error", "code": "invalid_max_tokens", "param": null } }

# Anthropic 协议错误信封（字段更少，无 code / param）
{ "type": "error", "error": { "type": "invalid_request_error", "message": "..." } }

# 状态码语义
400  请求本身有问题（messages 为空 / max_tokens 非正整数 / 参数越界 / 上游拒绝该请求）→ 不要重试，改参数
401  密钥无效、已停用或已删除                                  → 不要重试，换密钥
402  积分余额不足 / 本月预算已用尽                              → 不要重试，充值或调高预算
403  该密钥未授权使用此模型（模型白名单）                        → 不要重试，换模型或调整白名单
404  模型不存在                                                → 不要重试，核对模型 ID
413  请求体超过 2MB 上限                                       → 不要重试，裁剪上下文
429  超出速率 / 配额上限（含上游限流）                          → 可重试，指数退避
503  上游模型通道暂时不可用（所有降级候选均失败）                → 可重试，指数退避
503  本站数据面暂不可用（code=data_plane_*，与你的密钥无关）      → 可重试，稍后再试

ⓘ 参数校验：max_tokens 须为不小于 1 的整数（省略时默认 4096）、temperature 取值 0 ~ 2、top_p 取值 0 ~ 1；越界会返回 400 而不是被静默忽略。ⓘ 模型降级：主模型不可用时网关自动切换候选模型，因此 503 只在全部候选都失败时才会出现。