音声合成 API

このページでは 2 系統の音声モデルを扱います。MiniMax Speech 2.8 は独立したプラン MiniMax Speech 公式に属し、以下の各節は基本的にこちらの説明です。ByteDance の Doubao 音声（seed-tts-2.0、seed-audio-1.0）は別のプランに属し、OpenAI 互換エンドポイントだけを使います。Doubao 音声を参照してください。同じプランの seed-icl-2.0 によるボイスクローンは Doubao ボイスクローンで説明します。どちらも対応するプランを含むキーからのみ到達できます。新しいキーを作らず、既存のチャットや動画のキーにプランを追加することもできます。

音声を合成する

どちらのエンドポイントもクリップ全体を同期的に返します。OpenAI SDK をそのまま使うなら OpenAI 互換エンドポイント、全パラメータとストリーミングが必要ならネイティブエンドポイントを選びます。

MiniMax Speech 2.8 はテキストを同期的に音声へ変換します。レスポンスが音声そのものなので、ポーリングするタスクはありません。他のモデルと同じ Base URL(ページ冒頭の表を参照)と Bearer 認証で利用でき、音声専用のホストや認証情報はありません。

ID は大文字・小文字を区別し、エイリアスはありません。tts-1 / tts-1-hd は認識されません。このプランが有効なキーを使用し、GET /v1/models で ID を確認してください。

curl https://api.hop-base.com/v1/audio/speech \
  -H "Authorization: Bearer sk-your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "speech-2.8-turbo",
    "input": "Hello, world.",
    "voice": "English_expressive_narrator",
    "response_format": "mp3"
  }' \
  --output hello.mp3

OpenAI 互換エンドポイント

POST /v1/audio/speech は OpenAI のリクエスト形式を受け付け、音声のバイト列をそのまま返します。フィールドは API リファレンスにも記載しています。

• voice を省略すると、漢字を含むテキストは Chinese (Mandarin)_News_Anchor、それ以外は English_expressive_narrator になります。
• OpenAI のボイス名も同じデフォルトボイスになります。
• 範囲内の speed は 0.5〜2 にクランプされます。
• stream_format は非対応で、指定すると 400 が返ります。

公式の openai SDK を使う場合、変えるのは Base URL と model / voice の値だけです。

from openai import OpenAI

client = OpenAI(base_url="https://api.hop-base.com/v1", api_key="sk-your-key")

response = client.audio.speech.create(
    model="speech-2.8-turbo",
    voice="Japanese_IntellectualSenior",
    input="こんにちは、世界。",
    response_format="mp3",
)
response.write_to_file("hello.mp3")

# 長いテキスト:クリップ全体をメモリに溜めず、
# 届いたバイト列から順にディスクへ書き出す
with client.audio.speech.with_streaming_response.create(
    model="speech-2.8-turbo",
    voice="Japanese_IntellectualSenior",
    input="ここに長めの原稿を入れます。",
) as streamed:
    streamed.stream_to_file("long.mp3")

ネイティブエンドポイント

POST /v1/t2a_v2 は MiniMax T2A v2 のリクエストボディをそのまま受け付け、ゲートウェイが認識しないフィールドもそのまま透過します。JSON レスポンスも(エラーを除き)公式の構造に従います。

data.audio は 16 進数でエンコードされた音声、extra_info には usage_characters と音声のメタデータが含まれます。stream: true で SSE に切り替わります。書き方はストリーム出力を参照してください。

import requests

resp = requests.post(
    "https://api.hop-base.com/v1/t2a_v2",
    headers={"Authorization": "Bearer sk-your-key"},
    json={
        "model": "speech-2.8-hd",
        "text": "你好，世界",
        "voice_setting": {"voice_id": "Chinese (Mandarin)_News_Anchor", "speed": 1.0},
        "audio_setting": {"format": "mp3", "sample_rate": 32000},
    },
)
body = resp.json()
open("hello.mp3", "wb").write(bytes.fromhex(body["data"]["audio"]))
print(body["extra_info"]["usage_characters"])  # 課金文字数

ネイティブエンドポイントでゲートウェイが行うのは次の 3 つだけです。

