voice-quality-api

语音质量 API

测量到语音／VoIP 目标的网络路径质量，并获取预估 MOS（1–5）——通过 API 实时完成。 专为 AI 语音 Agent 打造。提供 REST 和 MCP 工具，通过 x402（Base 上的 USDC）按次付费。

🌐 在线体验： voice-quality.com · REST api.voice-quality.com · MCP mcp.voice-quality.com

---

试用

curl https://api.voice-quality.com/health          # {"status":"ok"}

curl -s https://api.voice-quality.com/v1/voice-quality \
  -H 'content-type: application/json' \
  -d '{ "target": "your-voice-endpoint.example", "target_port": 10000, "codec": "G711" }'

你会获得预估 MOS以及实时的 RTT／抖动／丢包率。将其指向能够响应媒体数据的端点——你自己的语音基础设施，或自行运行的小型反射器 （probe-agent/cmd/reflector）。每天免费 20 次； 超出后通过 x402 按次付费（无需账户）。

{
  "request_id": "vq_2ibc6qqq",
  "target": "your-voice-endpoint.example",
  "codec": "G711",
  "measured_at": "2026-07-01T10:15:13.795Z",
  "summary": { "mos_estimate": 4.38, "mos_class": "excellent", "r_factor": 91.8 },
  "by_probe": [ /* per-probe metrics + R-factor + MOS */ ],
  "methodology": {
    "model": "ITU-T G.107 E-model",
    "confidence": "estimate",
    "assumptions": ["owd = rtt/2 (symmetric path)", "adaptive jitter buffer = 2x jitter"]
  },
  "credits_used": 0
}

项目缘起

免费的网络测量平台（Globalping、RIPE Atlas）可测量 ping／traceroute／DNS／HTTP，但不会测量 RTP 媒体质量或预估 MOS。能够做到这一点的工具（Cyara、Spearline）则面向企业销售。本项目填补了这一空白：提供简洁、自助、原生支持 Agent 的语音路径质量 API——可在路由呼叫前进行检查，或监控通往语音端点的路径。

以可信为设计原则

• 指标诚实。 根据实测网络指标得出的客观 G.107 E-model 估算，绝不会冒称感知质量（PESQ/POLQA）评分。每个响应都包含 methodology.confidence: "estimate" 及其假设。
• 常量经过验证。 编解码器的 Ie／Bpl 值已根据 ITU-T G.113（09/2024），附录 I，表 I.4 验证——行与探测配置相匹配 （无 PLC、无 VAD/DTX）。并非“典型值”，而是有据可查。
• 防护 SSRF。 约 36.7% 的公开 MCP 服务存在 SSRF 问题——本服务默认阻止内部／私有目标（协调器和探测器均如此），并提供按目标允许列表和速率限制。
• 安全加固。 探测通道采用 TLS/mTLS，容器以非 root 身份运行， pnpm audit 无问题，错误结构化且机器可读，支持 Idempotency-Key、 Prometheus /metrics 以及按身份区分的 API 密钥。

定价

档位	可获得的内容
免费	每种身份每天测量 20 次（credits_used: 0）。
按次付费	超出后，每次调用支付不到一美分至数美分的微额费用，通过 x402（Base 上的 USDC）结算。未付款 → 返回包含付款要求的 402；付款后重试。Agent 可透明地完成支付。

原生支持 Agent（MCP + x402）

一个 MCP 工具：measure_voice_quality。免费额度用尽后，服务会从已配置的钱包透明地支付 x402 费用，以封装 REST API——无需人工介入。

{
  "mcpServers": {
    "voice-quality": {
      "url": "https://mcp.voice-quality.com/",
      "env": { "MCP_CLIENT_PRIVATE_KEY": "0x…" }   // optional; only for paid calls
    }
  }
}

架构

[AI agent / dev] ──(HTTP + x402 / MCP)──► [Orchestrator] ──► [E-model (G.107): R → MOS]
                                              └──► [regional probe] ──(emulated UDP/RTP)──► target

组件	技术栈	作用
协调器 (packages/orchestrator)	TypeScript + Hono	REST API、E-model、x402 付费墙、AUP、速率限制、探测任务分发
MCP 服务 (packages/mcp-server)	TypeScript + MCP SDK	measure_voice_quality；封装 REST + 透明 x402 支付
探测 Agent (probe-agent)	Go	UDP/RTP 仿真 + RFC 3550 指标；使用低成本区域 VPS
共享组件 (packages/shared)	TypeScript	Zod 架构、类型、G.113 编解码器常量

自托管

cp .env.example .env                 # fill in values
docker compose up --build -d         # orchestrator + MCP + probe + reflector + landing
curl localhost:8080/health

完整部署（通过 Caddy 或 Cloudflare Tunnel 提供公共 HTTPS，区域探测器使用 mTLS）：docs/deploy.md。生产环境上线（主网 x402、 编解码器验证、注册表）：docs/go-live.md。

文档

方法论 · OpenAPI · 部署 · 上线 · 发现与注册表

---

MOS 是根据网络状况得出的客观估算值，并不保证通话质量。持续维护中。