API 文档

在API 密钥页面创建 API 密钥。每个字符按语言消耗 1–5 额度（见“语言”一节）；音频生成失败时额度会退还。

面向 AI 智能体

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

1. MCP server

URL https://voicewrap247.com/api/mcp。工具：list_voices、text_to_speech、get_job、dub_media、get_dubbing、get_balance。可通过 OAuth（登录即可，无需密钥）或 API 密钥进行身份验证。list_voices 和 text_to_speech 支持可选的 language 字段（见“语言”）。dub_media 为公开 source_url 上的视频或音频配音，get_dubbing 返回进度和结果文件（见“视频配音”）。

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

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

其他客户端使用 API 密钥：

Claude Code

claude mcp add --transport http voicewrap https://voicewrap247.com/api/mcp \
  --header "Authorization: Bearer sk_live_..."

Cursor · ~/.cursor/mcp.json

{
  "mcpServers": {
    "voicewrap": {
      "url": "https://voicewrap247.com/api/mcp",
      "headers": { "Authorization": "Bearer sk_live_..." }
    }
  }
}

Claude Desktop · claude_desktop_config.json

{
  "mcpServers": {
    "voicewrap": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://voicewrap247.com/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://voicewrap247.com/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://voicewrap247.com/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://voicewrap247.com/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://voicewrap247.com/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,
  "chars": 28,                    // 文本字符数
  "cost": 28                      // 扣除的额度：字符数 × 语言系数
}

语言

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

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

vi Tiếng Việt · Hải Đăng
en English · Emma
zh 中文 · Vivian
ja 日本語 · Anna
ko 한국어 · Sohee
fr Français · Camille
de Deutsch · Lena
es Español · Lucía
it Italiano · Giulia
pt Português · Beatriz
ru Русский · Natasha

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

每个字符消耗的额度取决于朗读语言：cost = 字符数 × 系数（连续空白只算一个字符）。中日韩文字一个字就是一个完整音节，因此消耗更多。

每字符额度	语言
×1	`vi` Tiếng Việt
×2	`en` English, `fr` Français, `de` Deutsch, `es` Español, `it` Italiano, `pt` Português, `ru` Русский
×5	`zh` 中文, `ja` 日本語, `ko` 한국어

POST /api/v1/tts

curl https://voicewrap247.com/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://voicewrap247.com/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://voicewrap247.com/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://voicewrap247.com/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

视频配音: POST /api/v1/dubbing

将视频或音频配音成另一种语言：语音被转写、翻译，并用目标语言逐句朗读，再混入原始背景（保留音乐和音效）。结果包括配音后的 MP4（视频）、MP3 和翻译后的 SRT 字幕。按源文件时长计费，每分钟 20,000 额度，按秒计算；最长 15 分钟；失败的任务会退回额度。

1. 上传文件

POST /api/v1/dubbing/uploads 传入文件名、类型和大小（最大 50 MB），返回已签名的 upload_url；用 PUT 上传文件（带上 Content-Type），然后在第 2 步传入 upload_path。公开的或更大的文件可跳过此步，直接发送 source_url。

curl https://voicewrap247.com/api/v1/dubbing/uploads \
  -H "Authorization: Bearer $VOICEWRAP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"filename": "intro.mp4", "content_type": "video/mp4", "size": 18874368}'

{ "upload_path": "…/source.mp4", "upload_url": "https://…", "token": "…" }

curl -X PUT "$UPLOAD_URL" -H "Content-Type: video/mp4" --data-binary @intro.mp4

2. 创建任务

POST /api/v1/dubbing 返回 202 和任务。upload_path 与 source_url 必须且只能提供一个。

curl https://voicewrap247.com/api/v1/dubbing \
  -H "Authorization: Bearer $VOICEWRAP_API_KEY" \
  -H "Content-Type: application/json" \
  -d @- <<'EOF'
{
  "upload_path": "…/source.mp4",  // 来自第 1 步（或 source_url）
  "source_name": "intro.mp4",     // 可选，显示名称
  "target_language": "en",        // 配音目标语言
  "source_language": "vi",        // 可选；自动识别
  "voice": "clone",               // "clone" 或声音名称/id
  "consent": true                 // 使用 "clone" 时必填
}
EOF

"voice": "clone"（默认）保留说话人自己的声音，需要 "consent": true：确认你有权使用文件中人物的声音。也可以传入能朗读目标语言的内置声音名称或 id（GET /api/v1/voices?language=...），或你克隆的声音。

3. 查询结果

每 5–10 秒查询一次 GET /api/v1/dubbing/:id，直到 status 为 succeeded 或 failed；配音通常需要几分钟。文件链接已签名，1 小时后过期；重新获取任务即可得到新链接。GET /api/v1/dubbing 列出最近 20 个任务（不含 lines）。

curl https://voicewrap247.com/api/v1/dubbing/8c1e... -H "Authorization: Bearer $VOICEWRAP_API_KEY"

{
  "id": "8c1e...",
  "status": "succeeded",          // queued | running | succeeded | failed
  "progress": 1,                  // 0..1
  "source_name": "intro.mp4",
  "is_video": true,
  "source_language": "vi",
  "target_language": "en",
  "voice": "clone",
  "duration_seconds": 92.4,
  "cost": 30800,                  // 已扣额度，按秒计
  "files": {                      // 签名链接，1 小时后过期
    "video": "https://...",       // MP4，音频为 null
    "audio": "https://...",       // MP3
    "subtitles": "https://..."    // 翻译后的 SRT
  },
  "lines": [                      // 逐句：原文和译文
    { "start": 0.4, "end": 3.1, "text": "Xin chào các bạn", "translation": "Hi everyone" }
  ],
  "error": null,
  "created_at": "2026-10-25T08:00:00Z",
  "finished_at": "2026-10-25T08:03:12Z"
}

限制：上传最大 50 MB，源文件最长 15 分钟，每小时 20 个任务。专属错误码：400 consent_required、unreadable_media、too_long；404 upload_not_found；502 dubbing_failed（额度已退回）。

错误码

{ "error": { "code": "insufficient_credits", "message": "..." } }

400 invalid_request （例如缺少字段或值无效）
400 unsupported_language （不在 11 种语言内的代码，包括从文本识别出的）
400 voice_language_mismatch （内置声音搭配不同的 language；消息中会列出该语言的声音）
401 invalid_api_key, unauthorized
402 insufficient_credits
404 voice_not_found （附声音列表）, job_not_found
429 rate_limited
400 consent_required, unreadable_media, too_long, 404 upload_not_found, 502 dubbing_failed (视频配音)
502 synthesis_failed （额度已退还）
504 still_running （仅限 /audio/speech；请按 id 查询任务）