MATCHALL API / QUICK START
从这里,开始使用。
登录、创建密钥、配置客户端。几步就能发起第一次请求。
1. 登录并确认账户
点击“登录后台”,输入你的管理员密码。进入“账户管理”,确认 Pro / Plus 已授权且模型已同步。已有授权无需因更换域名重新连接。
首次连接或需要重新授权时,在自己的电脑运行项目中的 deploy/Open-Authorization.ps1,再通过后台的官方登录按钮完成授权。
2. 创建 API Key
进入“API Keys”→“创建 API Key”,填写应用名称并选择访问范围。模型客户端选择“模型接口”,编程任务选择“编程任务”。完整密钥只显示一次,保存后填入对应应用。
连接你的 Agent
选择你使用的工具,按步骤填写地址、密钥和模型。支持 OpenClaw、Hermes、DeepSeek Harness、Claude Code 与 Codex。
打开 Agent 接入教程 →3. 填入客户端配置
| 配置项 | 填写内容 |
|---|---|
| 接口类型 | OpenAI 兼容 |
| Base URL | https://api.maximoraverse.org/v1 |
| API Key | 你在后台创建的 MatchAll 密钥 |
| 模型 | matchall-auto(按后台策略选择) |
https://api.maximoraverse.org/v1也可使用 matchall-pro / matchall-plus 指定账户,或从 GET /v1/models 返回的列表选择真实模型。客户端会自动补上接口路径时,不要重复填写 /v1。
4. 查看用量,设置限额
进入“用量与限额” →,按时间、密钥、账户、模型或接口筛选,查看请求数、输入 / 输出 Tokens、缓存和花费趋势。
点击“设置限额”设置全局预算,或在对应 API Key 下点击“编辑”。可按每日、每月或累计设置请求数、Tokens 和 USD 限额;留空表示不限,填 0 会阻止新调用。全局与密钥限额同时生效,每日 / 每月按北京时间重置。
USD 是按官方 API 价格估算的等价花费,订阅调用不会因此额外扣费。未上报用量或未定价的数据会标注;已开始的请求会完成,单次实际用量可能使 Tokens / USD 超过设定值。
第一次请求
下面的示例使用 Chat Completions。把占位符替换成自己的密钥:
curl https://api.maximoraverse.org/v1/chat/completions \
-H "Authorization: Bearer ${MATCHALL_API_KEY}" \
-H "Content-Type: application/json" \
-d '{"model":"matchall-auto","messages":[{"role":"user","content":"你好"}],"stream":true}'多轮对话请发送完整历史。需要固定账户时,增加 X-Matchall-Session: 会话标识 请求头。Responses 客户端也可以使用 POST /v1/responses。
文件、批处理与对话续接
/v1/files 支持本地加密上传、下载和删除,引用文件时由订阅模型处理;每个文件最多 8 MiB。/v1/batches 支持 Responses / Chat 文本批处理,每批最多 100 条。批处理计入现有用量图表和限额,使用标准 API 等价价格,没有官方 Batch 折扣。
Responses 首次设置 store:true,后续携带 previous_response_id 即可续接。历史按密钥隔离、固定原账户,加密保存 30 天。Chat Completions 仍需要完整历史。
GET /v1/capabilities 可查询支持范围。支持 JSON Schema 输出、推理强度与文本详细度。图片生成、音频和 Embeddings 暂不支持订阅调用;采样和输出长度参数仍受上游限制,X-Matchall-Strict-Parameters:true 可在参数无法生效时拒绝请求。
提交编程任务
在“编程任务”中点击“新建任务”,选择 Codex 或 Claude Code,填写说明并上传工作文件。提交后查看进度,完成后点击文件名称下载结果;执行中的任务可取消。
Claude Code 需要先按“账户管理”中的步骤独立登录。Claude 订阅用于编程任务;使用 matchall-auto 时,/v1/messages 可让 Claude Code 调用 GPT 模型;真实 Claude 模型接口需要另行配置官方 Anthropic API Key。
遇到问题时
- 401:检查 API Key 是否填写正确、是否已撤销。
- 429:可能达到服务限额、账户用量受限或正在排队。在“请求记录”中查看原因;若达到自设限额,在“用量与限额”中查看重置时间或调整预算。
- 没有可用账户:在“账户管理”中检查授权、启用状态和冷却情况。
自动切换只发生在输出开始前。后台 Tokens 是本服务记录,实际剩余额度以官方账户用量页面为准。