• model、text の長さ、stream、output_format を検証します。
• voice_setting.speed を公式の範囲にクランプします。
• ボディを 1 MiB までに制限します。

それ以外はそのまま透過し、公式の範囲外の値はサービス側が 400 で拒否します。以下の表の値とデフォルトは公式のものです。

(laughs) (chuckle) (coughs) (clear-throat) (groans) (breath) (pant) (inhale) (exhale) (gasps)
(sniffs) (sighs) (snorts) (burps) (lip-smacking) (humming) (hissing) (emm) (sneezes)

システムボイス

MiniMax 公式のシステムボイス ID 一覧にあるボイス(24 言語・332 件)はすべて利用できます。voice_id は一覧の表記どおりに渡してください。下の表は入門用の抜粋です。

voice_id 列はそのまま使用してください。大文字・小文字、スペース、括弧も変更できません。「名前」は公式のラベルです。

• 広東語のボイスには language_boost: "Chinese,Yue" が必要です。
• 中国語のテキストには標準中国語のボイスを使用してください。
• 2026-09-16 に全件検証済み:公式一覧のうち、サービス側が "voice id not exist" を返すのは 2 件だけです。
• その 2 件は Cantonese_ProfessionalHost (F) と Cantonese_ProfessionalHost (M) です。
• システムボイスの一覧は POST /v1/get_voice に {"voice_type": "system"} を送ると取得できます。

ストリーム出力

ネイティブエンドポイントで stream: true を指定すると SSE に切り替わります。各 data: {...} イベントが 16 進数の音声チャンクを運び、最後のイベントは data.status が 2 で extra_info を伴います。ボディを 1 行ずつ読み、各イベントのチャンクをデコードしてファイルに追記します。

import json
import requests

with requests.post(
    "https://api.hop-base.com/v1/t2a_v2",
    headers={"Authorization": "Bearer sk-your-key"},
    json={
        "model": "speech-2.8-turbo",
        "text": "ここに長めの原稿を入れます。",
        "stream": True,
        "stream_options": {"exclude_aggregated_audio": True},
        "voice_setting": {"voice_id": "Japanese_IntellectualSenior"},
        "audio_setting": {"format": "mp3", "sample_rate": 32000},
    },
    stream=True,
    timeout=(10, 300),
) as resp, open("long.mp3", "wb") as out:
    resp.raise_for_status()
    for line in resp.iter_lines():
        if not line.startswith(b"data:"):
            continue
        event = json.loads(line[5:])
        base = event.get("base_resp") or {}
        if base.get("status_code", 0) != 0:  # 途中で失敗: 課金されず、ストリームは終了
            raise RuntimeError(base.get("status_msg"))
        data = event.get("data") or {}
        if data.get("audio"):
            out.write(bytes.fromhex(data["audio"]))
        if data.get("status") == 2:
            print(event["extra_info"]["usage_characters"])  # 課金文字数

レイテンシとタイムアウト

短いテキスト(1〜2 文)での実測値:同期エンドポイントはクリップ全体を約 1.5〜2.4 秒で返し、stream: true では最初の音声チャンクが約 1 秒で届きます。

レイテンシはテキストの長さに応じて増えるため、長いものはストリーミングにしてください(MiniMax は 3,000 文字を超える場合にストリーミングを推奨)。同期リクエストのクライアント設定は、同時実行数、タイムアウト、課金にある他の同期エンドポイントと同じ指針に従い、読み取りタイムアウトを 300 秒以上にします。

ボイスクローン

ご自身の録音からボイスをクローンし、両エンドポイントでシステムボイスと同じように使えます。流れは MiniMax 公式のボイスクローン API と同じで、公式 SDK のコードは Base URL とキーを変えるだけで流用できます。キーのプランに MiniMax Speech のモデルが含まれている必要があります。

1. 音声をアップロード

POST /v1/files/upload は multipart/form-data で次の 2 つのフィールドだけを受け付け、それ以外は 400 を返します。

• voice_clone はクローンする録音、prompt_audio は任意のサンプル音声です。
• 長さ:voice_clone は 10 秒〜5 分、prompt_audio は 8 秒未満です。
• 長さはクローン時に検証されます。

