API ドキュメント

API キーはAPI キーページで作成します。1 文字あたり言語に応じて 1〜5 クレジットを消費し（「言語」を参照）、音声の作成に失敗した場合はクレジットが返還されます。

AI エージェント向け

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

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

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（OpenAI 形式に対する VoiceWrap 独自の拡張）、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 を返し、その言語のボイスを案内します。

1 文字あたりのクレジットは読み上げ言語で決まります。cost = 文字数 × 係数（連続する空白は 1 文字として数えます）。中国語・日本語・韓国語は 1 文字が 1 音節にあたるため多めです。

1 文字あたりのクレジット	言語
×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

動画や音声を別の言語に吹き替えます。音声を書き起こして翻訳し、吹き替え先の言語で 1 行ずつ読み上げて、元の背景音（音楽や効果音）に重ねます。吹き替え済みの MP4（動画の場合）、MP3、翻訳済みの SRT 字幕が得られます。料金は元ファイルの長さで 1 分あたり 20,000 クレジット（秒単位で課金、1ファイル最低1分）、最長 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. 結果を確認

status が succeeded か failed になるまで、5〜10 秒ごとに GET /api/v1/dubbing/:id を照会します。吹き替えには数分かかります。ファイルのリンクは署名付きで 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 分、1 時間に 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 でジョブを照会してください）