# VoiceWrap

> Text-to-speech API in 11 languages (vi, en, zh, ja, ko, fr, de, es, it, pt, ru), strongest in Vietnamese. Every language is read by native voices: Vietnamese in northern, central and southern accents, plus native English, Chinese, Japanese, Korean, French, German, Spanish, Italian, Portuguese and Russian voices. MP3/WAV, voice cloning, priced per character (1 credit = 1 character, failed jobs refunded).

Authenticate every request with `Authorization: Bearer sk_live_...`. A human creates the key at https://voicewrap.app/app/keys. New accounts get 1,000 free characters.

## Docs

- [Full reference for agents](https://voicewrap.app/llms-full.txt): every endpoint with JSON examples, error codes, all voices, MCP setup, pricing
- [OpenAPI 3.1 spec](https://voicewrap.app/api/v1/openapi.json)
- [MCP server card](https://voicewrap.app/.well-known/mcp.json)
- [API docs (vi)](https://voicewrap.app/docs)
- [API docs (en)](https://voicewrap.app/en/docs)
- [API docs (zh)](https://voicewrap.app/zh/docs)
- [API docs (ja)](https://voicewrap.app/ja/docs)
- [API docs (ko)](https://voicewrap.app/ko/docs)

## Fastest integration

- MCP server (Streamable HTTP): https://voicewrap.app/api/mcp — tools: list_voices (optional "language" filter), text_to_speech (optional "language"), get_job, get_balance. Supports MCP OAuth (the user signs in and approves; discovery via https://voicewrap.app/.well-known/oauth-protected-resource/api/mcp, dynamic client registration) or an API key as a Bearer token.
- OpenAI-compatible: POST https://voicewrap.app/api/v1/audio/speech with {"input", "voice", "response_format": "mp3"|"wav", "speed", "language"?}. Returns audio bytes. With an OpenAI SDK, set base_url="https://voicewrap.app/api/v1".
- OpenAPI spec: https://voicewrap.app/api/v1/openapi.json

## Endpoints

- POST https://voicewrap.app/api/v1/audio/speech — audio bytes in the response (waits for long text).
- POST https://voicewrap.app/api/v1/tts — {"text", "voice", "speed", "format", "language", "async"} → job JSON with audio_url/download_url (signed, 1 hour). Over 500 characters returns 202; poll GET https://voicewrap.app/api/v1/tts/{id} every 2–5 s.
- GET https://voicewrap.app/api/v1/voices — available voices; ?language=xx keeps the built-in voices for that language plus your cloned ones. Each voice has "language" (null for cloned voices) and "gender".
- GET https://voicewrap.app/api/v1/me — credit balance.

Text limit: 5000 characters per request. Rate limit: 30 requests/minute. "language" is an optional ISO 639-1 code (vi, en, zh, ja, ko, fr, de, es, it, pt, ru).

## Languages

- Each built-in voice is a native speaker of one language and reads only that language. A user's cloned voices read any of the 11 languages.
- When "language" is omitted: a named built-in voice sets it (its own language); with a cloned voice or no voice it is detected from the text.
- With no voice, the language's default voice is used: vi→Hải Đăng, en→Emma, zh→Vivian, ja→Anna, ko→Sohee, fr→Camille, de→Lena, es→Lucía, it→Giulia, pt→Beatriz, ru→Natasha.
- Errors: 400 unsupported_language (a code, or a detected language, outside the list); 400 voice_language_mismatch (a built-in voice with a different explicit "language"; the message lists that language's voices).
- Numbers, percentages and currency are spelled out following each language's own conventions.

## Voices

Pass the name (accents optional) as `voice`. To read a language, pick one of its voices below (or omit voice). OpenAI names map to a native voice of the same gender in the request's language; for Vietnamese they map to: 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.

- Hải Đăng [vi]: Nam · Miền Bắc · Tự nhiên
- Ngọc Huyền [vi]: Nữ · Miền Bắc · Tự nhiên
- Mai Anh [vi]: Nữ · Miền Bắc · Tin tức
- Thiện Minh [vi]: Nam · Miền Bắc · Kể chuyện
- Trúc Ly [vi]: Nữ · Miền Bắc · Tự nhiên
- Thùy Dung [vi]: Nữ · Miền Nam · Tin tức
- Adam [vi]: Nam · Miền Nam · Tự nhiên
- Quang Sơn [vi]: Nam · Miền Trung · Tự nhiên
- Ngọc Trân [vi]: Nữ · Miền Trung · Tự nhiên
- Adam bựa [vi]: Nam · Miền Bắc · Tự nhiên
- Thiền Tâm Đức [vi]: Nam · Miền Bắc · Kể chuyện
- Minh Đức [vi]: Nam · Miền Bắc · Tin tức
- Phạm Tuyên [vi]: Nam · Miền Bắc · Tự nhiên
- Thái Sơn [vi]: Nam · Miền Nam · Kể chuyện
- Xuân Vĩnh [vi]: Nam · Miền Bắc · Tự nhiên
- Thanh Bình [vi]: Nam · Miền Bắc · Kể chuyện
- Ngọc Linh [vi]: Nữ · Miền Bắc · Kể chuyện
- Đoan Trang [vi]: Nữ · Miền Bắc · Tự nhiên
- Thục Đoan [vi]: Nữ · Miền Nam · Kể chuyện
- Minh Triết [vi]: Nam · Miền Nam · Tin tức
- Mỹ Duyên [vi]: Nữ · Miền Nam · Đọc truyện
- Quỳnh Anh [vi]: Nữ · Miền Bắc · Đọc truyện
- Đức Trí [vi]: Nam · Miền Nam · Đọc truyện
- Kim Thanh [vi]: Nữ · Miền Nam · Đọc truyện
- Quốc Tuấn [vi]: Nam · Miền Bắc · Tự nhiên
- Ryan [en]: Nam · Anh Mỹ · Năng động
- Aiden [en]: Nam · Anh Mỹ · Tươi sáng
- Emma [en]: Nữ · Anh Mỹ · Tự nhiên
- Olivia [en]: Nữ · Anh Anh · Tin tức
- Vivian [zh]: Nữ · Phổ thông · Tươi trẻ
- Serena [zh]: Nữ · Phổ thông · Dịu dàng
- Uncle Fu [zh]: Nam · Phổ thông · Trầm ấm
- Dylan [zh]: Nam · Giọng Bắc Kinh · Trẻ trung
- Eric [zh]: Nam · Giọng Tứ Xuyên · Sôi nổi
- Anna [ja]: Nữ · Tokyo · Tươi tắn
- Haruto [ja]: Nam · Tokyo · Tự nhiên
- Yui [ja]: Nữ · Tokyo · Kể chuyện
- Sohee [ko]: Nữ · Seoul · Ấm áp
- Minjun [ko]: Nam · Seoul · Tự nhiên
- Seoyeon [ko]: Nữ · Seoul · Tin tức
- Camille [fr]: Nữ · Paris · Tự nhiên
- Louis [fr]: Nam · Paris · Tự nhiên
- Élise [fr]: Nữ · Paris · Kể chuyện
- Antoine [fr]: Nam · Paris · Tin tức
- Lena [de]: Nữ · Đức chuẩn · Tự nhiên
- Jonas [de]: Nam · Đức chuẩn · Tự nhiên
- Katrin [de]: Nữ · Đức chuẩn · Tin tức
- Matthias [de]: Nam · Đức chuẩn · Kể chuyện
- Lucía [es]: Nữ · Tây Ban Nha · Tự nhiên
- Mateo [es]: Nam · Mỹ Latinh · Tự nhiên
- Valentina [es]: Nữ · Mỹ Latinh · Tin tức
- Javier [es]: Nam · Tây Ban Nha · Kể chuyện
- Giulia [it]: Nữ · Ý chuẩn · Tự nhiên
- Marco [it]: Nam · Ý chuẩn · Tự nhiên
- Francesca [it]: Nữ · Ý chuẩn · Tin tức
- Luca [it]: Nam · Ý chuẩn · Kể chuyện
- Beatriz [pt]: Nữ · Brazil · Tự nhiên
- Rafael [pt]: Nam · Brazil · Tự nhiên
- Inês [pt]: Nữ · Bồ Đào Nha · Tin tức
- Tiago [pt]: Nam · Bồ Đào Nha · Kể chuyện
- Natasha [ru]: Nữ · Moskva · Tự nhiên
- Dmitri [ru]: Nam · Moskva · Tự nhiên
- Olga [ru]: Nữ · Moskva · Tin tức
- Ivan [ru]: Nam · Moskva · Kể chuyện

## Pricing

1 credit = 1 character; failed jobs are refunded. Credit packs (VND, paid via PayOS at https://voicewrap.app/app/billing): Starter 25,000 VND = 100,000 credits; Pro 100,000 VND = 450,000 credits; Business 250,000 VND = 1,250,000 credits.

## Example

```bash
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"}' \
  --output speech.mp3
```

```python
from openai import OpenAI
client = OpenAI(api_key=VOICEWRAP_API_KEY, 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")
```

```bash
# Another language: use one of its native voices, or omit voice and set language
curl https://voicewrap.app/api/v1/tts \
  -H "Authorization: Bearer $VOICEWRAP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "こんにちは、VoiceWrap です。", "language": "ja"}'
```