音声合成API

音声合成APIは、テキストとvoice_idを受け取り、MP3またはWAV音声を 返します。Base URLはhttps://api.kitschlabs.comで、公開APIへのリクエストは xi-api-keyヘッダーで認証します。

API概要

項目	値
Base URL	https://api.kitschlabs.com
認証	xi-api-key: <API_KEY>
デフォルト出力	mp3_44100_128 (audio/mpeg)
追加出力	wav_24000 (audio/wav)

language_codeスキーマはen、ko、ja、zhを受け付けます。利用できる 言語と音声はアカウントによって異なる場合があるため、GET /v1/voicesの レスポンスから選択してください。

どのエンドポイントを使用しますか？

Method	Endpoint	用途
GET	/v1/voices	利用可能な音声を取得
POST	/v1/text-to-speech/{voice_id}	完成した音声ファイルを生成

どのように認証しますか？

すべての公開エンドポイントにxi-api-keyを送信します。例の<API_KEY>を 発行されたキーに置き換え、実際のキーをコードやログに残さないでください。

xi-api-key: <API_KEY>

音声一覧を取得するには？

curl "https://api.kitschlabs.com/v1/voices" \
  --header "xi-api-key: <API_KEY>"

音声合成には/v1/voicesレスポンスのvoice_idを使用します。表示名は変更される 可能性があるため、表示名ではなくvoice_idを保存してください。

音声を生成するには？

POST /v1/text-to-speech/{voice_id}にJSONを送信し、レスポンスボディを ファイルに保存します。

cURL

curl --request POST \
  "https://api.kitschlabs.com/v1/text-to-speech/<VOICE_ID>?output_format=mp3_44100_128" \
  --header "xi-api-key: <API_KEY>" \
  --header "Content-Type: application/json" \
  --data '{
    "text": "今日も良い一日をお過ごしください。",
    "language_code": "ja"
  }' \
  --output speech.mp3

Python

import os

import requests

response = requests.post(
    "https://api.kitschlabs.com/v1/text-to-speech/<VOICE_ID>",
    params={"output_format": "mp3_44100_128"},
    headers={
        "xi-api-key": os.environ["KITSCH_API_KEY"],
        "Content-Type": "application/json",
    },
    json={
        "text": "今日も良い一日をお過ごしください。",
        "language_code": "ja",
    },
    timeout=120,
)
response.raise_for_status()

with open("speech.mp3", "wb") as audio_file:
    audio_file.write(response.content)

JavaScript

import { writeFile } from "node:fs/promises";

const response = await fetch(
  "https://api.kitschlabs.com/v1/text-to-speech/<VOICE_ID>?output_format=mp3_44100_128",
  {
    method: "POST",
    headers: {
      "xi-api-key": process.env.KITSCH_API_KEY,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      text: "今日も良い一日をお過ごしください。",
      language_code: "ja",
    }),
  },
);

if (!response.ok) {
  throw new Error(`${response.status}: ${await response.text()}`);
}

await writeFile("speech.mp3", Buffer.from(await response.arrayBuffer()));

どのフィールドを送信しますか？

フィールド	型	必須	説明
text	string	はい	合成するテキスト。空文字列は不可
language_code	string	いいえ	en、ko、ja、zhのいずれか
instruct	string	いいえ	話し方に関する自然言語の指示
speed	number	いいえ	発話速度。0.25から4
voice_settings.emotion_code	string	いいえ	利用可能な感情を選択

対応しているテキストタグ

textには[laughter]、[sigh]、[en]、[wa]、[hnn]タグを含めることが できます。その他の角括弧タグはリクエストエラーとして拒否されます。

{
  "text": "本当ですか？ [laughter] 私もまったく予想していませんでした。"
}

エラーにはどのように対応しますか？

エラーレスポンスには通常、detail.status、detail.message、 detail.request_idが含まれます。

{
  "detail": {
    "status": "rate_limited",
    "message": "Rate limit exceeded. Please retry later.",
    "request_id": "<REQUEST_ID>"
  }
}

ステータス	意味	推奨対応
400·422	リクエスト値が不正	body、tag、範囲を修正
401	APIキーがない、または無効	キーとxi-api-keyヘッダーを確認
402	利用可能なcreditが不足	請求の状態を確認
404	音声が見つからない、またはアクセス不可	voice_idとアカウントの権限を確認
429	アカウントのリクエスト上限を超過	Retry-Afterに従いbackoffを適用
5xx	一時的なサーバーエラー	request IDを記録し、回数を制限して再試行

成功時とエラー時のレスポンスヘッダーに含まれるx-kitsch-request-idを ログに残すと、サポートへの問い合わせや障害追跡に利用できます。