qianwen-audio-tts

Qwen Audio TTS（Text-to-Speech）

Qwen TTS モデルを使用して、テキストから自然な音声を合成します。 このスキルは QianWen-AI/qianwen-ai の一部です。

スキルディレクトリ

このスキルの内部ファイルを使用して、実行や情報の確認を行います。デフォルトのパスで見つからない場合、または詳細が必要な場合は、必要に応じてリファレンスファイルを読み込んでください。

場所	用途
scripts/tts.py	Qwen TTS（HTTP API）— qwen3-tts-, qwen-audio-3.0-tts-
scripts/tts_cosyvoice.py	CosyVoice（WebSocket / HTTP NRT）— dashscope SDK が必要です
references/cosyvoice-guide.md	CosyVoice のセットアップ、音声、例、エラー
references/execution-guide.md	フォールバック：curl（標準、指示、ストリーミング）、コード生成
references/prompt-guide.md	音声用テキストの書式、指示テンプレート、音声の選択
references/api-guide.md	API 補足
references/sources.md	公式ドキュメントの URL

セキュリティ

API キーや認証情報を平文で出力してはいけません。 常に変数参照を使用してください（シェルでは $DASHSCOPE_API_KEY、Python では os.environ["DASHSCOPE_API_KEY"]）。認証情報の確認や検出は、必ず非平文で行ってください。報告するのはステータス（例：「設定済み」／「未設定」、「有効」／「無効」）のみとし、値を出力してはいけません。秘密情報が含まれる可能性のある .env ファイルや設定ファイルの内容を表示してはいけません。

API キーが設定されていない場合、ユーザーに直接キーの提供を求めてはいけません。 代わりに、プレースホルダー（DASHSCOPE_API_KEY=sk-your-key-here）を含む .env ファイルの作成を支援し、QianWen Console から取得した実際のキーに置き換えるようユーザーに案内してください。実際のキーの値を書き込むのは、ユーザーから明示的に依頼された場合に限ります。

キーの互換性

PAYG（sk-ws-...、旧形式の sk-...）と Token Plan（sk-sp-...）の両方のキーに対応しています。キーの種類は、キーを公開せずに判定します。

python3 -c "
import sys; sys.path.insert(0, 'scripts')
from qianwen_lib import detect_api_key_type
print(detect_api_key_type('scripts/qianwen_lib.py'))
"

出力	意味
token-plan	Token Plan キー — 以下の Token Plan カタログに掲載されたモデルのみを使用します。
payg	従量課金キー — すべてのモデルカタログを利用できます。
not-set	キーが設定されていません。

Token Plan の場合は、最新の Token Plan モデルカタログを取得して読み込み、scripts/tts.py では掲載されているモデルを正確に指定してください。CDN にアクセスできない場合は、ローカルのフォールバックを使用してください。

実行前：キーに基づくモデルの判定

TTS スクリプトを呼び出す前に、キーのプレフィックスからキーの種類を判定します（scripts/qianwen_lib.py を使用して、キーを公開せずに確認します）。次に、スクリプトとの互換性、おすすめ、デフォルトを確認するため、最新の Qwen audio TTS モデルカタログを取得して読み込みます。CDN にアクセスできない場合は、ローカルのフォールバックを使用してください。

Token Plan がサポートするモデルは限られています。上記のリファレンスに掲載されたモデルを正確に使用してください。モデルが利用可能かどうかを推測したり、試しに呼び出したりしてはいけません。PAYG の場合は、以下に進んでください。

モデルの選択

モデルの選択、おすすめ、またはデフォルト設定を行う前に、上記の Qwen audio TTS モデルカタログを参照してください。カタログにはモデル一覧、モデルの基本情報、スクリプトや音声との互換性、おすすめ、デフォルトが記載されています。

⚠️ 重要：モデルカタログは特定時点のスナップショットであり、古くなっている可能性があります。モデルの提供状況は頻繁に変わります。モデルを選ぶ際は、必ず公式モデル一覧を確認し、最新かつ正式なカタログに基づいて判断してください。

モデルの詳細：特定のモデルについて詳しく知りたい場合は、ユーザーに https://www.qianwenai.com/models/<model-name> を案内してください。<model-name> は正確なモデル ID に置き換えてください。変更したり、推測したりしてはいけません。

動的なモデル照会：qianwen-model-selector スキルまたは QianWen CLI（qianwen models info <model>）を利用できる場合は、リアルタイムのモデル情報を取得するために使用してください。CLI の使用には認証が必要です。ログイン方法については、qianwen-usage スキルを参照してください。

