88API 音声 API:TTS と STT
Grok と Gemini の音声モデル接続ガイド:/v1/audio/speech による音声合成、WebSocket ストリーミング音声合成、Grok リアルタイム音声対話、/v1/audio/transcriptions とチャット音声入力による文字起こし。全音声、出力形式、リクエストフィールド、cURL、OpenAI SDK、Python、Node.js のサンプルを掲載。
88API は Grok と Gemini の 2 系統の音声モデルを提供しています。音声合成(TTS)と音声認識(STT)ではモデル、エンドポイント、フィールドがそれぞれ異なるため、下表を参考に選択してください。
モデルとエンドポイント
| 機能 | モデル | エンドポイント | 課金基準 |
|---|---|---|---|
| 音声合成 | grok-tts | POST /v1/audio/speech | 入力文字数 |
| ストリーミング音声合成 | grok-tts | WebSocket /v1/tts | 入力文字数 |
| リアルタイム音声対話 | grok-voice-latest、grok-voice-3.0 | WebSocket /v1/realtime | 通話時間 |
| 音声合成 | gemini-3.8-flash-tts | Gemini ネイティブの generateContent(音声のダウンロードリンクを返す) | Token |
| 音声認識 | grok-stt | POST /v1/audio/transcriptions | 音声の長さ |
| 音声認識 | gemini-3-stt、gemini-3.5-stt、gemini-3.5-transcribe | POST /v1/audio/transcriptions、POST /v1/chat/completions(音声入力)、または Gemini ネイティブの generateContent | Token |
- 料金はコンソールのモデル広場の表示をご確認ください。トークンのグループは
语音模型(コンソールに表示されるグループ名)または自動グループを選択してください。 - 音声モデルは上表のエンドポイントでのみ使用できます。チャット、Responses、Messages エンドポイントで TTS モデルや
grok-sttを呼び出すと400が返り、正しいエンドポイントを使うよう案内されます。 /v1/audio/translations(音声を英語に翻訳)エンドポイントは提供していません。/v1/audio/speechは完全な音声を一度に返します。ストリーミング出力には対応しておらず、stream_format: "sse"を指定すると400が返ります。合成しながら再生したい場合は、Grok ストリーミング音声合成 を使用してください。
ベース URL と認証:
Base URL: https://api.88api.ai/v1
Authorization: Bearer $API_KEYGrok 音声合成(grok-tts)
cURL
curl --fail-with-body https://api.88api.ai/v1/audio/speech \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "grok-tts",
"input": "88API 音声合成サービスへようこそ。",
"voice": "eve",
"language": "ja",
"response_format": "mp3"
}' \
--output speech.mp3成功時のレスポンスは JSON ではなく音声バイナリです。そのままファイルに書き込んでください。Windows のコマンドラインで -d に非 ASCII テキストを直接渡すと文字化けしやすいため、リクエスト本文を UTF-8 ファイルに保存し、--data-binary @request.json で送信してください。
リクエストフィールド
| フィールド | 型 | 必須 | 既定値 | 説明 |
|---|---|---|---|---|
model | string | はい | — | grok-tts |
input | string | はい | — | 読み上げるテキスト。空にはできません。後述の表現タグを挿入できます |
voice | string | いいえ | eve | 下の音声一覧を参照。大文字小文字は区別しません。OpenAI の alloy、nova などの音声名は 400 を返します |
response_format | string | いいえ | mp3 | mp3、wav、pcm、mulaw、alaw。opus、aac、flac は 400 を返します |
language | string | いいえ | 自動認識 | 言語コード。例:zh、en、ja、ko、fr、ru、vi、pt-BR。言語を固定すると自動認識より安定します |
speed | number | いいえ | 1.0 | 話速の倍率。範囲は 0.7–1.5、範囲外は 400 を返します |
sample_rate | integer | いいえ | 24000 | 8000、16000、22050、24000、44100、48000。それ以外の値は 400 を返します |
bit_rate | integer | いいえ | 128000 | MP3 のみ有効:32000、64000、96000、128000、192000 |
text_normalization | boolean | いいえ | false | true の場合、数字・略語・記号を話し言葉の読み方に変換してから合成します |
replace | object | いいえ | — | 発音の置換表。例:{"nginx": "engine x"}。キーが原文、値が読み方です |
sample_rate、bit_rate、text_normalization、replace は Grok の拡張フィールドで、OpenAI SDK では extra_body で渡します。instructions フィールドは grok-tts では効果がありません。声の表現は表現タグで制御してください。
出力形式
response_format | Content-Type | 説明 |
|---|---|---|
mp3 | audio/mpeg | 既定は 24 kHz、128 kbps。そのまま再生できます |
wav | audio/wav | 16-bit モノラル。後編集に適しています |
pcm | audio/pcm | 16-bit モノラルの raw PCM。ヘッダーなしのため、サンプルレートに合わせて解析が必要です |
mulaw | audio/basic | G.711 μ-law。電話用途で、通常 sample_rate: 8000 と組み合わせます |
alaw | audio/alaw | G.711 A-law。電話用途で、通常 sample_rate: 8000 と組み合わせます |
pcm、mulaw、alaw はブラウザーで直接再生できません。Web で再生する場合は mp3 または wav を使用してください。
音声
すべての音声で対応言語を読み上げられます。名前の大文字小文字は区別しません。スタイルの説明は xAI 公式の音声一覧に基づいています。自分の原稿で 2〜3 種類を試聴してから固定することをおすすめします。
| 音声 | スタイル | 用途 |
|---|---|---|
eve | エネルギッシュで明るい、イギリス英語アクセント(既定) | 汎用 |
ara | 温かく親しみやすい | 汎用 |
rex | 自信があり明瞭 | 汎用 |
sal | なめらかでバランスが良い | 汎用 |
leo | 威厳があり力強い、イギリス英語アクセント | 汎用 |
carina | 柔らかく共感的で、心を落ち着かせる | ウェルネス、サポート |
zagan | 力強くドラマチック | キャラクター、ナレーション |
helix | 大胆で勢いがある | 実況・解説、ポッドキャスト |
orion | 深みがあり映画的 | ナレーション、オーディオブック |
luna | 優しく忍耐強い | 教育、アシスタント |
iris | 親しみやすく明るい | 営業、サポート |
altair | 上品で洗練されている | 広告、ナレーション |
zenith | シャープで集中力がある | 営業、広告 |
perseus | 落ち着いていて信頼できる | 広告、ナレーション |
helios | 明るく活力にあふれる | アシスタント、ウェルネス |
lux | 落ち着いていて聡明 | ウェルネス、ナレーション |
kepler | 独創的で人を惹きつける | 広告、ポッドキャスト |
rigel | 正確でプロフェッショナル、オーストラリア英語アクセント | アシスタント、サポート |
cosmo | 明るく好奇心旺盛で、わかりやすい | 教育、ポッドキャスト |
celeste | 思いやりがあり安心感を与える | サポート、アシスタント |
ursa | 親しみやすく温かく、頼れる | アシスタント、ポッドキャスト |
sirius | 機転が利き遊び心がある | 実況・解説、キャラクター |
lumen | 温かく、表現が明瞭 | 教育、広告 |
castor | 親しみやすく気さく | 営業、サポート |
naksh | 温かく聡明、インド英語アクセント | アシスタント、サポート |
atlas | 自信があり主導力を感じさせる | 営業、アシスタント |
aurora | 穏やかで安定している | サポート、アシスタント |
liora | 穏やかで地に足が着いている | ウェルネス、アシスタント |
上の一覧にない音声名は 400 を返し、エラーメッセージに利用可能な音声が示されます。
表現タグ
input にタグを挿入すると、間、笑い声、ささやきなどの表現を制御できます。詳しくは xAI 公式ドキュメント を参照してください。
| 種類 | タグ |
|---|---|
| 挿入型(発声させたい位置に置く) | [pause] [long-pause] [laugh] [chuckle] [giggle] [cry] [sigh] [breath] [inhale] [exhale] [tsk] [tongue-click] [lip-smack] [hum-tune] |
| 囲み型(ペアでテキストを囲む) | <whisper> <soft> <loud> <build-intensity> <decrease-intensity> <higher-pitch> <lower-pitch> <slow> <fast> <emphasis> <sing-song> <singing> |
{
"model": "grok-tts",
"voice": "eve",
"input": "ドアを開けると、[pause] それはそこにあった。[laugh] <whisper>これは秘密だよ。</whisper> <slow><soft>おやすみ。</soft></slow>"
}囲み型タグは必ずペアで使用し、入れ子にできます。1〜2 文字だけを囲むより、文全体を囲むほうが自然に聞こえます。
Python(OpenAI SDK)
from openai import OpenAI
client = OpenAI(
api_key="YOUR_88API_KEY",
base_url="https://api.88api.ai/v1",
)
with client.audio.speech.with_streaming_response.create(
model="grok-tts",
voice="eve",
input="88API 音声合成サービスへようこそ。",
response_format="mp3",
extra_body={"language": "ja", "sample_rate": 44100},
) as response:
response.stream_to_file("speech.mp3")Node.js(OpenAI SDK)
import fs from "node:fs";
import OpenAI from "openai";
const client = new OpenAI({
apiKey: process.env.API_KEY,
baseURL: "https://api.88api.ai/v1",
});
const speech = await client.audio.speech.create({
model: "grok-tts",
voice: "ara",
input: "Hello from 88API. [laugh] <whisper>This part is a secret.</whisper>",
response_format: "wav",
});
fs.writeFileSync("speech.wav", Buffer.from(await speech.arrayBuffer()));Grok ストリーミング音声合成(WebSocket)
大規模言語モデルがテキストを生成しながら読み上げる場面など、できるだけ早く再生を始めたい用途に適しています。テキストは複数回に分けて送信でき、音声は合成されたそばから返されます。最初の音声は通常 0.3 秒ほどで届きます。モデル、音声、表現タグ、料金は grok-tts と同じです。
接続
wss://api.88api.ai/v1/tts?model=grok-tts&voice=eve&codec=mp3&language=ja
Authorization: Bearer $API_KEYパラメーターはすべて接続 URL のクエリ文字列に指定します。
| パラメーター | 必須 | 既定値 | 説明 |
|---|---|---|---|
model | はい | — | grok-tts |
voice | いいえ | eve | 上の音声一覧を参照 |
codec | いいえ | mp3 | mp3、wav、pcm、mulaw(ulaw とも指定可)、alaw。opus、aac、flac には対応していません |
language | いいえ | 自動認識 | 言語コード。例:zh、en、ja |
sample_rate | いいえ | 24000 | 8000、16000、22050、24000、44100、48000 |
bit_rate | いいえ | 128000 | MP3 のみ有効:32000、64000、96000、128000、192000 |
speed | いいえ | 1.0 | 話速の倍率。範囲は 0.7–1.5 |
text_normalization | いいえ | false | true または false。true の場合、数字・略語・記号を話し言葉の読み方に変換してから合成します |
メッセージ
接続後は、双方とも JSON テキストメッセージを送信します。
| 方向 | メッセージ | 説明 |
|---|---|---|
| クライアントから送信 | {"type": "text.delta", "delta": "..."} | 読み上げるテキストを追加します。続けて何回でも送信できます |
| クライアントから送信 | {"type": "text.done"} | このセグメントのテキストを送り終えたことを示します |
| サーバーから返信 | audio.delta | delta は Base64 エンコードされた音声チャンクです。受信順に連結すると完全な音声になります |
| サーバーから返信 | audio.done | このセグメントの音声がすべて返されました |
| サーバーから返信 | error | このセグメントの合成に失敗しました。詳細はメッセージに含まれます |
実際のレスポンス例:
{"type": "audio.delta", "delta": "//PExABLjDncBN4ZECBPfcTHl40IKQ..."}
{"type": "audio.done", "trace_id": "a52a926b-726f-439c-bbeb-5d741dd497ad"}audio.doneを受信した後も接続は維持されます。再接続せずに、次のセグメントのtext.deltaとtext.doneを続けて送信できます。- 実際に音声が合成されたセグメントのテキストの文字数に応じて課金され、料金は
grok-ttsと同じです。合成に失敗したセグメントと、テキストを送信しなかった接続には課金されません。 - JSON テキストメッセージのみに対応しています。バイナリフレームは送信しないでください。
- パラメーターは接続を確立する前に検証されます。
voiceが音声一覧にない場合(OpenAI の音声名を含む)や、codec、sample_rate、speedなどの値が無効な場合は、ハンドシェイクで直接 HTTP400が返され、WebSocket 接続は確立されません。エラーメッセージには利用可能な値が示されます。
Python
websockets 14 以降が必要です(pip install websockets)。
import asyncio
import base64
import json
import websockets
API_KEY = "YOUR_88API_KEY"
URL = "wss://api.88api.ai/v1/tts?model=grok-tts&voice=eve&codec=mp3&language=ja"
async def main():
async with websockets.connect(
URL, additional_headers={"Authorization": f"Bearer {API_KEY}"}
) as ws:
segments = [
["88API ストリーミング", "音声合成へようこそ。", "テキストを生成しながら読み上げます。"],
["同じ接続で次のセグメントを続けて合成できます。"],
]
for i, pieces in enumerate(segments):
for text in pieces:
await ws.send(json.dumps({"type": "text.delta", "delta": text}))
await ws.send(json.dumps({"type": "text.done"}))
with open(f"part{i + 1}.mp3", "wb") as f:
async for message in ws:
event = json.loads(message)
if event["type"] == "audio.delta":
f.write(base64.b64decode(event["delta"]))
elif event["type"] == "audio.done":
break
elif event["type"] == "error":
raise RuntimeError(event)
asyncio.run(main())Node.js
ws ライブラリを使用します(npm install ws)。
import fs from "node:fs";
import WebSocket from "ws";
const url = "wss://api.88api.ai/v1/tts?model=grok-tts&voice=ara&codec=mp3&language=ja";
const ws = new WebSocket(url, {
headers: { Authorization: `Bearer ${process.env.API_KEY}` },
});
const chunks = [];
ws.on("open", () => {
for (const delta of ["ドアを開けると、", "[pause] それはそこにあった。", "<whisper>これは秘密だよ。</whisper>"]) {
ws.send(JSON.stringify({ type: "text.delta", delta }));
}
ws.send(JSON.stringify({ type: "text.done" }));
});
ws.on("message", (data) => {
const event = JSON.parse(data.toString());
if (event.type === "audio.delta") {
chunks.push(Buffer.from(event.delta, "base64"));
} else if (event.type === "audio.done") {
fs.writeFileSync("speech.mp3", Buffer.concat(chunks));
ws.close();
} else if (event.type === "error") {
console.error(event);
ws.close();
}
});Grok 音声認識(grok-stt)
cURL
multipart/form-data で音声をアップロードします。multipart boundary は cURL または SDK に生成させ、Content-Type: multipart/form-data ヘッダーを手動で設定しないでください。
curl --fail-with-body https://api.88api.ai/v1/audio/transcriptions \
-H "Authorization: Bearer $API_KEY" \
-F "model=grok-stt" \
-F "language=ja" \
-F "keyterm=88API" \
-F "file=@./meeting.mp3"レスポンス:
{
"text": "88API音声合成サービスへようこそ。今日は2026年10月17日です。"
}リクエストフィールド
| フィールド | 型 | 必須 | 既定値 | 説明 |
|---|---|---|---|---|
file | file | はい | — | 音声または動画ファイル。mp3、wav、ogg、opus、flac、aac、m4a、mp4、mkv に対応し、ブラウザーで録音した webm も使用できます |
model | string | はい | — | grok-stt |
response_format | string | いいえ | json | json、text、verbose_json。srt、vtt は 400 を返します |
language | string | いいえ | 自動認識 | 言語コード。例:zh、en、ja、yue(広東語)。指定すると認識が安定します |
format | boolean | いいえ | false | true の場合、話し言葉の数字や金額などを書き言葉の表記に変換します。language も同時に指定する必要があります |
keyterm | string | いいえ | — | 優先的に認識させたい固有名詞(製品名、人名など)。複数回指定でき、1 回につき 1 語です。例:88API のような製品名 |
filler_words | boolean | いいえ | false | true の場合、「えー」「あの」などのフィラーを残します。既定では除去されます |
OpenAI の prompt、temperature、timestamp_granularities は grok-stt では効果がなく、無視されます。固有名詞を正確に認識させたい場合は keyterm を使用してください。
レスポンス形式
response_format | Content-Type | 内容 |
|---|---|---|
json | application/json | {"text": "..."} |
text | text/plain | プレーンテキスト |
verbose_json | application/json | text、language、duration(秒)、および単語単位のタイムスタンプ words(word、start、end) |
verbose_json の例:
{
"task": "transcribe",
"language": "ja",
"duration": 7.08,
"text": "88API音声合成サービスへようこそ。今日は2026年10月17日です。",
"words": [
{ "word": "88API", "start": 0.08, "end": 1.264 },
{ "word": "音", "start": 1.344, "end": 1.524 }
]
}Python(OpenAI SDK)
from openai import OpenAI
client = OpenAI(
api_key="YOUR_88API_KEY",
base_url="https://api.88api.ai/v1",
)
with open("meeting.mp3", "rb") as audio_file:
result = client.audio.transcriptions.create(
model="grok-stt",
file=audio_file,
language="ja",
response_format="verbose_json",
extra_body={"format": "true", "keyterm": "88API"},
)
print(result.text, result.duration)Node.js(OpenAI SDK)
import fs from "node:fs";
import OpenAI from "openai";
const client = new OpenAI({
apiKey: process.env.API_KEY,
baseURL: "https://api.88api.ai/v1",
});
const transcription = await client.audio.transcriptions.create({
model: "grok-stt",
file: fs.createReadStream("meeting.mp3"),
language: "ja",
});
console.log(transcription.text);Grok リアルタイム音声対話(grok-voice)
1 本の WebSocket 接続で、モデルとリアルタイムに音声で対話します。テキストまたはマイク音声を送信すると、モデルが音声で直接返答し、同時に文字起こしも返します。音声アシスタント、電話サポート、会話練習などの用途に適しています。
| モデル | 説明 |
|---|---|
grok-voice-latest | 常に最新バージョンを指します。現在は grok-voice-3.0 |
grok-voice-3.0 | 固定バージョン |
接続
wss://api.88api.ai/v1/realtime?model=grok-voice-latest
Authorization: Bearer $API_KEYイベントプロトコルは xAI Realtime と同じです。接続に成功すると、サーバーがまず session.created と conversation.created を送信し、その後クライアントがセッションを設定して対話を始めます。
- 既定では、音声は Base64 エンコードして JSON イベントに入れて送受信します。バイナリ転送に切り替えることもでき、その場合は生の音声を WebSocket のバイナリフレームで直接やり取りします。バイナリ音声転送 を参照してください。
- ブラウザーの WebSocket では
Authorizationリクエストヘッダーを設定できず、フロントエンドで API Key を公開すべきでもありません。自分のサーバーで接続を確立し、音声をブラウザーやアプリに中継してください。 - 音声形式:入力・出力とも PCM16(16-bit リトルエンディアン)、24 kHz、モノラルです。
セッションの設定
{
"type": "session.update",
"session": {
"voice": "eve",
"instructions": "あなたは 88API の音声アシスタントです。簡潔に答えてください。",
"turn_detection": { "type": "server_vad" }
}
}| フィールド | 説明 |
|---|---|
voice | 返答に使う音声。grok-tts の 28 種類の音声と同じです(上の音声一覧を参照)。大文字小文字は区別しません。既定は ara |
instructions | システム指示。役割、口調、回答の長さなどを設定します |
turn_detection | {"type": "server_vad"}:話し終えたことをサーバーが検出すると自動で返答します。null(既定):音声の確定と返答のリクエストを手動で行う必要があります |
voiceが音声一覧にない場合(OpenAI の音声名を含む)はerrorイベントを受信し、error.paramはsession.voiceになります。このsession.updateは全体が反映されず、接続は維持されます。修正してから再送信してください。session.updatedでは音声は返されません。現在の音声は、接続時のsession.createdにのみ表示されます。例:既定のxai_ara。
クライアントイベント
| イベント | 説明 |
|---|---|
session.update | 音声、システム指示、ターン検出を設定します |
conversation.item.create | テキストメッセージを 1 件送信します(content 内の input_text) |
response.create | モデルに返答をリクエストします |
input_audio_buffer.append | 音声を追加します。audio は Base64 エンコードされた PCM16 データで、1 回あたり 100 ms 程度を推奨します |
input_audio_buffer.commit | 追加済みの音声を確定し、1 件のユーザーメッセージにします。turn_detection が null のときに使用します |
テキストの送信:
{"type": "conversation.item.create", "item": {"type": "message", "role": "user", "content": [{"type": "input_text", "text": "一言で自己紹介してください。"}]}}
{"type": "response.create"}音声の送信:input_audio_buffer.append を連続して送信します。server_vad が有効な場合、話し終えた後の一定の無音で自動的に返答します。turn_detection が null の場合は、音声を送り終えてから input_audio_buffer.commit と response.create を送信します。
サーバーイベント
| イベント | 説明 |
|---|---|
session.created、session.updated | セッションが作成された、設定が反映された |
input_audio_buffer.speech_started / speech_stopped | server_vad が発話の開始、発話の終了を検出した |
conversation.item.input_audio_transcription.completed | ユーザー音声の認識テキスト。transcript に入ります |
response.output_audio.delta | 返答音声のチャンク。delta は Base64 エンコードされた PCM16 24 kHz モノラル |
response.output_audio_transcript.delta / .done | 返答の文字起こし。.done の transcript が全文です |
response.done | このターンの返答が終了 |
ping | ハートビート。無視してかまいません |
error | エラー。詳細は error.message と error.code にあります |
上のセッション設定でこのテキストメッセージを送信したときの実際のレスポンス(抜粋):
{"type": "response.output_audio_transcript.delta", "delta": "88APIの音声アシスタントです。"}
{"type": "response.output_audio.delta", "delta": "<Base64 音声>"}
{"type": "response.output_audio_transcript.done", "transcript": "88APIの音声アシスタントです。"}
{"type": "response.output_audio.done"}
{"type": "response.done", "response": {"status": "completed", "output": [{"type": "message", "role": "assistant", "content": [{"type": "audio", "transcript": "88APIの音声アシスタントです。"}]}]}}課金
- 通話時間に応じて課金されます。接続の確立から切断まで秒単位で計測し、話していないアイドル時間も含まれるため、使い終わったらすぐに接続を閉じてください。料金はコンソールのモデル広場をご確認ください。
- ユーザーのテキストメッセージ(
input_textを含むconversation.item.create)1 件ごとに少額の料金が別途かかります。音声入力とモデルの音声返答は個別には課金されません。 - 残高またはトークンの利用枠が 1 分間の通話料金に満たない場合、接続直後に
error(codeはinsufficient_user_quota)を受信して切断されます。通話中に残高がなくなった場合は、30 秒以内に同じerrorを受信し、その後クローズコード1008で接続が切断されます。
Python
websockets 14 以降が必要です(pip install websockets)。次の例はテキストメッセージを 1 件送信し、音声の返答を reply.wav に保存します。
import asyncio
import base64
import json
import wave
import websockets
API_KEY = "YOUR_88API_KEY"
URL = "wss://api.88api.ai/v1/realtime?model=grok-voice-latest"
async def main():
async with websockets.connect(
URL, additional_headers={"Authorization": f"Bearer {API_KEY}"}
) as ws:
await ws.send(json.dumps({
"type": "session.update",
"session": {
"voice": "eve",
"instructions": "あなたは 88API の音声アシスタントです。簡潔に答えてください。",
"turn_detection": {"type": "server_vad"},
},
}))
await ws.send(json.dumps({
"type": "conversation.item.create",
"item": {
"type": "message",
"role": "user",
"content": [{"type": "input_text", "text": "一言で自己紹介してください。"}],
},
}))
await ws.send(json.dumps({"type": "response.create"}))
audio = bytearray()
async for message in ws:
event = json.loads(message)
if event["type"] == "response.output_audio.delta":
audio += base64.b64decode(event["delta"])
elif event["type"] == "response.output_audio_transcript.done":
print("文字起こし:", event["transcript"])
elif event["type"] == "response.done":
break
elif event["type"] == "error":
raise RuntimeError(event)
with wave.open("reply.wav", "wb") as f:
f.setnchannels(1)
f.setsampwidth(2)
f.setframerate(24000)
f.writeframes(bytes(audio))
asyncio.run(main())音声を送信する場合は、24 kHz、16-bit、モノラルの音声を分割して送信します。上の server_vad を有効にしたセッションを例にすると、テキストを送信する 2 つのメッセージを次のように置き換えられます。
with wave.open("question.wav", "rb") as f: # 24 kHz、16-bit、モノラル
pcm = f.readframes(f.getnframes())
pcm += b"\x00" * 48000 # 末尾に 1 秒の無音を追加し、server_vad に発話の終了を判定させる
for i in range(0, len(pcm), 4800): # 1 回あたり 100 ms
await ws.send(json.dumps({
"type": "input_audio_buffer.append",
"audio": base64.b64encode(pcm[i:i + 4800]).decode(),
}))マイクからリアルタイムに入力する場合は、取得した音声をそのまま送信すればよく、無音を追加する必要はありません。
Node.js
ws ライブラリを使用します(npm install ws)。この例では server_vad を無効にし、テキストを送信した後に手動で返答をリクエストして、返答を reply.wav に保存します。
import fs from "node:fs";
import WebSocket from "ws";
const ws = new WebSocket("wss://api.88api.ai/v1/realtime?model=grok-voice-latest", {
headers: { Authorization: `Bearer ${process.env.API_KEY}` },
});
const send = (event) => ws.send(JSON.stringify(event));
const chunks = [];
// PCM16 24 kHz モノラルのデータに WAV ヘッダーを付ける
function toWav(pcm, rate = 24000) {
const header = Buffer.alloc(44);
header.write("RIFF", 0);
header.writeUInt32LE(36 + pcm.length, 4);
header.write("WAVEfmt ", 8);
header.writeUInt32LE(16, 16);
header.writeUInt16LE(1, 20);
header.writeUInt16LE(1, 22);
header.writeUInt32LE(rate, 24);
header.writeUInt32LE(rate * 2, 28);
header.writeUInt16LE(2, 32);
header.writeUInt16LE(16, 34);
header.write("data", 36);
header.writeUInt32LE(pcm.length, 40);
return Buffer.concat([header, pcm]);
}
ws.on("open", () => {
send({
type: "session.update",
session: { voice: "rex", instructions: "一言で答えてください。", turn_detection: null },
});
send({
type: "conversation.item.create",
item: {
type: "message",
role: "user",
content: [{ type: "input_text", text: "フランスの首都はどこですか?" }],
},
});
send({ type: "response.create" });
});
ws.on("message", (data) => {
const event = JSON.parse(data.toString());
switch (event.type) {
case "response.output_audio.delta":
chunks.push(Buffer.from(event.delta, "base64"));
break;
case "response.output_audio_transcript.delta":
process.stdout.write(event.delta);
break;
case "response.done":
fs.writeFileSync("reply.wav", toWav(Buffer.concat(chunks)));
ws.close();
break;
case "error":
console.error(event.error);
ws.close();
break;
}
});バイナリ音声転送
session.update で入力と出力の transport を "binary" に設定すると、生の PCM 音声が WebSocket のバイナリフレームとして直接送受信され、Base64 のエンコード・デコードが不要になります。
{
"type": "session.update",
"session": {
"turn_detection": null,
"audio": {
"input": { "format": { "type": "audio/pcm", "rate": 24000 }, "transport": "binary" },
"output": { "format": { "type": "audio/pcm", "rate": 24000 }, "transport": "binary" }
}
}
}- 送信:各バイナリフレームは PCM16、24 kHz、モノラルの生の音声データです。1 フレームあたり 100 ms(4800 バイト)を推奨します。
input_audio_buffer.appendの代わりに使います。 - 受信:返答音声はバイナリフレームで返され、
response.output_audio.deltaイベントは送られなくなります。受信した順に連結してください。 input_audio_buffer.commit、response.createなどの制御イベント、およびsession.updated、文字起こし、response.doneなどのサーバーイベントは、引き続き JSON テキストフレームです。- 課金方法は変わりません。
Python の例:音声で質問を送信し、音声の返答を reply.wav に保存します。
import asyncio
import json
import wave
import websockets
API_KEY = "YOUR_88API_KEY"
URL = "wss://api.88api.ai/v1/realtime?model=grok-voice-latest"
PCM = {"type": "audio/pcm", "rate": 24000}
async def main():
async with websockets.connect(
URL, additional_headers={"Authorization": f"Bearer {API_KEY}"}
) as ws:
await ws.send(json.dumps({
"type": "session.update",
"session": {
"voice": "eve",
"turn_detection": None,
"audio": {
"input": {"format": PCM, "transport": "binary"},
"output": {"format": PCM, "transport": "binary"},
},
},
}))
with wave.open("question.wav", "rb") as f: # 24 kHz、16-bit、モノラル
pcm = f.readframes(f.getnframes())
for i in range(0, len(pcm), 4800): # 1 フレーム 100 ms、生の PCM をそのまま送信
await ws.send(pcm[i:i + 4800])
await ws.send(json.dumps({"type": "input_audio_buffer.commit"}))
await ws.send(json.dumps({"type": "response.create"}))
audio = bytearray()
async for message in ws:
if isinstance(message, bytes): # バイナリフレーム:返答音声
audio += message
continue
event = json.loads(message) # テキストフレーム:制御イベント
if event["type"] == "response.output_audio_transcript.done":
print("文字起こし:", event["transcript"])
elif event["type"] == "response.done":
break
elif event["type"] == "error":
raise RuntimeError(event)
with wave.open("reply.wav", "wb") as f:
f.setnchannels(1)
f.setsampwidth(2)
f.setframerate(24000)
f.writeframes(bytes(audio))
asyncio.run(main())Gemini 音声合成
Gemini の音声合成は現在 gemini-3.8-flash-tts のみで、Gemini ネイティブエンドポイントで呼び出します。/v1/audio/speech には対応していません(500「モデルが音声を返しませんでした」が返され、課金はされません)。従来の gemini-3.1-flash-tts、gemini-3.8-flash-lite-tts、gemini-2.5-flash-tts、gemini-2.5-pro-tts は提供を終了しました。/v1/audio/speech やストリーミング音声が必要な場合は、Grok 音声合成を使ってください。
cURL
キーは同じく 88API の API キーで、x-goog-api-key リクエストヘッダーに設定できます。
curl --fail-with-body "https://api.88api.ai/v1beta/models/gemini-3.8-flash-tts:generateContent" \
-H "x-goog-api-key: $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"contents": [{ "role": "user", "parts": [{ "text": "88API 音声合成サービスへようこそ。<laugh> 今日はいい天気ですね。" }] }],
"generationConfig": {
"responseModalities": ["AUDIO"],
"speechConfig": {
"voiceConfig": { "prebuiltVoiceConfig": { "voiceName": "Kore" } }
}
}
}'レスポンスとダウンロード
レスポンスは JSON で、音声データは含まれません。代わりに candidates[0].content.parts[0].text に音声のダウンロードリンクが Markdown リンク形式で返されます(リンクの文字列は常に中国語の「生成音频」(音声を生成)です)。
{
"candidates": [{
"content": {
"role": "model",
"parts": [{ "text": "[生成音频](https://example.com/contents/xxxxxxxx.wav)" }]
},
"finishReason": "STOP"
}]
}- テキストから丸かっこ内の URL を取り出してダウンロードしてください。ダウンロードに API キーは不要です。音声は WAV ファイル(24 kHz、16-bit、モノラル)です。
- リンクは数時間しか保持されません。期限が切れるとダウンロードできないため、レスポンスを受け取ったらすぐにダウンロードして保存してください。
- 入力と出力の Token で課金されます。料金はコンソールのモデル広場の表示を確認してください。
- ストリーミングエンドポイント
POST /v1beta/models/gemini-3.8-flash-tts:streamGenerateContent?alt=sseも呼び出せますが、音声は分割して返されません。合成が完了すると、1 つのイベントで同じダウンロードリンクが返されます。
読み上げのルール
- 一字一句読み上げ:テキスト内のすべての文字が読み上げられます。「楽しげな口調で言って:」のような説明をテキストに書かないでください。その文も読み上げられてしまいます。
- トーンはテキスト内の山かっこタグで制御します。タグ自体は読み上げられません。例:
<laugh>(笑い)、<short pause>(短い間)、<whispers>(ささやき)、<sigh>(ため息)。
音声
speechConfig.voiceConfig.prebuiltVoiceConfig.voiceName で指定します。30 種類のプリセット音声があります。スタイルの説明は Google 公式の音声一覧に基づいています。すべての音声で日本語を含む多くの言語を読み上げられます。
| 音声 | スタイル | 性別 |
|---|---|---|
Achernar | 柔らかい | 女性 |
Achird | 親しみやすい | 男性 |
Algenib | しゃがれた | 男性 |
Algieba | なめらか | 男性 |
Alnilam | 力強い | 男性 |
Aoede | 軽やか | 女性 |
Autonoe | 明るい | 女性 |
Callirrhoe | 気さく | 女性 |
Charon | 知的 | 男性 |
Despina | なめらか | 女性 |
Enceladus | 息づかいのある | 男性 |
Erinome | 明瞭 | 女性 |
Fenrir | 興奮気味 | 男性 |
Gacrux | 成熟した | 女性 |
Iapetus | 明瞭 | 男性 |
Kore | 力強い | 女性 |
Laomedeia | 陽気 | 女性 |
Leda | 若々しい | 女性 |
Orus | 力強い | 男性 |
Puck | 陽気 | 男性 |
Pulcherrima | 率直 | 女性 |
Rasalgethi | 知的 | 男性 |
Sadachbia | 活発 | 男性 |
Sadaltager | 博識 | 男性 |
Schedar | 落ち着いた | 男性 |
Sulafat | 温かい | 女性 |
Umbriel | 気さく | 男性 |
Vindemiatrix | 優しい | 女性 |
Zephyr | 明るい | 女性 |
Zubenelgenubi | カジュアル | 男性 |
迷った場合は、まず Kore(女性)と Charon(男性)を試してください。音声と言語の最新情報は Google Gemini-TTS 公式ドキュメント を参照してください。
2 人の会話
speechConfig 内の voiceConfig を multiSpeakerVoiceConfig に置き換え、最大 2 人の話者にそれぞれ音声を指定します。テキストは各行を「名前: セリフ」だけにし、「TTS the following conversation…」のような説明は付けないでください(読み上げられてしまいます)。
{
"contents": [{
"role": "user",
"parts": [{ "text": "Joe: How's it going today Jane?\nJane: Not too bad, how about you?" }]
}],
"generationConfig": {
"responseModalities": ["AUDIO"],
"speechConfig": {
"multiSpeakerVoiceConfig": {
"speakerVoiceConfigs": [
{ "speaker": "Joe", "voiceConfig": { "prebuiltVoiceConfig": { "voiceName": "Charon" } } },
{ "speaker": "Jane", "voiceConfig": { "prebuiltVoiceConfig": { "voiceName": "Kore" } } }
]
}
}
}
}返し方は 1 人の場合と同じで、WAV のダウンロードリンクが返されます。
Gemini 音声認識
| モデル | 説明 |
|---|---|
gemini-3-stt | 推奨。通常の文字起こし、会議録、字幕向け |
gemini-3.5-stt | より難しい音声向け。単価は高め |
gemini-3.5-transcribe | 文字起こし専用モデル。85 以上の言語を自動認識し、1 回あたり最長約 1 時間の音声に対応。高速 |
3 つのモデルの呼び出し方法は同じで、以下の例の model を他のモデル名に変えるだけです。gemini-3.5-transcribe の相違点は gemini-3.5-transcribe を参照してください。呼び出し方法は 3 通りあります:/v1/audio/transcriptions へのファイルアップロード(推奨)、チャットエンドポイントでの音声入力、Gemini ネイティブエンドポイントです。
ファイルをアップロードして文字起こし(推奨)
grok-stt と同じく multipart/form-data を使用します。Content-Type: multipart/form-data ヘッダーを手動で設定しないでください。
curl --fail-with-body https://api.88api.ai/v1/audio/transcriptions \
-H "Authorization: Bearer $API_KEY" \
-F "model=gemini-3-stt" \
-F "language=ja" \
-F "file=@./meeting.mp3"レスポンス:
{
"text": "88API音声合成サービスへようこそ。今日は2026年10月17日です。"
}| フィールド | 型 | 必須 | 既定値 | 説明 |
|---|---|---|---|---|
file | file | はい | — | 音声ファイル。mp3、wav、m4a、ogg、flac などの一般的な形式に対応、最大 25 MB |
model | string | はい | — | gemini-3-stt、gemini-3.5-stt または gemini-3.5-transcribe |
response_format | string | いいえ | json | json({"text": "..."})、text(プレーンテキスト)、verbose_json(task、language、duration を追加)。srt、vtt は 400 を返します |
language | string | いいえ | 自動認識 | 言語コード。例:zh、en、yue(広東語) |
prompt | string | いいえ | — | 場面、人名、用語などのヒント。認識精度の向上に役立ちます。gemini-3.5-transcribe では効果がありません |
verbose_json には単語単位のタイムスタンプ(words)やセグメント(segments)は含まれません。単語単位のタイムスタンプが必要な場合は grok-stt、または gemini-3.5-transcribe のネイティブエンドポイントを使用してください。ファイルが 25 MB を超えると 400 が返るため、圧縮(例:16 kHz モノラル MP3 に変換)または分割してから文字起こししてください。
Python(OpenAI SDK):
from openai import OpenAI
client = OpenAI(
api_key="YOUR_88API_KEY",
base_url="https://api.88api.ai/v1",
)
with open("meeting.mp3", "rb") as audio_file:
result = client.audio.transcriptions.create(
model="gemini-3-stt",
file=audio_file,
language="ja",
)
print(result.text)チャットエンドポイント(音声入力)
音声を Base64 でチャットメッセージに入れ、テキストの指示に従って文字起こし結果を出力させます。指示の中で場面、人名、用語を説明すると、より正確に認識できます。
cURL
まず音声を Base64 に変換し、input_audio に入れます。
AUDIO_B64=$(base64 < meeting.mp3 | tr -d '\n')
cat > request.json <<EOF
{
"model": "gemini-3-stt",
"messages": [{
"role": "user",
"content": [
{ "type": "text", "text": "この音声を文字起こしし、文字起こし結果のみを出力してください。" },
{ "type": "input_audio", "input_audio": { "data": "$AUDIO_B64", "format": "mp3" } }
]
}]
}
EOF
curl --fail-with-body https://api.88api.ai/v1/chat/completions \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
--data-binary @request.json文字起こし結果は choices[0].message.content に入ります。format には mp3、wav などの音声形式を指定します。
Python(OpenAI SDK)
import base64
from openai import OpenAI
client = OpenAI(
api_key="YOUR_88API_KEY",
base_url="https://api.88api.ai/v1",
)
with open("meeting.mp3", "rb") as f:
audio_b64 = base64.b64encode(f.read()).decode()
completion = client.chat.completions.create(
model="gemini-3-stt",
messages=[{
"role": "user",
"content": [
{"type": "text", "text": "この音声を文字起こしし、文字起こし結果のみを出力してください。"},
{"type": "input_audio", "input_audio": {"data": audio_b64, "format": "mp3"}},
],
}],
)
print(completion.choices[0].message.content)Node.js(OpenAI SDK)
import fs from "node:fs";
import OpenAI from "openai";
const client = new OpenAI({
apiKey: process.env.API_KEY,
baseURL: "https://api.88api.ai/v1",
});
const audio = fs.readFileSync("meeting.mp3").toString("base64");
const completion = await client.chat.completions.create({
model: "gemini-3-stt",
messages: [{
role: "user",
content: [
{ type: "text", text: "この音声を文字起こしし、文字起こし結果のみを出力してください。" },
{ type: "input_audio", input_audio: { data: audio, format: "mp3" } },
],
}],
});
console.log(completion.choices[0].message.content);Gemini ネイティブエンドポイント
{
"contents": [{
"role": "user",
"parts": [
{ "text": "この音声を文字起こしし、文字起こし結果のみを出力してください。" },
{ "inlineData": { "mimeType": "audio/wav", "data": "<Base64 音声>" } }
]
}]
}POST https://api.88api.ai/v1beta/models/gemini-3-stt:generateContent に送信し、リクエストヘッダーに x-goog-api-key: $API_KEY を付けます。
チャットエンドポイントとネイティブエンドポイントは音声を Base64 でリクエスト本文に入れるため、短めの録音に適しています。ファイルが大きい場合は、ファイルアップロードによる文字起こしを使用してください。廃止済みの gemini-2.5-stt、gemini-3.6-stt は gemini-3-stt、gemini-3.5-stt または grok-stt に切り替えてください。
gemini-3.5-transcribe
文字起こし専用モデルです。音声だけを送ればよく、テキストの指示は不要で、受け付けません。
/v1/audio/transcriptions:languageには BCP-47 言語コード(例:zh、en、yue)を指定します。無効なコードは400を返します。promptは効果がありません。モデルは認識した言語を返さないため、verbose_jsonのlanguageは指定した値になり、指定しない場合は空文字列です。- チャットエンドポイント:メッセージ内のテキストは無視され、課金もされません。
input_audioだけを送れば十分です。systemメッセージやreasoning_effortを含めると400が返ります。 - ネイティブエンドポイント:
generationConfig.audioTranscriptionConfigで言語、カスタム語彙、話者分離、単語単位のタイムスタンプを指定できます。 - リアルタイムのストリーミング文字起こしには対応していません。
ネイティブエンドポイントの例:
curl --fail-with-body "https://api.88api.ai/v1beta/models/gemini-3.5-transcribe:generateContent" \
-H "x-goog-api-key: $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"contents": [{
"role": "user",
"parts": [{ "inlineData": { "mimeType": "audio/wav", "data": "<Base64 音声>" } }]
}],
"generationConfig": {
"audioTranscriptionConfig": { "diarization": true, "wordTimestamp": true }
}
}'audioTranscriptionConfig のフィールド | 型 | 説明 |
|---|---|---|
languageCodes | string[] | 音声の言語。BCP-47 コード、例:["zh"]。指定しない場合は自動認識 |
customVocabulary | string[] | 優先的に認識させたい固有名詞、例:["88API"]。これらの語は入力使用量に含まれます |
diarization | boolean | 話者を区別し、各セグメントの結果に speakerLabel を付けます(実験的機能) |
wordTimestamp | boolean | 単語単位のタイムスタンプ words を返します(実験的機能) |
mode | string | SMART:スマート文字起こしモード。処理時間が長くなります。diarization、wordTimestamp と同時に使用すると 400 が返ります |
2 人の会話を文字起こしした実際のレスポンス(candidates[0].content.parts、抜粋):
[
{
"text": "How's it going today, Jane?",
"audioTranscription": {
"text": "How's it going today, Jane?",
"speakerLabel": "spk:0",
"words": [
{ "word": "How's", "startOffset": "0.200s", "endOffset": "0.300s" },
{ "word": "it", "startOffset": "0.300s", "endOffset": "0.400s" }
]
}
},
{
"text": "Not too bad. How about you?",
"audioTranscription": {
"text": "Not too bad. How about you?",
"speakerLabel": "spk:1",
"words": [
{ "word": "Not", "startOffset": "2.100s", "endOffset": "2.200s" }
]
}
}
]話者分離を有効にしない場合、文字起こし結果全体は parts[0].text に入ります。話者分離と単語単位のタイムスタンプは実験的機能です。中国語と英語が混在する音声では主要でない言語の部分が欠落することがあるため、完全なテキストが必要な場合はこの 2 つを無効にしてください。
主なエラー
| ステータス | 主な原因 | 対処 |
|---|---|---|
400 | input / file の不足、音声名が音声一覧にない(OpenAI の音声名を含む)、未対応の形式やサンプルレート、speed が範囲外、テキストが長すぎる、アップロードしたファイルが 25 MB を超えている | エラーメッセージと本ページのフィールド説明に沿ってリクエストを修正してください |
400 | チャット、Responses、Messages エンドポイントで音声モデルを呼び出した | 本ページの対応するエンドポイントを使用してください |
400 | テキストが安全ポリシーでブロックされた(PROHIBITED_CONTENT) | テキストを修正して再試行してください。同じ内容を再送しても解決しません |
401 | API Key がない、または無効 | Bearer Token を確認し、ブラウザーのフロントエンドでキーを公開しないでください |
429 | レート、残高、容量の制限 | 指数バックオフで再試行し、アカウント残高を確認してください |
500 / 502 / 503 | サーバーまたは上流の一時的な異常 | 回数を限って再試行し、続く場合は request ID を添えてサポートへ連絡してください |
エラーレスポンスの request id は調査の手がかりになるため、ログに残してください。API Key、非公開の音声、機密性の高い文字起こし内容は記録しないでください。