curl https://api.hop-base.com/v1/files/upload \
  -H "Authorization: Bearer sk-your-key" \
  -F purpose=voice_clone \
  -F file=@my_voice.mp3
# → {"file":{"file_id":123456789,"bytes":…,"created_at":…,"filename":"my_voice.mp3","purpose":"voice_clone"},"base_resp":{…}}

2. ボイスをクローン

POST /v1/voice_clone に file_id と任意の voice_id を渡します。text と model を加えるとプレビュー音声が返ります。

curl https://api.hop-base.com/v1/voice_clone \
  -H "Authorization: Bearer sk-your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "file_id": 123456789,
    "voice_id": "MyNarrator01",
    "text": "Hello, this is my cloned voice.",
    "model": "speech-2.8-hd",
    "need_noise_reduction": true
  }'
# レスポンス: input_sensitive、input_sensitive_type、demo_audio(api.hop-base.com 上のプレビューのダウンロードリンク、24 時間有効。text なしなら空)、extra_info.usage_characters(プレビューの課金文字数)、base_resp

• voice_id は英字・数字・-・_ で構成し、先頭は英字、末尾は -・_ 以外にします。
• clone_prompt は {"prompt_audio": <file_id>, "prompt_text": "…"} の形式で、両方のキーが必須です。
• prompt_text はサンプル音声の正確な書き起こしで、句読点で終えます。

クローンしたボイスを使う

voice_id を /v1/audio/speech の voice、または /v1/t2a_v2 の voice_setting.voice_id(timber_weights[].voice_id も可)に指定します。

curl https://api.hop-base.com/v1/audio/speech \
  -H "Authorization: Bearer sk-your-key" \
  -H "Content-Type: application/json" \
  -d '{"model": "speech-2.8-turbo", "input": "Hello again.", "voice": "MyNarrator01"}' \
  --output cloned.mp3

• アップロードしたファイルは 1 回限りです。クローンが成功すると元音声とサンプル音声は自動削除されるため、再度クローンするにはアップロードし直します。
• クローンに失敗した場合はファイルが残り、再試行できます。
• アップロードから 24 時間以内に使われなかったファイルは自動削除されます。ファイルを削除してもクローン済みのボイスには影響しません。
• クローンから 7 日以内に合成に使われなかったボイスは自動削除され、クローン料金は発生しません。
• ボイスはお客様のアカウント専用です(エンタープライズではオーナー配下のメンバーのキーで共有)。他のアカウントは voice_id を知っていても使えません。

# クローンしたボイスの一覧("system" はシステムボイス、"all" は両方。"voice_generation" は常に空)
curl https://api.hop-base.com/v1/get_voice \
  -H "Authorization: Bearer sk-your-key" -H "Content-Type: application/json" \
  -d '{"voice_type": "voice_cloning"}'
# クローンしたボイスを削除
curl https://api.hop-base.com/v1/delete_voice \
  -H "Authorization: Bearer sk-your-key" -H "Content-Type: application/json" \
  -d '{"voice_type": "voice_cloning", "voice_id": "MyNarrator01"}'
# 未使用のアップロード: 一覧、取得、削除
curl "https://api.hop-base.com/v1/files/list?purpose=voice_clone" -H "Authorization: Bearer sk-your-key"
curl "https://api.hop-base.com/v1/files/retrieve?file_id=123456789" -H "Authorization: Bearer sk-your-key"
curl https://api.hop-base.com/v1/files/delete \
  -H "Authorization: Bearer sk-your-key" -H "Content-Type: application/json" \
  -d '{"file_id": 123456789, "purpose": "voice_clone"}'

課金

音声合成は課金文字数に基づいて課金されます。正式な値はネイティブレスポンスの extra_info.usage_characters です。OpenAI 互換エンドポイントは音声しか返さないため、同じ数値はコンソールの利用量レコードで tts_characters として確認してください。

Unicode の各文字を 1 と数え、漢字(CJK)はさらに 1 を加算するため、漢字 1 文字は 2 と数えます。句読点、スペース、絵文字、<#0.5#> のようなポーズ記号はそれぞれ 1 です。