利用可能な音声

最新のモデルと音声の互換性およびデフォルト設定については、上記の Qwen オーディオ TTS モデルカタログを使用してください。音声の完全な一覧については、sources.md に記載されている公式の音声リストへのリンクを使用してください。

カスタム音声（v3.5 で必須）

cosyvoice-v3.5 モデルにはカスタム音声 ID が必要です。作成するには、次の手順に従います。

1. 音声クローンにアクセスします
2. 10〜20 秒の、ノイズのない音声サンプルをアップロードします
3. カスタム音声 ID を取得します
4. --voice <id> またはリクエスト JSON の "voice": "<id>" で渡します

実行

⚠️ 複数の成果物：1 回のセッションで複数のファイルを生成する場合は、上書きを防ぐため、各ファイル名に数値のサフィックスを付ける必要があります（例：out_1.wav、out_2.wav）。

Qwen TTS（HTTP API）— tts.py

前提条件

• API キー：Key Compatibility にある非平文検出機能を使用してください。変数の存在確認に置き換えないでください。キーが見つからない場合は、利用可能であれば qianwen-ops-auth を使用するか、ユーザーに .env で DASHSCOPE_API_KEY／QIANWEN_API_KEY を設定するよう案内してください。スキルは個別にインストールできます。
• Python 3.9 以降（標準ライブラリのみ、pip install は不要です）

環境の確認

初回実行前に、Python が利用可能であることを確認してください。

python3 --version  # must be 3.9+

python3 が見つからない場合は、python --version または py -3 --version を試してください。Python が利用できない場合、またはバージョンが 3.9 未満の場合は、execution-guide.md の Path 2（curl） に進んでください。

デフォルト：スクリプトを実行

スクリプトのパス：スクリプトは、このスキルのディレクトリ（SKILL.md を含むディレクトリ）内の scripts/ サブディレクトリにあります。最初にこのスキルのインストールディレクトリを特定し、その後、必ずスクリプトの実行に完全な絶対パスを使用してください。 スクリプトが現在の作業ディレクトリにあると想定しないでください。実行前にディレクトリを切り替えるために cd を使用しないでください。

実行時の注意：すべてのスクリプトはフォアグラウンドで実行し、標準出力が得られるまで待機してください。バックグラウンドでは実行しないでください。

検索：まず python3 <this-skill-dir>/scripts/tts.py --help を実行して、利用可能な引数を確認してください。

python3 <this-skill-dir>/scripts/tts.py \
  --request '{"text":"Hello, this is a test.","voice":"longanlingxin"}' \
  --output output/qianwen-audio-tts/ \
  --print-response

引数	説明
--request '{...}'	JSON リクエスト本文
--file path.json	ファイルからリクエストを読み込みます
--output path	音声とレスポンス JSON をディレクトリに保存します。または、音声ファイルのパス（例：speech.mp3）を指定します。上書きを避けるため、呼び出しごとに異なるファイル名を使用してください
--print-response	レスポンスを標準出力に表示します
--model ID	モデルを上書きします
--voice NAME	音声を上書きします
--format	Qwen-Audio-TTS NRT モデルの音声形式（デフォルトは mp3、wav、pcm）
--sample-rate	Qwen-Audio-TTS NRT モデルのサンプリングレート（Hz）（デフォルト：24000）

モデルの優先順位：--model CLI フラグ ＞ --request JSON 内の "model" フィールド ＞ 組み込みのデフォルト。

結果の確認

• 終了コードが 0 で、出力に output.audio フィールドを含む有効な JSON がある → 成功
• ゼロ以外の終了コード、HTTP エラー、空のレスポンス、またはエラー JSON → 失敗
• 実行後の確認：出力音声ファイルが存在し、サイズが 0 ではないことを確認します（ls -la <output_dir>）
• 必須 — 標準エラーのシグナル確認：結果を確認した後、コマンドの標準エラー出力に [ACTION_REQUIRED] または [UPDATE_AVAILABLE] がないか調べます。いずれかのシグナルがある場合は、ユーザーに応答する前に、以下の 更新の確認 の指示に必ず従ってください。

失敗した場合

スクリプトが失敗した場合は、以下の診断表とエラー出力を照合して、解決方法を判断してください。一致するものがない場合は、代替手順として execution-guide.md を参照してください：curl コマンド（Path 2 — 標準、指示、ストリーミング）、コード生成（Path 3）、自律的な解決（Path 5）。

