# GateMux

> 一份余额，跨厂商通用：一把 key 调用中国 SOTA（对话 / 图像 / 视频 / 语音），兼容 fal 队列协议与 OpenAI / Anthropic 协议；开发者用「用 GateMux 登录」接入用户——用户自付、按贡献分成；设备证书与设备授权流把电视、音箱、机器人接进来。

> One balance across vendors: a single key for Chinese SOTA models (chat / image / video / speech), compatible with the fal queue protocol and the OpenAI / Anthropic protocols. Developers add "Sign in with GateMux": users pay from their own balance and developers earn a share.

- OpenAI / Anthropic SDK: change `base_url` + key. Nothing else.
- fal Python (`fal-client`): set FAL_RUN_HOST / FAL_QUEUE_RUN_HOST **before** importing.
- fal JavaScript (`@fal-ai/client`): no host env var exists — use `requestMiddleware`.
  Working examples for both: https://gatemux.cn/docs/api-reference.md

- API base: https://rest.gatemux.cn/v1 (OpenAI 兼容 / OpenAI-compatible)
- OpenAPI: https://rest.gatemux.cn/openapi.json
- OAuth discovery: https://rest.gatemux.cn/.well-known/oauth-authorization-server
- MCP: https://mcp.gatemux.cn/mcp
- 模型目录 / Model catalog: https://rest.gatemux.cn/catalog/models
- 模型与价格一张表 / Models & prices in one table: https://gatemux.cn/models.md
- 应用目录 / App directory: https://rest.gatemux.cn/catalog/apps

每篇文档都有原始 markdown：把页面地址加 `.md` 即可（英文在 `/docs/en/{slug}.md`）。
Every page is available as raw markdown: append `.md` to its URL (English at `/docs/en/{slug}.md`).

## 入门