• Hello, world. → 課金文字数 13
• 你好，世界 → 5 文字のうち漢字が 4 文字 → 課金文字数 9

400 で拒否されたリクエストや合成中に失敗したリクエストは課金されず、最後のイベントの前に終了したストリームも課金されません。100 万文字あたりの公式リスト価格は料金ページに、お使いのプランの適用レートはログイン後のモデルカタログに掲載されています。

アップロードとクローンは無料です。クローン料金はボイスの最初の合成が成功したときに 1 回だけ課金され、その合成の利用量レコードの内訳に voice_clone_activation が加わります。

プレビューの text は音声合成の文字数として課金されるだけで初回利用に数えず、失敗したリクエストは課金されません。料金は料金ページをご覧ください。

エラーとヒント

どちらのエンドポイントでも、エラーは 200 以外のステータスと {"error":{…}} で返り、公式の base_resp ではありません。ゲートウェイ自身の検証(モデル、テキスト、形式、速度、未知のフィールド)には code がないため、message を参照してください。

ボイスクローンの 400 には、使用済み・期限切れの file_id、既存の voice_id、範囲外の音声の長さ、text_validation の照合失敗があります。よくあるメッセージと対処:

400 voice id not exist                       存在しない、または削除・期限切れのボイス ID
400 file_id ... does not exist; uploaded files are single-use and expire 24 hours after upload    アップロードし直す
400 voice_id ... already exists             別の名前にするか古いボイスを削除
400 (クローン)音声の長さが範囲外            元音声は 10 秒〜5 分、サンプル音声は 8 秒未満
400 (クローン)音声認識の照合に失敗          text_validation 指定時のみ: 書き起こしを修正か accuracy を下げる
503 voice cloning is temporarily unavailable    時間をおいて再試行
400 sensitive content / >10% invalid chars   テキストを書き換えるか整理
400 invalid request parameters; check text, voice_setting and audio_setting (opus requires an explicit sample_rate)
413 request body exceeds the 1048576 byte limit (got N bytes)            ボディが 1 MiB 超
502 response_size_limit_exceeded (audio over 64 MiB)    stream: true、短いテキスト、低いビットレートを使用
ストリーム途中の失敗: 最後に data: {"base_resp":{...}} を送って切断、課金なし

Doubao 音声

ByteDance の Doubao 音声の 2 モデルは独立したプラン Doubao 音声 クラウド に属し、このプランを含むキーからのみ呼び出せます。既存のキーにこのプランを追加することもできます。使えるのは OpenAI 互換の POST /v1/audio/speech だけで、クリップ全体を同期的に返し、ストリーミングには対応しません。ネイティブの /v1/t2a_v2 はこの 2 モデルに対応しておらず、400 を返して /v1/audio/speech を使うよう案内します。

curl https://api.hop-base.com/v1/audio/speech \
  -H "Authorization: Bearer sk-your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seed-tts-2.0",
    "input": "你好，欢迎使用豆包语音合成。",
    "voice": "zh_female_vv_uranus_bigtts"
  }' \
  -o out.mp3

公式の openai SDK では、Base URL と model / voice の値を変えるだけです。seed-audio-1.0 では input にシーンとセリフを書きます。

from openai import OpenAI

client = OpenAI(base_url="https://api.hop-base.com/v1", api_key="sk-your-key")

response = client.audio.speech.create(
    model="seed-tts-2.0",
    voice="zh_female_vv_uranus_bigtts",
    input="你好，欢迎使用豆包语音合成。",
)
response.write_to_file("out.mp3")

# シーン音声:input に「シーンの説明 + セリフ」を書く。生成には約 10-30 秒
scene = client.audio.speech.create(
    model="seed-audio-1.0",
    voice="alloy",  # SDK では voice が必須。OpenAI のボイス名は未指定と同じ扱いで、声は説明で決まる
    input="先是一声手机震动的声音，随后一名男子（中青年，嗓音低沉）用严肃语气说道：“钟sir，你是什么时候被收买的？”",
    timeout=300,
)
scene.write_to_file("scene.mp3")

Doubao 音声のパラメータ