Python をまったく利用できない場合 → execution-guide.md の Path 2（curl）に直接進んでください。

---

CosyVoice — tts_cosyvoice.py

CosyVoice には dashscope SDK が必要です。クイックスタート：

pip install dashscope>=1.25.17
python3 <this-skill-dir>/scripts/tts_cosyvoice.py --text "Hello"

完全ガイド：cosyvoice-guide.md（セットアップ、音声、例、エラー）

エラーパターン	診断	解決方法
command not found: python3	Python が PATH にありません	python または py -3 を試してください。Python 3.9 以降がインストールされていない場合はインストールしてください
Python 3.9+ required	スクリプトのバージョンチェックに失敗しました	Python 3.9 以降にアップグレードしてください
型ヒント付近の SyntaxError	Python < 3.9	Python 3.9 以降にアップグレードしてください
QIANWEN_API_KEY/DASHSCOPE_API_KEY not found	API キーがありません	QianWen Console でキーを取得します。.env に追加してください：echo 'DASHSCOPE_API_KEY=sk-...' >> .env。または、利用可能な場合は qianwen-ops-auth を実行してください
HTTP 401	キーが無効、または一致していません	qianwen-ops-auth を実行してください（平文ではないことの確認のみ）。キーが有効であることを確認してください
SSL: CERTIFICATE_VERIFY_FAILED	SSL 証明書の問題（プロキシ／企業ネットワーク）	macOS：Install Certificates.command を実行してください。それ以外の場合は SSL_CERT_FILE 環境変数を設定してください
URLError / ConnectionError	ネットワークに接続できません	インターネット接続を確認してください。プロキシ経由の場合は HTTPS_PROXY を設定してください
HTTP 429	レート制限に達しました	待ってから、バックオフを適用して再試行してください
HTTP 5xx	サーバーエラー	バックオフを適用して再試行してください
PermissionError	出力を書き込めません	--output を使って、書き込み可能なディレクトリを指定してください

クイックリファレンス

リクエストフィールド（Qwen3-TTS HTTP API — tts.py）

フィールド	型	説明
text	string	必須 — 合成するテキスト（最大 600 文字）
voice	string	必須 — 音声 ID（例：Cherry、Ethan）
model	string	モデル ID。現在のデフォルトについては、上記のモデルカタログを確認してください
language_type	string	Auto、Chinese、English、Japanese、Korean、French、German など
instructions	string	トーン／スタイルの指示。現在のモデルとの互換性と制限については、上記のモデルカタログを確認してください
optimize_instructions	bool	true の場合、システムが instructions を意味的に強化し、より自然な音声にします。instructions の設定が必要です。デフォルト：false
stream	bool	ストリーミングを有効にします（Base64 チャンク）

リクエストフィールド（CosyVoice NRT API — tts_cosyvoice.py）

フィールド	型	説明
text	string	必須 — 合成するテキスト（1 回の呼び出しにつき最大 20,000 文字）
voice	string	必須 — 音声 ID（モデル固有。音声一覧を参照）
model	string	モデル ID。現在のデフォルトについては、上記のモデルカタログを確認してください
instruction	string	音声を制御する自由形式の指示。現在のモデルとの互換性については、上記のモデルカタログを確認してください
language_hints	list	対象言語のヒント：zh、en、fr、de、ja、ko、ru、pt、th、id、vi など
format	string	音声フォーマット：mp3（デフォルト）、wav、pcm、opus
sample_rate	int	サンプルレート（Hz）：8000、16000、22050（デフォルト）、24000、44100、48000

レスポンスフィールド

フィールド	説明
audio_url	生成された音声の URL（24 時間有効）
audio_format	フォーマット（例：wav）
sample_rate	サンプルレート（例：24000）
usage	文字数の使用量

重要な注意事項

• text：1 リクエストあたり最大 600 文字（Qwen3-TTS）。最大 20,000 文字（CosyVoice／Qwen-Audio-TTS NRT）。
• instructions / instruction model compatibility：上記のモデルカタログを確認し、選択したモデルについて記載されているパラメーター形式を使用してください。
• language_type（Qwen3-TTS）：複数言語が混在する場合は Auto を指定します。発音を改善するには言語を指定してください。
• language_hints（CosyVoice／Qwen-Audio-TTS）：合成品質を改善するには、対象言語コード（zh、en など）を指定してください。
• audio_url：有効期間は 24 時間です。速やかにダウンロードしてください。
• リアルタイム／ストリーミング TTS：WebSocket ベースのリアルタイム TTS（CosyVoice、qwen3-tts-flash-realtime）には、WebSocket クライアントが必要です。このスキルの対象は HTTP ベースの非リアルタイム API です。リアルタイムストリーミングのユースケースについては、sources.md の公式ドキュメントを参照してください。