- [快速开始](https://gatemux.cn/docs/quickstart.md): 从注册到第一张图、第一条对话，五分钟。兼容 OpenAI / Anthropic 协议与 fal 队列协议，现有代码改 base_url + key 即可。

## 接口

- [OpenAI / Anthropic 兼容](https://gatemux.cn/docs/openai-compat.md): 对话 /v1/chat/completions 与 /v1/messages（协议透传）+ 图像 /v1/images/generations + 语音 /v1/audio/* + RAG 检索层 /v1/embeddings 与 /v1/rerank。
- [实时语音（WebSocket 流式）](https://gatemux.cn/docs/realtime-speech.md): 边说边出字、边生成边播放：两条 WebSocket（实时识别 / 实时合成）加 `/v1/audio/speech` 的 `stream: true`。事件形状对齐 OpenAI Realtime；按段结算，每段一条用量。
- [智能路由与缓存](https://gatemux.cn/docs/routing.md): 多因素自动路由与故障转移、`:provider` 锁定供应商、重复请求缓存与预算护栏。
- [跨模态工作流](https://gatemux.cn/docs/workflows.md): 一次 API 调用提交「LLM + 图 + 视频」多步生成管线——编排、审核、计费、故障转移全托管。

## fal 兼容

- [队列协议 API](https://gatemux.cn/docs/api-reference.md): fal 队列协议兼容 REST —— 提交、轮询、取结果、取消，以及错误码、幂等、webhook 与限流。
- [MCP 接入](https://gatemux.cn/docs/mcp.md): 9 个标准 MCP 工具，Streamable HTTP 无状态。Claude、Cursor 等客户端可无改切换。

## 集成

- [开发工具接入](https://gatemux.cn/docs/tools.md): 在 Claude Code、Cursor、Cline、Continue 等开发工具里用上 gatemux——改 base_url + key 即接入国产模型全家桶。
- [DeepSeek Harness 接入](https://gatemux.cn/docs/deepseek-harness.md): 在 DeepSeek Harness 桌面端安装 GateMux 登录插件——用你自己的 GateMux 账户登录，模型请求记你自己的余额，不用配 key。
- [Pipecat 实时智能体](https://gatemux.cn/docs/pipecat.md): 用 Pipecat 编排实时语音与多模态对话，接入 GateMux 的 STT、TTS 和 LLM，帮助玩具与 IoT 设备团队快速开发原型。

## 计费

- [峰谷计费](https://gatemux.cn/docs/pricing-tiers.md): 部分模型按时段两档计价，空闲时段更便宜。如何查当前档位、请求跨越时段边界怎么算、为什么扣款先多后退。

## 开放平台

- [开放平台快速开始](https://gatemux.cn/docs/developer-quickstart.md): 成为开发者 → 建应用 → 拿 client_id → 用户授权 → 首次调用，15 分钟走通。你的应用不用建收银台、不用囤额度，用户带钱来。
- [轮询式授权（桌面 / CLI）](https://gatemux.cn/docs/oauth-polling.md): 三个请求、一个授权页：发起（PKCE）→ 用户在浏览器同意 → 轮询换凭据。为什么不用回调、检查顺序为什么先判未批准、每个状态码该怎么处理。
- [重定向式授权（Web 应用）](https://gatemux.cn/docs/oauth-redirect.md): 有后端的 Web 应用用标准 OAuth 2.0 授权码 + PKCE 接入：浏览器跳到授权页，同意后带 code 回你的回调地址，后端换 access_token + refresh_token。
- [设备授权流（电视 / IoT / 无浏览器）](https://gatemux.cn/docs/oauth-device.md): 没有浏览器也没有键盘的设备（电视、音箱、机器人、远程 SSH 里的 CLI）用 RFC 8628 设备授权流接入：设备显示一个 8 位码，用户在手机上输码同意，设备轮询换凭据。
- [设备证书（IoT 批量签发）](https://gatemux.cn/docs/device-provisioning.md): 出厂设备不经过用户授权也能调用：厂商在门户按批次签发设备证书，每台一条凭据、用量记厂商账户、按台设月预算，按固件批次或序列号吊销。
- [权限（scope）](https://gatemux.cn/docs/scopes.md): 九个 scope 各管哪些端点、缺了会怎样、为什么续期不能扩权、存量服务端 key 为什么不受影响。
- [安全事件回调](https://gatemux.cn/docs/security-events.md): 用户撤销授权、授权因异常被暂停、应用被停用或恢复、授权的月上限用完时，GateMux 把带签名的事件 POST 到你登记的地址。事件格式、验签方法、重试规则。
- [归因与用量](https://gatemux.cn/docs/attribution.md): 每笔用量怎么算到你的应用头上（来自凭据，永远不来自请求头）、门户里的用量图、目录排名的口径、以及用户设的每月上限如何生效。
- [应用审核](https://gatemux.cn/docs/app-review.md): 三条准入标准、提审包必填项、3 个工作日 SLA、驳回原因码、上线后哪些修改要复审、停用的三种类型与申诉。
- [错误码](https://gatemux.cn/docs/errors.md): 开放平台相关端点的全部错误码。code 是契约，客户端按 code 分支；message 只给人看，随时可能改。
- [分成规则](https://gatemux.cn/docs/revenue-share.md): 你的应用带来的每一笔已结算用量，平台按毛利的一定比例计提给你。这里是完整口径：基数、费率、什么时候不计提、退款怎么算、多币种怎么记、什么时候能提现。
- [「用 GateMux 登录」是什么](https://gatemux.cn/docs/sign-in-with-gatemux.md): 给使用第三方应用的你：这个按钮授权了什么、钱怎么扣、上限怎么设、怎么随时撤回。
- [开放平台变更日志](https://gatemux.cn/docs/changelog-platform.md): scope 增减、错误码变化、费率调整都记在这里。会影响开发者的改动（费率、scope 语义）提前公告。

## English

- [Quickstart](https://gatemux.cn/docs/en/quickstart.md): From signup to your first image and first chat in five minutes. Compatible with OpenAI / Anthropic protocols and the fal queue protocol — existing code only needs a base_url + key change.
- [OpenAI / Anthropic compatible](https://gatemux.cn/docs/en/openai-compat.md): Chat via /v1/chat/completions and /v1/messages, images via /v1/images/generations, speech via /v1/audio/*, plus the RAG retrieval layer — /v1/embeddings and /v1/rerank.
- [Realtime speech (WebSocket streaming)](https://gatemux.cn/docs/en/realtime-speech.md): Words as they are spoken, audio as it is generated — two WebSockets (realtime transcription / synthesis) plus `stream: true` on `/v1/audio/speech`. Events follow the OpenAI Realtime shape; billing is per segment, one usage row each.
- [Smart Routing & Caching](https://gatemux.cn/docs/en/routing.md): Multi-factor automatic routing and failover, `:provider` pinning, result caching and budget guardrails.
- [Cross-Modal Workflows](https://gatemux.cn/docs/en/workflows.md): Submit an LLM + image + video pipeline in one API call — orchestration, moderation, billing and failover fully managed.
- [Queue Protocol API](https://gatemux.cn/docs/en/api-reference.md): fal queue-protocol-compatible REST — submit, poll, fetch, cancel, plus error codes, idempotency, webhooks and rate limits.
- [MCP](https://gatemux.cn/docs/en/mcp.md): 9 standard MCP tools over stateless Streamable HTTP. Clients like Claude and Cursor switch over with no changes.
- [Dev Tool Integrations](https://gatemux.cn/docs/en/tools.md): Use gatemux from Claude Code, Cursor, Cline, Continue and more — change base_url + key to unlock China's SOTA models.
- [DeepSeek Harness](https://gatemux.cn/docs/en/deepseek-harness.md): Install the GateMux sign-in plugin in the DeepSeek Harness desktop app — sign in with your own GateMux account and requests are billed to your own balance, with no key to configure.
- [Pipecat Real-Time Agents](https://gatemux.cn/docs/en/pipecat.md): Build real-time voice and multimodal agent prototypes with Pipecat and GateMux STT, TTS, and LLM services for toys and IoT devices.
- [Peak & Off-Peak Pricing](https://gatemux.cn/docs/en/pricing-tiers.md): Some models are billed at two time-based rates, cheaper off-peak. How to check the current tier, how requests spanning a boundary are billed, and why the hold exceeds the final charge.
- [Open platform quickstart](https://gatemux.cn/docs/en/developer-quickstart.md): Become a developer → create an app → get a client_id → user authorizes → first call, in 15 minutes. No checkout page, no prepaid quota — users bring their own balance.
- [Polling authorization (desktop / CLI)](https://gatemux.cn/docs/en/oauth-polling.md): Three requests and one consent page - start (PKCE) → the user approves in a browser → poll for the credential. Why there is no callback, why "pending" is checked before the verifier, and what to do with each status code.
- [Redirect authorization (web apps)](https://gatemux.cn/docs/en/oauth-redirect.md): Web apps with a backend integrate through standard OAuth 2.0 authorization code + PKCE - the browser goes to the consent page, comes back to your redirect URI with a code, and your backend exchanges it for an access_token and a refresh_token.
- [Device authorization (TV / IoT / no browser)](https://gatemux.cn/docs/en/oauth-device.md): Devices with no browser or keyboard (TVs, speakers, robots, a CLI inside a remote SSH session) use the RFC 8628 device flow. The device shows an 8-character code, the user enters it on their phone and approves, and the device polls for the credential.
- [Device certificates (IoT batch provisioning)](https://gatemux.cn/docs/en/device-provisioning.md): Factory devices can call GateMux without a user ever authorizing them. The vendor issues device certificates in batches from the developer portal, one credential per device, billed to the vendor's account, with an optional monthly cap per device and revocation by firmware batch or serial.
- [Scopes](https://gatemux.cn/docs/en/scopes.md): Which endpoints each of the nine scopes gates, what happens without it, why renewal cannot widen scopes, and why existing server keys are unaffected.
- [Security events](https://gatemux.cn/docs/en/security-events.md): When a user revokes access, an authorization is paused for unusual spending, the app is suspended or restored, or a monthly cap runs out, GateMux POSTs a signed event to your URL. Format, signature check, retries.
- [Attribution and usage](https://gatemux.cn/docs/en/attribution.md): How each usage record is attributed to your app (from the credential, never from headers), the portal's usage chart, how directory ranking is computed, and how a user's monthly cap takes effect.
- [App review](https://gatemux.cn/docs/en/app-review.md): The three admission criteria, required submission items, the 3-business-day SLA, rejection reason codes, which post-launch edits need re-review, and the three suspension kinds plus appeals.
- [Error codes](https://gatemux.cn/docs/en/errors.md): Every error code for open-platform endpoints. The code is the contract - branch on it; the message is for humans and may change.
- [Revenue share](https://gatemux.cn/docs/en/revenue-share.md): For every settled request your app brings, the platform accrues a share of the gross margin to you. This page is the full definition — basis, rate, when nothing accrues, refunds, currencies, and when payouts open.
- [What is "Sign in with GateMux"](https://gatemux.cn/docs/en/sign-in-with-gatemux.md): For people using a third-party app: what the button authorizes, how you are charged, how to set a cap, and how to revoke at any time.
- [Open platform changelog](https://gatemux.cn/docs/en/changelog-platform.md): Scope additions and removals, error-code changes and rate adjustments are recorded here. Developer-affecting changes (rates, scope semantics) are announced in advance.