• seed-tts-2.0：voice を省略するか、alloy などの OpenAI 標準ボイス名を渡すと、テキストの言語に応じて既定ボイスを選びます。中国語は zh_female_vv_uranus_bigtts、その他の言語は en_female_dacey_uranus_bigtts です。ほかの 2.0 ボイス（ID が _uranus_bigtts で終わるもの。例：zh_male_m191_uranus_bigtts）も指定できます。
• seed-audio-1.0：input には上の例のように「シーンの説明 + セリフ」を書きます。voice を省略するか OpenAI 標準ボイス名を渡すと、声は説明に基づいて決まります。Doubao のボイス ID を指定することもできます。説明が長すぎると、生成する音声がモデルの最大長を超えて 400 duration_out_of_range になることがあります。短くしてから送り直してください。
• 出力：seed-tts-2.0 は 24 kHz モノラル（pcm は OpenAI と同じ 24 kHz・16 ビット・モノラルの生データ）、seed-audio-1.0 は 48 kHz ステレオです。
• ストリーミングには対応せず、stream_format を渡すと 400 です。ボイスとテキストの言語が合わず（英語ボイスで中国語だけのテキストを読むなど）音声がまったく生成されない場合は 400 no_audio です。
• さらに長いテキストはクライアント側で上限以内に分割し、1 つずつリクエストして音声をつなげてください。

所要時間と課金

• seed-tts-2.0：短い文で約 1-3 秒、2,000 文字で約 70 秒。
• seed-audio-1.0：約 10-30 秒。
• どちらもクリップ全体の生成が終わってから返ります。クライアントの読み取りタイムアウトは、同時実行数、タイムアウト、課金にある同期エンドポイントと同じく 300 秒以上にしてください。
• seed-tts-2.0 は入力文字数、seed-audio-1.0 は生成音声の長さで課金されます。公式価格は上のモデル表のとおりで、ご利用プランの実際の単価はサインイン後のモデル一覧でご確認ください。400 で拒否されたリクエストと、生成中に失敗したリクエストは課金されません。

上の表の条件を満たさない値は 400 を返します。同じ内容で再試行せず、エラーに従って修正してください。/v1/t2a_v2 で呼び出した場合も 400 です。402、404、429、503 の意味と対処は、上のエラーとヒントと同じです。

Doubao ボイスクローン

ご自身の録音から専用のボイスをクローンし、そのボイスで音声を合成できます。モデルは seed-icl-2.0(Doubao ボイスクローン 2.0)で、Doubao 音声と同じプラン Doubao 音声 クラウド に属し、このプランを含むキーからのみ呼び出せます。手順は 3 つです。POST /v1/voice_clone に録音を送って voice_id(hbv_ で始まる)を受け取り、それを POST /v1/audio/speech の voice に指定して合成します。不要になったら一覧で確認したり削除したりできます。

リクエスト形式は上の MiniMax のボイスクローンと異なります。録音は base64 で JSON に直接入れ、事前のファイルアップロードは不要です。また 3 つのクローン用エンドポイントはいずれも本文に "model": "seed-icl-2.0" が必須です。MiniMax のボイスクローンと Doubao のボイスクローンを併用する場合は、それぞれ別のキーを使ってください。

テスト期間中の枠:テスト期間中、クローンボイスは 1 アカウントにつき 1 つまで保持できます。別の声に替えるには、古いボイスを削除してからクローンし直すか、その voice_id を指定して再学習してください。クローンボイスの枠には限りがあり、満杯のときは 503 voice_capacity_full を返します。しばらくしてから再試行してください。

1. ボイスをクローンする

POST /v1/voice_clone は最大 16 MiB の JSON 本文を受け付けます。

• language に指定できる値:zh、en、ja、es、id、pt、de、fr、ko、it、th、vi、ru、fil、ms、ar、es-mx、pt-br、pl、tr、sv。
• クローンは同期的に完了します。実測では 17 秒の録音で約 33 秒かかりました。クライアントの読み取りタイムアウトは 300 秒以上にしてください。

