[ 快速开始 ]
快速开始
三步完成首次调用：获取 API Key、配置接口地址、发送请求
接入信息
- 接口地址（base URL）
- YOUR_API_BASE_URL
接口地址将在开通后于控制台提供。
- 示例模型 ID
- matr-1去模型广场选择 →
- 鉴权方式
- 请求头 Authorization: Bearer <API Key>
- 协议
- 按 OpenAI 兼容格式设计（Chat Completions / Embeddings），兼容范围以 API 文档为准
步骤 1：获取 API Key
提交试用额度申请，开通后我们会告知控制台登录方式与 API Key 获取方式。申请试用额度
请将 API Key 保存在环境变量或密钥管理服务中，不要写入前端代码或提交到代码仓库。
bash
export MATR_API_KEY="<您的 API Key>"步骤 2：安装 SDK
matr 模型 API 按 OpenAI 兼容格式设计，可使用 OpenAI 官方 SDK 调用；个别参数的支持情况以 API 文档为准。
pip install openai步骤 3：发送首个请求
将下方示例中的模型 ID 替换为模型广场中您选择的模型。
curl YOUR_API_BASE_URL/chat/completions \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $MATR_API_KEY" \
-d '{
"model": "matr-1",
"messages": [
{"role": "system", "content": "你是一名严谨的技术助理。"},
{"role": "user", "content": "用三句话解释什么是向量检索。"}
]
}'流式输出
设置 stream 为 true，逐段接收生成内容，适合对话界面。
stream = client.chat.completions.create(
model="matr-1",
messages=[{"role": "user", "content": "写一段 100 字的产品介绍。"}],
stream=True,
)
for chunk in stream:
if chunk.choices and chunk.choices[0].delta.content:
print(chunk.choices[0].delta.content, end="", flush=True)读取用量
响应中的 usage 字段列出本次请求的 Tokens 用量，可用于与业务日志核对。以下字段名为通行格式，实际字段与计量口径以 API 文档和控制台为准。
JSON
"usage": {
"prompt_tokens": 1200,
"completion_tokens": 350,
"total_tokens": 1550,
"prompt_tokens_details": { "cached_tokens": 1024 }
}prompt_tokens：输入 Tokens；prompt_tokens_details.cached_tokens 为其中命中上下文缓存的部分completion_tokens：输出 Tokens；推理类模型的计量口径以 API 文档为准total_tokens：输入与输出合计
各部分对应的单价见模型详情页；计量与计费口径以控制台为准。
从其他平台迁移
如果您的代码已使用 OpenAI SDK，通常按以下三步迁移：
- 将 base_url 改为 matr 接口地址；
- 将 API Key 改为 matr 控制台创建的密钥；
- 将 model 改为模型广场中的模型 ID。
部分参数（如工具调用、结构化输出）的支持情况因模型而异，以模型详情页的能力标签与 API 文档为准。
限流与重试
请求超过 RPM 或 TPM 限额时，接口通常返回 HTTP 429（以 API 文档为准）。建议按指数退避重试；需要更高限额时可申请提升，或咨询专属吞吐。
查看限流等级 →常见错误
| 状态码 | 含义 | 建议处理 |
|---|---|---|
| 400 | 请求参数有误 | 检查请求体格式与该模型支持的参数 |
| 401 | API Key 缺失或无效 | 检查 Authorization 请求头与密钥状态 |
| 403 | 无权访问该模型或账户状态受限 | 确认账户状态与模型访问权限 |
| 404 | 模型不存在 | 核对模型 ID 是否与模型广场一致 |
| 429 | 超出 RPM / TPM 限流 | 按指数退避重试，或申请提升限流 |
| 500 / 503 | 服务暂时不可用 | 稍后按指数退避重试；持续出现请联系我们 |
状态码含义以 API 文档为准。