VoiceWrap

API 文档

在API 密钥页面创建 API 密钥。每个字符消耗 1 额度；音频生成失败时额度会退还。

面向 AI 智能体

三种集成方式，选择您的智能体支持的一种。供机器读取： /llms.txt （面向 LLM 的说明）和 /api/v1/openapi.json （OpenAPI 3.1）。

1. MCP server

URL https://voicewrap.app/api/mcp。工具：list_voices、text_to_speech、get_job、get_balance。可通过 OAuth（登录即可，无需密钥）或 API 密钥进行身份验证。list_voices 和 text_to_speech 支持可选的 language 字段（见“语言”）。

Claude.ai / Claude Desktop：无需 API 密钥

  1. Settings → Connectors → Add custom connector。
  2. 名称填写 VoiceWrap，粘贴 URL https://voicewrap.app/api/mcp，点击 Add。
  3. 点击 Connect，登录 Google 并选择 允许。可在“API 密钥”页面断开连接。

其他客户端使用 API 密钥：

Claude Code
claude mcp add --transport http voicewrap https://voicewrap.app/api/mcp \
  --header "Authorization: Bearer sk_live_..."
Cursor · ~/.cursor/mcp.json
{
  "mcpServers": {
    "voicewrap": {
      "url": "https://voicewrap.app/api/mcp",
      "headers": { "Authorization": "Bearer sk_live_..." }
    }
  }
}
Claude Desktop · claude_desktop_config.json
{
  "mcpServers": {
    "voicewrap": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://voicewrap.app/api/mcp",
               "--header", "Authorization: Bearer sk_live_..."]
    }
  }
}

2. OpenAI SDK（修改 base_url）

Python
from openai import OpenAI

client = OpenAI(api_key="sk_live_...", base_url="https://voicewrap.app/api/v1")
client.audio.speech.create(
    model="voicewrap", voice="Ngọc Huyền", input="Xin chào!"
).write_to_file("speech.mp3")
TypeScript
import OpenAI from "openai";

const client = new OpenAI({ apiKey: "sk_live_...", baseURL: "https://voicewrap.app/api/v1" });
const res = await client.audio.speech.create({ model: "voicewrap", voice: "nova", input: "Xin chào!" });
await fs.promises.writeFile("speech.mp3", Buffer.from(await res.arrayBuffer()));

3. REST API

见下方各节。

身份验证

Authorization: Bearer sk_live_...

每个账户每分钟最多 30 次请求。每次请求的文本最多 5,000 个字符。

OpenAI 兼容: POST /api/v1/audio/speech

格式与 OpenAI 相同。直接返回音频文件；长文本会等待生成完成（最长约 4.5 分钟）。model 字段会被忽略。可选的 language 字段是 VoiceWrap 的扩展（见“语言”）。

curl https://voicewrap.app/api/v1/audio/speech \
  -H "Authorization: Bearer $VOICEWRAP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"input": "Xin chào, đây là VoiceWrap.", "voice": "Ngọc Huyền", "response_format": "mp3"}' \
  --output speech.mp3

也可以使用 OpenAI 的声音名称。越南语中的对应关系：alloy → Ngọc Huyền, ash → Minh Triết, ballad → Ngọc Linh, coral → Thùy Dung, echo → Hải Đăng, fable → Thiện Minh, nova → Mai Anh, onyx → Thiền Tâm Đức, sage → Quỳnh Anh, shimmer → Trúc Ly, verse → Thanh Bình。其他语言中，每个名称对应该语言中同性别的母语声音。

生成语音（任务）: POST /api/v1/tts

返回任务及音频链接（1 小时后过期）。500 个字符以内立即返回（200）；文本更长或发送 "async": true 时返回 202，之后每 2–5 秒查询一次 GET /api/v1/tts/:id。

curl https://voicewrap.app/api/v1/tts \
  -H "Authorization: Bearer $VOICEWRAP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "Giá gói Pro là 100.000 đồng.", "voice": "Hải Đăng", "speed": 1.0, "format": "mp3"}'
{
  "id": "f0b2...",
  "status": "succeeded",          // queued | running | succeeded | failed
  "progress": 1,                  // 运行中为 0..1
  "queue_position": null,         // 排队时前面的任务数
  "language": "vi",               // 朗读语言；未发送时取声音的语言或自动识别
  "audio_url": "https://...",     // 播放，1 小时后过期
  "download_url": "https://...",  // 下载文件
  "duration_seconds": 3.4,
  "cost": 28
}

语言

API 支持朗读 11 种语言。每个内置声音都是母语者，只朗读自己的语言；您克隆的声音可以朗读其中任意一种。可在 POST /api/v1/tts、POST /api/v1/audio/speech（VoiceWrap 对 OpenAI 格式的扩展）和 MCP 工具 text_to_speech 中发送可选的 language 字段（ISO 639-1 代码）。省略时，内置声音按其自身语言朗读；使用克隆声音或不指定声音时，根据文本识别语言，不指定声音时由该语言的默认声音（见下方）朗读。数字、百分比和货币会按各语言的习惯读出。

支持的代码及各语言的默认声音：

其他代码（包括从文本识别出的）返回 400 unsupported_language。内置声音搭配不同的 language 时返回 400 voice_language_mismatch，并列出该语言的声音。

POST /api/v1/tts
curl https://voicewrap.app/api/v1/tts \
  -H "Authorization: Bearer $VOICEWRAP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "こんにちは、VoiceWrap です。", "voice": "Anna", "language": "ja"}'
POST /api/v1/audio/speech
curl https://voicewrap.app/api/v1/audio/speech \
  -H "Authorization: Bearer $VOICEWRAP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"input": "Hello from VoiceWrap.", "voice": "nova", "language": "en"}' \
  --output hello.mp3
Python · OpenAI SDK
client.audio.speech.create(
    model="voicewrap", voice="nova", input="Hello from VoiceWrap.",
    extra_body={"language": "en"},  # language 是 VoiceWrap 的扩展，因此放在 extra_body 中
).write_to_file("hello.mp3")

声音: GET /api/v1/voices

voice 可传入名称（带或不带声调符号，例如 "ngoc-huyen"）、id 或 OpenAI 声音名称。留空时使用该语言的默认声音。加上 ?language=ja 可只列出朗读该语言的声音（以及您克隆的声音）。每个声音都带有 language（克隆声音为 null，可朗读所有语言）和 gender。

curl "https://voicewrap.app/api/v1/voices?language=vi" -H "Authorization: Bearer $VOICEWRAP_API_KEY"

{ "voices": [ { "id": "...", "name": "Ngọc Huyền", "key": "ngoc-huyen",
                "description": "Nữ · Miền Bắc · Tự nhiên", "type": "system",
                "language": "vi", "gender": "female",
                "preview_url": "https://..." } ] }

克隆声音: POST /api/v1/voices

需要 3 到 15 秒清晰的语音，并附上准确的文字稿。只能使用您本人或已同意者的声音。

curl https://voicewrap.app/api/v1/voices \
  -H "Authorization: Bearer $VOICEWRAP_API_KEY" \
  -F name="Giọng của tôi" \
  -F ref_text="Nội dung chính xác của đoạn ghi âm" \
  -F consent=true \
  -F file=@sample.wav

错误码

{ "error": { "code": "insufficient_credits", "message": "..." } }
API 文档 · VoiceWrap