# 録音を base64 にしてリクエスト本文に入れる(jq 1.6+)
jq -n --rawfile audio <(base64 < my_voice.wav | tr -d '\n') \
  '{model: "seed-icl-2.0", audio: $audio, language: "ja", demo_text: "こんにちは、これはクローンした私の声です。"}' > clone.json

curl https://api.hop-base.com/v1/voice_clone \
  -H "Authorization: Bearer sk-your-key" \
  -H "Content-Type: application/json" \
  --max-time 300 \
  -d @clone.json

{
  "voice_id": "hbv_k3m9x2p7q8r4t6w1y5z0a2b4",
  "status": "ready",
  "language": "ja",
  "remaining_trainings": 14,
  "created_at": 1792051200,
  "demo_audio": "<base64 音声>",
  "demo_audio_format": "wav"
}

2. クローンボイスで合成する

POST /v1/audio/speech で model を seed-icl-2.0、voice をクローンで得た voice_id にします。その他のパラメータ・形式・上限は seed-tts-2.0 と同じです(Doubao 音声のパラメータを参照)。input は 5,000 文字以内、response_format は mp3 / opus / aac / wav / pcm、speed は 0.5-2.0、出力は 24 kHz モノラルで、クリップ全体を同期的に返し、ストリーミングには対応しません。

curl https://api.hop-base.com/v1/audio/speech \
  -H "Authorization: Bearer sk-your-key" \
  -H "Content-Type: application/json" \
  -d '{"model": "seed-icl-2.0", "input": "会議は午後 3 時に変更になりました。", "voice": "hbv_k3m9x2p7q8r4t6w1y5z0a2b4"}' \
  -o cloned.mp3

• seed-icl-2.0 で使えるのはご自身がクローンしたボイスだけです。voice を省略したり、システムボイスや OpenAI のボイス名を指定したりすると 400 voice_required を返します。
• クローンボイスは seed-icl-2.0 専用で、他のモデルに指定すると 400 unknown_voice を返します。
• クローンボイスはお客様のアカウント専用です(エンタープライズではオーナー配下のメンバーのキーで共有)。他のアカウントは voice_id を知っていても使えません。

3. 一覧と削除

どちらのエンドポイントも無料で、本文には同じく model が必要です。

# クローンボイスの一覧(voice_id を付けるとその 1 件だけ)
curl https://api.hop-base.com/v1/get_voice \
  -H "Authorization: Bearer sk-your-key" -H "Content-Type: application/json" \
  -d '{"model": "seed-icl-2.0"}'
# → {"voices":[{"voice_id":"hbv_k3m9x2p7q8r4t6w1y5z0a2b4","status":"ready","language":"ja","remaining_trainings":14,"created_at":1792051200}]}

# クローンボイスを削除
curl https://api.hop-base.com/v1/delete_voice \
  -H "Authorization: Bearer sk-your-key" -H "Content-Type: application/json" \
  -d '{"model": "seed-icl-2.0", "voice_id": "hbv_k3m9x2p7q8r4t6w1y5z0a2b4"}'
# → {"voice_id":"hbv_k3m9x2p7q8r4t6w1y5z0a2b4","deleted":true}

voice_id を付けた get_voice はそのボイスのオブジェクトを直接返します(フィールドはクローンのレスポンスと同じで、試聴音声は含みません)。削除した voice_id は以後使えなくなり、枠はすぐに空きます。

ボイスクローンの課金

• クローンボイスでの合成は入力文字数で課金され、公式価格は 1 万文字あたり ¥3 で seed-tts-2.0 と同じです。
• 試聴:demo_text も同じ価格で文字数課金されます。
• クローン自体、一覧、削除は無料で、現在クローン料金はかかりません。失敗したリクエストは課金されません。

ご利用プランの実際の単価はサインイン後のモデル一覧でご確認ください。

ボイスクローンのエラー

エラー形式は他のエンドポイントと同じで、200 以外のステータスと {"error":{"message","type","code"}} です。パラメータ検証のエラーには code がないため、message を確認してください。

次のステップ

• 利用可能なモデル:すべてのモデル ID とそのプラン
• 音声を作成(API リファレンス)
• MiniMax Hailuo(海螺) H3 動画 API
• エラーコードと再試行
• 同時実行数、タイムアウト、課金