スキル間の連携

生成した音声を別のスキル（例：動画生成の音声オーバーレイ）に渡す場合：

• audio_url を直接渡してください — スクリプトが URL のプレフィックスを検出し、再アップロードせずにそのまま渡します。
• ローカル再生や API を使わない操作の場合にのみ、audio_file を使用してください。

エラー処理

エラー	原因	対処方法
401 Unauthorized	API キーが無効または未設定です	利用可能であれば qianwen-ops-auth を実行してください。それ以外の場合は、キーを設定するようユーザーに促してください（平文でないことの確認のみ）
400	パラメーターが無効です（text／voice がありません）	リクエスト本文を検証してください
429 ／ 5xx	レート制限またはサーバーエラーです	バックオフして再試行してください

使用状況と課金：使用状況、無料枠の上限、課金情報を直接確認するには、qianwen-usage スキルを使用してください。代わりに、ユーザーは QianWen コンソールにアクセスできます： 使用状況の分析 | 従量課金 | トークンプランのサブスクリプション

使用状況／課金／コンソールの URL を捏造、推測、または組み立ててはなりません。 このスキルに記載されている正確なリンクのみを提示してください。ここに記載されていない URL を作成してはなりません。

出力先

現在の作業ディレクトリを優先してください。既定のサブディレクトリ：./output/qianwen-audio-tts/。

書き込み禁止：このスキルのインストールディレクトリ、または skills/ 階層内に出力ファイルを書き込んではなりません。生成したすべてのコンテンツは、現在の作業ディレクトリ内の output/、またはユーザー指定のパスに保存してください。

更新の確認（実行後に必須）

スクリプトの実行後、stderr にアクションを示すシグナルがないか確認してください。スクリプトは更新状況を自動検出し、構造化されたシグナルを出力します。これらのシグナルには必ず対応してください。このセクションは、ユーザーが更新の確認を明示的に依頼した場合にも適用されます。

シグナル：[ACTION_REQUIRED] qianwen-update-check skill is not installed

stderr にこのシグナルが含まれている場合は、以下の選択肢をユーザーに提示し、続行する前に返答を待ってください。黙ってスキップしてはなりません。

更新確認スキルがインストールされていません。このスキルを使うと、QianWen-AI/qianwen-ai の新機能やバグ修正について最新情報を確認できます。

1. 今すぐインストール — インストールコマンドを実行します
2. 今回はスキップ — 今回は何もしません
3. 今後は通知しない — この確認を今後表示しないようにします

ユーザーの返答後：

• ユーザーが 1 を選択 → npx skills add QianWen-AI/qianwen-ai --skill qianwen-update-check -y を実行し、続けて python3 <this-skill-scripts-dir>/gossamer.py --dismiss を実行します
• ユーザーが 2 を選択 → python3 <this-skill-scripts-dir>/gossamer.py --dismiss を実行してから、通常どおり続行します
• ユーザーが 3 を選択 → python3 <this-skill-scripts-dir>/gossamer.py --never-install を実行してから、通常どおり続行します

シグナル：[UPDATE_AVAILABLE]

stderr にこのシグナルが含まれている場合は、stderr に表示されたバージョン情報と更新コマンドを含む簡潔な更新通知を、回答に追加してください。

stderr に通知がない場合

stderr に [ACTION_REQUIRED] も [UPDATE_AVAILABLE] も含まれていない場合、対応は不要です。スキルはインストール済みで最新の状態です（または、24 時間以内にキャッシュされています）。

ユーザーから明示的に依頼された場合

ユーザーから更新の確認を明示的に依頼された場合（例：「更新を確認して」「バージョンを確認して」）：

1. 隣接するスキルディレクトリ内で qianwen-update-check/SKILL.md を探します。
2. 見つかった場合 — python3 <qianwen-update-check-dir>/scripts/check_update.py --print-response を実行し、結果を報告します。
3. 見つからなかった場合 — 上記のインストール方法を提示します。

参考資料

• execution-guide.md — フォールバックの方法（curl の標準／指示／ストリーミング、コード生成、自律実行）
• api-guide.md — API の補足ガイド
• sources.md — 公式ドキュメントの URL