API 认证

AiWma API 使用基于 HTTP Header 的 API Key 认证机制，所有需要身份验证的请求都必须在 X-Api-Key 请求头中包含有效的 Key。

API Key 格式

AiWma API Key 采用统一的结构化格式，方便识别环境和客户归属：

        格式说明
        aiwma_{env}_{clientCode}_{32位随机字符}

示例：
  aiwma_dev_xmohe_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6    # 开发环境
  aiwma_prod_xmohe_q7r8s9t0u1v2w3x4y5z6a7b8c9d0e1f2   # 生产环境

字段	可选值	说明
`env`	`dev` / `prod`	`dev` Key 不计入生产配额，日志更详细； `prod` Key 用于正式上线环境
`clientCode`	您的客户代码（如 `xmohe`）	由 AiWma 团队在开户时分配，全局唯一
随机字符	32 位十六进制字符串	加密随机生成，平台内部只存储哈希值，明文 Key 只在创建时显示一次

🔑

API Key 明文只显示一次

Key 创建后，明文只在响应中出现一次。AiWma 平台内部只存储哈希值，无法还原明文。如果 Key 丢失，必须重新创建新的 Key。请立即将 Key 保存到安全的密钥管理工具（如 1Password、Vault）中。

在请求中使用 API Key

将 API Key 放在 HTTP 请求的 X-Api-Key 请求头中：

        bashcurl 示例
        # 创建 ACS 会话
curl -X POST https://api.aiwma.com/api/v1/acs/sessions \
  -H "X-Api-Key: aiwma_prod_xmohe_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"channel": "web_widget"}'

        javascriptJavaScript / Node.js 示例
        const response = await fetch('https://api.aiwma.com/api/v1/acs/sessions', {
  method: 'POST',
  headers: {
    'X-Api-Key': process.env.AIWMA_API_KEY,  // 从环境变量读取
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ channel: 'api_direct' }),
});

const data = await response.json();
console.log(data.data.session.id); // 会话 ID

        pythonPython 示例
        import os, httpx

client = httpx.Client(
    base_url='https://api.aiwma.com',
    headers={'X-Api-Key': os.environ['AIWMA_API_KEY']},
)

resp = client.post('/api/v1/acs/sessions', json={'channel': 'api_direct'})
resp.raise_for_status()
session_id = resp.json()['data']['session']['id']

⚠️

永远不要在前端代码中硬编码 API Key

生产环境的 API Key 只应存在于服务器端环境变量中。 Web Widget 使用的 apiKey 是受限公开 Key，只允许创建 web_widget 渠道的会话，不能用于 REST API 调用。二者是不同的 Key，请勿混用。

开发环境 vs 生产环境

特性	开发 Key (`dev`)	生产 Key (`prod`)
计入月配额	否	是
日志详细度	DEBUG 级别，包含完整追踪	INFO 级别，不记录消息内容
速率限制	宽松（100 次/分钟）	按合同配置（默认 30 次/分钟）
数据保留	7 天后自动清除	按合同约定（默认 90 天）
适用场景	本地开发、CI 测试	正式上线服务

速率限制

AiWma API 在网关层实施速率限制。超出限制时，API 返回 429 Too Many Requests，响应头中包含重试时间：

        http response headers速率限制响应头
        HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit:     30
X-RateLimit-Remaining: 0
X-RateLimit-Reset:     1748390400
Retry-After:           12

Retry-After 表示多少秒后可以重试。建议在客户端实现指数退避重试（Exponential Backoff）：

        javascript指数退避重试示例
        async function fetchWithRetry(url, options, maxRetries = 3) {
  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    const resp = await fetch(url, options);
    if (resp.status !== 429) return resp;

    const retryAfter = parseInt(resp.headers.get('Retry-After') ?? '2');
    const delay = retryAfter * 1000 * Math.pow(2, attempt);
    await new Promise(r => setTimeout(r, delay));
  }
  throw new Error('Max retries exceeded');
}

认证错误响应

认证失败时，所有端点统一返回以下格式：

        json认证错误响应体
        {
  "success": false,
  "error": {
    "code":    "AUTH_INVALID_KEY",
    "message": "The provided API key is invalid or has been revoked"
  },
  "meta": {
    "requestId": "req_01HXYZ...",
    "traceId":   "tr_abc123...",
    "timestamp": "2026-05-28T08:00:00.000Z"
  }
}

常见认证错误码及处理建议：

错误码	HTTP 状态	原因及处理
`AUTH_INVALID_KEY`	401	Key 格式错误、Key 不存在或已被吊销。检查 Key 是否有前后空格，或联系 AiWma 确认 Key 状态。
`AUTH_KEY_EXPIRED`	401	Key 已过期。默认 Key 有效期为 365 天，需重新申请。
`AUTH_ENV_MISMATCH`	401	使用 `dev` Key 访问了生产端点（或反之）。确认 API Key 前缀与目标环境一致。
`SESSION_QUOTA_EXCEEDED`	429	月会话配额已耗尽。查看用量控制台或联系 AiWma 升级套餐。

WebSocket 认证

建立 WebSocket 连接时，API Key 通过 HTTP 握手阶段的请求头传递，而不是通过 URL 参数（避免 Key 被记录在服务器日志中）：

        javascriptWebSocket 认证示例
        // 浏览器端（受限，不推荐直接使用生产 Key）
const ws = new WebSocket(
  'wss://api.aiwma.com/ws/acs/SESSION_ID'
);
// 注意：浏览器的 WebSocket API 不支持自定义 Header
// 请使用 Widget 内置的语音模式，或通过后端代理建立 WS 连接

// Node.js 后端示例（推荐）
import WebSocket from 'ws';

const ws = new WebSocket('wss://api.aiwma.com/ws/acs/SESSION_ID', {
  headers: { 'X-Api-Key': process.env.AIWMA_API_KEY },
});

ℹ️

浏览器 WebSocket 的认证限制

原生浏览器 WebSocket API 不支持在建立连接时设置自定义请求头。如果需要在浏览器端直接使用语音 WebSocket，请使用 AiWma Web Widget （内部处理了认证逻辑），或通过您自己的后端服务器代理 WebSocket 连接。