入门指南

发起首次 API 请求所需的一切

基础 URL

根据您的使用场景，Moknah 提供两种类型的端点：

标准 REST API (针对单个请求):

https://moknah.io/api/v1/

实时 WebSocket API (用于连续流式传输):

wss://moknah.io/api/v1/

身份验证

Moknah API 使用 API 密钥 用于身份验证。请在……中包含您的 API 密钥。 Authorization 使用……的页眉 持票人；持有人 随每次 HTTP 请求和 WebSocket 握手一起使用的方案。

Authorization: Bearer YOUR_API_KEY

获取 API 密钥

登录您的 Moknah 仪表盘
订阅专业版套餐或联系我们销售用于企业访问。
导航至 API
点击 管理 API 密钥
点击 新钥匙
复制并妥善保存您的密钥

妥善保管您的密钥

切勿在客户端代码或公开的代码仓库中泄露 API 密钥。请将其视为密码来对待。

快速 HTTP 示例

以下是一个使用标准 REST API 将文本转换为语音的完整示例：

curl -X POST "https://moknah.io/api/v1/tts/generate/" \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "مرحبا بك في منصة مكنة",
    "voice_id": 1
  }' \
  --output speech.mp3

import requests

response = requests.post(
    "https://moknah.io/api/v1/tts/generate/",
    headers={
        "Authorization": f"Bearer your_api_key",
    },
    json={
        "text": "مرحبا بك في منصة مكنة",
        "voice_id": 1
    }
)

if response.status_code == 200:
    with open("speech.mp3", "wb") as f:
        f.write(response.content)
    print("音频已保存！")
else:
    print(f"错误： {response.json()}")

const response = await fetch(
    'https://moknah.io/api/v1/tts/generate/',
    {
        method: 'POST',
        headers: {
            'Authorization': 'Bearer your_api_key',
            'Content-Type': 'application/json'
        },
        body: JSON.stringify({
            text: 'مرحبا بك في منصة مكنة',
            voice_id: 1
        })
    }
);

if (response.ok) {
    const blob = await response.blob();
    // 使用音频 Blob
    console.log("音频已生成！");
} else {
    const error = await response.json();
    console.error(error);
}

响应格式

成功响应

成功的响应因端点而异：

TTS 生成 (POST): 返回完整的二进制音频数据 (audio/mpeg)
TTS 流 (WSS)： 在生成 MP3 二进制数据块的同时，持续进行流式传输
其他端点： 返回结构化的 JSON 数据

速率限制标头（仅限 HTTP）

每个 HTTP 响应都包含速率限制信息（WebSocket 则通过关闭连接来实施限制）：

页眉	描述
RateLimit-Limit	每分钟最大请求数
RateLimit-Remaining	当前窗口中的剩余请求
RateLimit-Reset	限额重置时的 Unix 时间戳
Moknah-Credits-Remaining	您的剩余信用余额

常见错误代码

代码	类型	描述
400	`INVALID_REQUEST`	参数无效或 JSON 格式错误
401	`UNAUTHORIZED`	API 密钥无效或缺失
402	`INSUFFICIENT_CREDITS`	账户余额不足
429	`RATE_LIMIT_EXCEEDED`	请求过多 (HTTP)
4290	`CONCURRENT_LIMIT`	活动连接过多 (WSS)
500	`INTERNAL_SERVER_ERROR`	服务器错误