API Guide · 2026

Mouvia API 接入指南

适用范围

本指南供服务端开发者通过 Mouvia API 接入已授权模型。同时支持 OpenAI 兼容协议和 Anthropic 原生协议，请根据客户端类型选择对应的认证头和 Base URL。

配置	值
OpenAI 兼容协议 Base URL	`https://api.mouvia.tech/v1`
Anthropic 原生协议 Base URL	`https://api.mouvia.tech`
OpenAI Chat Completions	`POST /v1/chat/completions`
模型列表	`GET /v1/models`

模型授权根据访问密钥配置，客户端的模型列表请通过 /v1/models 的实时查询为准。

准备访问密钥

在工作台创建访问密钥，并确认它属于目标 Team、授权了目标模型，且额度、RPM、TPM、并发数和有效期符合调用场景。密钥只展示一次，应立即存入服务端秘密管理器。

访问密钥不得进入前端代码、Git、镜像、日志、截图或工单。应用通过运行时环境变量读取密钥：

Plain Text

MOUVIA_OPENAI_BASE_URL=https://api.mouvia.tech/v1
MOUVIA_API_KEY=<由秘密管理器注入>
MOUVIA_MODEL_ID=<由 /v1/models 返回的模型 ID>

临时手工验证时，可以在 Bash 中关闭输入回显，避免把密钥写进命令历史：

Bash

export MOUVIA_OPENAI_BASE_URL='https://api.mouvia.tech/v1'
IFS= read -rs -p 'Mouvia API Key: ' MOUVIA_API_KEY
printf '\n'
export MOUVIA_API_KEY

查询获授权模型

先请求模型列表。HTTP 200 只证明密钥通过鉴权并能读取目录；仍需发送一次真实推理才能证明模型链路可用。

Bash

curl --silent --show-error --fail-with-body \
  "$MOUVIA_OPENAI_BASE_URL/models" \
  -H "Authorization: Bearer $MOUVIA_API_KEY"

在返回的 data[].id 中确认目标模型。示例模型 ID 只说明请求格式，实际可用模型以当前访问密钥的本次响应为准。

发送最小推理请求

用模型列表中的准确 ID 请求 Chat Completions：

Bash

curl --silent --show-error --fail-with-body \
  "$MOUVIA_OPENAI_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $MOUVIA_API_KEY" \
  -H 'Content-Type: application/json' \
  --data @- <<'JSON'
{
  "model": "<model-id>",
  "messages": [
    {
      "role": "user",
      "content": "只回复：mouvia ready"
    }
  ],
  "max_tokens": 16,
  "stream": false
}
JSON

接入测试的通过条件如下：

HTTP 状态为 200。
choices[0].message.content 是非空字符串。
响应中的模型与请求目标一致。
usage 包含本次请求的 token 用量。

不要只检查 HTTP 200。响应缺少 choices、文本为空或 JSON 无法解析时，本次调用仍应判为失败。

OpenAI SDK 配置

支持自定义 OpenAI Base URL 的 SDK 可复用现有 Reponses / Chat Completions 客户端。

下面以Chat Completions 客户端 Python SDK 为例：

Python

import os

from openai import OpenAI

client = OpenAI(
    api_key=os.environ["MOUVIA_API_KEY"],
    base_url=os.environ.get(
        "MOUVIA_OPENAI_BASE_URL",
        "https://api.mouvia.tech/v1",
    ),
    max_retries=0,
    timeout=60.0,
)

response = client.chat.completions.create(
    model=os.environ["MOUVIA_MODEL_ID"],
    messages=[
        {"role": "user", "content": "只回复：mouvia ready"},
    ],
    max_tokens=16,
)

content = response.choices[0].message.content
if not content or not content.strip():
    raise RuntimeError("模型返回了空文本")

print(content)

联调阶段关闭 SDK 自动重试，便于看到第一次请求的真实结果。服务端应用如需重试，应设置较小的次数和退避上限，并遵守服务端返回的 Retry-After。连接在服务端已接收请求后中断时，调用结果和费用都可能已经产生，不要无条件重放。

服务接入要求

只从服务端秘密管理器或受控运行时环境读取 MOUVIA_API_KEY。
启动时校验 Base URL 使用 HTTPS，且主机名精确为 api.mouvia.tech。
把模型标识作为受控配置，启用前用目标 key 查询一次 /v1/models。
为连接和总请求设置超时。调用方取消等待不代表网关没有产生用量。
报错 40x 建议先修正请求或权限；429 可能是额度不足，建议按 Retry-After 和额度策略处理；5xx、网络错误和超时建议只做有上限的退避重试。

常见错误

现象	优先检查
401	key 是否与当前推理入口匹配、是否粘贴完整、是否已过期或撤销。不同环境的 key 不能混用。
403	key 或 Team 是否授权了请求中的模型。
404	Base URL 是否误用了工作台域名，或漏写 `/v1`。请求使用 `api.mouvia.tech/v1`。
429	RPM、TPM、并发或预算是否达到限制；读取 `Retry-After` 后再决定是否重试。
5xx 或超时	记录调用编号和发生时间，执行有上限的退避重试；不要在日志中附上密钥和完整提示词。
HTTP 200 但文本为空	按失败处理，保存脱敏后的响应结构和调用编号，检查客户端解析与模型返回。

接入验收

使用将要部署的服务身份和目标 key 完成以下检查：

/v1/models 返回 200，目标模型出现在 data[].id。
/v1/chat/completions 返回 200 和非空文本。
应用能读取 usage，工作台能看到对应的用量归属。
故意使用无效 key 时返回 401，应用不会把服务端错误正文当作成功结果。
配置、构建产物、日志和 Git diff 中没有访问密钥。
监控能区分 401/403、429、5xx、网络错误和超时。

不要把历史测试记录或示例模型 ID 当作当前可用性证明。每次接入或配置变更后都应使用目标 key 完成上述验收。

密钥轮换

先创建新 key 并部署到调用方，再用新 key 完成模型列表和真实推理测试。确认用量进入新 key 后撤销旧 key。只要密钥出现在聊天、日志、截图、工单或 Git 中，就按泄露处理并立即轮换。