Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.supertoneapi.com/llms.txt

Use this file to discover all available pages before exploring further.

このドキュメントは英語の原文から自動翻訳されています。表現に不自然な箇所がある場合があります。正確な内容は英語の原文もあわせてご確認ください。
カスタムボイスとは、アカウントに紐付くボイスクローンのことです。一度登録すれば、プリセットボイスとまったく同じように動作します。同じTTSエンドポイント、同じパラメータが使えますが、専用のエンドポイント群を介して扱われ、作成元のアカウントからのみ呼び出すことができます。 カスタムボイスは、2つの方法で作成できます。
  • Supertone Playで作成 — サンプルをアップロードし、UIからクローニングします。
  • API経由で作成 — オーディオファイルを添えてPOST /v1/custom-voices/cloned-voiceを呼び出します。
どちらの方法でも同じ種類のボイスが生成されます。Playで作成したクローンボイスはlist_custom_voicesに表示され、API経由で作成したボイスはPlayにも表示されます。同期処理は不要です。
API経由のボイスクローニングは、Freeプランではご利用いただけません。Play上でのクローニングは、すべての有料プランで利用可能です。

​
エンドポイント概要

エンドポイント目的
POST /v1/custom-voices/cloned-voiceアップロードされたオーディオサンプルから新しいクローンを作成します。
GET /v1/custom-voicesアカウント上のすべてのカスタムボイスを一覧取得します。
GET /v1/custom-voices/search名前や説明でカスタムボイスをフィルタリングします。
GET /v1/custom-voices/{voice_id}単一のカスタムボイスを取得します。
PATCH /v1/custom-voices/{voice_id}名前または説明を更新します。
DELETE /v1/custom-voices/{voice_id}カスタムボイスを完全に削除します。

​
クローンを作成する

クローニングしたいボイスの、ノイズの少ないオーディオサンプルをアップロードします。 
import os
from supertone import Supertone

with Supertone(api_key=os.environ["SUPERTONE_API_KEY"]) as client:
    with open("voice_sample.wav", "rb") as f:
        response = client.custom_voices.create_cloned_voice(
            files={"file_name": "voice_sample.wav", "content": f.read()},
            name="Hana — narrator voice",
            description="Calm, mid-pitch female voice for audiobook narration.",
        )

    print("Created custom voice:", response.voice_id)
レスポンスには新しいvoice_idが含まれます。TTS呼び出しに渡す値となりますので、保存しておいてください。

​
アップロードの制約

  • 形式： WAVまたはMP3
  • サイズ： 3 MB未満
  • 名前： 最大100文字
クリーンでモノラルかつ単一話者のオーディオ（5〜30秒）が最も良いクローン結果につながります。BGM、複数話者、強いルームノイズは避けてください。

​
一覧と検索

# List all
result = client.custom_voices.list_custom_voices(page_size=20)
for voice in result.items or []:
    print(voice.voice_id, voice.name)

# Search by name or description
result = client.custom_voices.search_custom_voices(name="narrator")

​
TTSでカスタムボイスを使用する

クローンが登録されたら、プリセットボイスとまったく同じ要領でtext_to_speech.create_speechを呼び出してください。カスタムのvoice_idを渡すだけです。 
response = client.text_to_speech.create_speech(
    voice_id=CUSTOM_VOICE_ID,
    text="The first chapter begins on a quiet rainy morning.",
    language="en",
    model="sona_speech_2",
)
カスタムボイスは、プリセットボイスと同じvoice_settings、output_format、include_phonemes、normalized_textの各フィールドに対応しています。

​
更新と削除

# Rename / update description
client.custom_voices.edit_custom_voice(
    voice_id=CUSTOM_VOICE_ID,
    name="Hana — narrator (v2)",
    description="Improved take with cleaner room tone.",
)

# Permanently delete
client.custom_voices.delete_custom_voice(voice_id=CUSTOM_VOICE_ID)

// Rename / update description
await client.customVoices.editCustomVoice({
  voiceId: CUSTOM_VOICE_ID,
  name: "Hana — narrator (v2)",
  description: "Improved take with cleaner room tone.",
});

// Permanently delete
await client.customVoices.deleteCustomVoice({ voiceId: CUSTOM_VOICE_ID });

​
重要な制約

  • アカウントスコープ。 カスタムボイスは作成元のアカウントからのみ呼び出せます。IDを知っていても、他人のカスタムボイスを呼び出すと403 Forbiddenが返ります。
  • クレジット消費は同じ。 カスタムボイスの呼び出しは、プリセットボイスと同じレートでクレジットを消費します。
  • 権限と開示。 アップロードするボイスをクローニングする権利を必ずお持ちであることをご確認ください。お使いの地域でのAI生成音声およびエンドユーザーへの開示に関する規則も併せてご確認ください。

​
関連項目

プリセットボイス

Supertoneのプリセットボイスライブラリを閲覧・検索しましょう。

エンドツーエンドの例

カスタムボイスのクローニング、一覧取得、TTSでの利用までを通して試します。

APIリファレンス

リクエストとレスポンスの完全なスキーマ。

コストと使用量

コストを見積もり、ボイスごとの使用量を監視しましょう。