VoiceWrap

Tài liệu API

Tạo API key ở trang API keys. Mỗi ký tự tốn 1 credit; credit được hoàn lại nếu tạo audio thất bại.

Dành cho AI agent

Ba cách tích hợp, chọn cách agent của bạn hỗ trợ. Đọc tự động: /llms.txt (hướng dẫn cho LLM) và /api/v1/openapi.json (OpenAPI 3.1).

1. MCP server

URL https://voicewrap.app/api/mcp. Tool: list_voices, text_to_speech, get_job, get_balance. Xác thực bằng OAuth (đăng nhập, không cần key) hoặc API key. Tool list_voices và text_to_speech nhận trường language tuỳ chọn (xem mục Ngôn ngữ).

Claude.ai / Claude Desktop: không cần API key

  1. Settings → Connectors → Add custom connector.
  2. Đặt tên VoiceWrap, dán URL https://voicewrap.app/api/mcp, bấm Add.
  3. Bấm Connect, đăng nhập Google và chọn Cho phép. Ngắt kết nối ở mục API keys & kết nối.

Các client khác dùng API key:

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. SDK OpenAI (đổi 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

Xem các mục bên dưới.

Xác thực

Authorization: Bearer sk_live_...

Giới hạn 30 request/phút cho mỗi tài khoản. Văn bản tối đa 5.000 ký tự mỗi request.

Tương thích OpenAI: POST /api/v1/audio/speech

Cùng định dạng với OpenAI. Trả về thẳng file audio; văn bản dài được chờ tới khi xong (tối đa khoảng 4,5 phút). Trường model được bỏ qua. Trường tuỳ chọn language là phần mở rộng của VoiceWrap (xem mục Ngôn ngữ).

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

Tên giọng OpenAI cũng dùng được. Với tiếng Việt: 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. Với ngôn ngữ khác, mỗi tên ứng với một giọng bản xứ cùng giới tính.

Tạo giọng nói (job): POST /api/v1/tts

Trả về job kèm link audio (hết hạn sau 1 giờ). Tới 500 ký tự trả về ngay (200); dài hơn, hoặc gửi "async": true, trả về 202, sau đó hỏi lại GET /api/v1/tts/:id mỗi 2–5 giây.

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 khi đang chạy
  "queue_position": null,         // số job phía trước nếu đang xếp hàng
  "language": "vi",               // ngôn ngữ đọc; nếu không gửi thì theo giọng hoặc tự nhận diện
  "audio_url": "https://...",     // nghe, hết hạn sau 1 giờ
  "download_url": "https://...",  // tải file
  "duration_seconds": 3.4,
  "cost": 28
}

Ngôn ngữ

API đọc 11 ngôn ngữ. Mỗi giọng có sẵn là người bản xứ và chỉ đọc ngôn ngữ của mình; giọng bạn clone đọc được mọi ngôn ngữ trong số đó. Gửi trường tuỳ chọn language (mã ISO 639-1) ở POST /api/v1/tts, POST /api/v1/audio/speech (phần mở rộng của VoiceWrap so với định dạng OpenAI) và tool MCP text_to_speech. Bỏ trống thì giọng có sẵn quyết định ngôn ngữ; với giọng clone hoặc khi không chọn giọng, ngôn ngữ được nhận diện từ văn bản, và nếu không chọn giọng thì dùng giọng mặc định của ngôn ngữ đó (danh sách dưới). Số, phần trăm, tiền tệ được đọc thành chữ theo cách của từng ngôn ngữ.

Các mã được hỗ trợ, kèm giọng mặc định:

Mã khác (kể cả ngôn ngữ nhận diện được từ văn bản) trả về 400 unsupported_language. Dùng giọng có sẵn với language khác ngôn ngữ của giọng trả về 400 voice_language_mismatch, kèm danh sách giọng của ngôn ngữ đó.

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 là phần mở rộng của VoiceWrap nên gửi qua extra_body
).write_to_file("hello.mp3")

Giọng: GET /api/v1/voices

Truyền voice bằng tên (có dấu hoặc không, ví dụ "ngoc-huyen"), id, hoặc tên giọng OpenAI. Bỏ trống thì dùng giọng mặc định của ngôn ngữ. Thêm ?language=ja để chỉ lấy các giọng đọc ngôn ngữ đó (kèm giọng bạn clone). Mỗi giọng có language (null với giọng clone, vốn đọc được mọi ngôn ngữ) và 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://..." } ] }

Clone giọng: POST /api/v1/voices

3 đến 15 giây giọng nói rõ, kèm lời đọc chính xác. Chỉ dùng giọng của bạn hoặc người đã đồng ý.

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

Mã lỗi

{ "error": { "code": "insufficient_credits", "message": "..." } }
Tài liệu API · VoiceWrap