VoiceWrap

API ドキュメント

API キーはAPI キーページで作成します。1 文字につき 1 クレジットを消費し、音声の作成に失敗した場合はクレジットが返還されます。

AI エージェント向け

連携方法は 3 つあります。エージェントが対応している方法を選んでください。機械可読な資料： /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_...

リクエストはアカウントごとに 1 分あたり 30 件までです。テキストは 1 リクエストあたり最大 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 を返すので、その後 GET /api/v1/tts/:id を 2〜5 秒ごとにポーリングしてください。

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（OpenAI 形式に対する VoiceWrap 独自の拡張）、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