qwencloud-audio-tts

Qwen Audio TTS（テキスト読み上げ）

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

スキルディレクトリ

このスキルの内部ファイルを使用して、実行方法や仕組みを確認してください。デフォルトのパスで読み込みに失敗した場合や、詳細が必要な場合は、必要に応じて参照ファイルを読み込んでください。

Location	Purpose
scripts/tts.py	Qwen TTS / Qwen Audio TTS（HTTP および WebSocket）。現在の互換性とデフォルト設定については、以下のモデルカタログを参照してください
scripts/tts_cosyvoice.py	CosyVoice（WebSocket API）。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 キーや認証情報を平文で出力してはいけません。 必ず変数参照を使用してください（シェルでは $QWENCLOUD_API_KEY、Python では os.environ["QWENCLOUD_API_KEY"]）。スクリプトは QWENCLOUD_API_KEY、次に QWEN_API_KEY、最後に DASHSCOPE_API_KEY を受け付けます。認証情報の確認や検出は、必ず平文を表示しない方法で行ってください。状態（例：「設定済み」／「未設定」、「有効」／「無効」）のみを報告し、値は決して表示しないでください。秘密情報が含まれている可能性がある .env ファイルや設定ファイルの内容は、決して表示しないでください。

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

主な互換性

スクリプトは、標準の QwenCloud API キー（sk-...）と Token Plan キー（sk-sp-...）の両方をサポートします。Token Plan キーは、対応する TTS モデルの場合、Token Plan エンドポイントに自動的にルーティングされます。詳細は以下の Token Plan のサポートを参照してください。

Token Plan では curl を使用せず、必ず同梱の Python スクリプトを使用してください。

Coding Plan キー（こちらも sk-sp- プレフィックスですが、Coding Plan サブスクリプションで購入したもの）は使用できません。TTS モデルは Coding Plan では利用できません。スクリプトは起動時にキーの種類を検出し、それに応じてルーティングします。qwencloud-ops-auth がインストールされている場合は、詳細について references/codingplan.md を参照してください。

API キーを公開せずに種類を検出します。

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

Output	Meaning
token-plan	Token Plan キーが検出されました（sk-sp- プレフィックス）
payg	標準の PAYG キーが検出されました
not-set	環境内に API キーが見つかりません

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

モデルの選択

🚫 重大 — ユーザーが選んだモデルを決して変更しないでください。 ユーザーまたはリクエスト JSON で model が明示されている場合は、必ずそのモデルをそのまま使用してください。次のことはしないでください。

• 「より適している」モデルに置き換える（例：文体的・詩的なテキストに対して qwen3-tts-instruct-flash に切り替える）
• ユーザーが求めていない instructions を追加する
• ユーザーが明示したパラメーターを変更する

以下のモデル選択ガイダンスは、ユーザーがモデルを指定していない場合に限り適用されます。

モデルを選択、推奨、またはデフォルト設定する前に、最新の QwenCloud 音声 TTS モデルカタログを取得して確認してください。カタログには、モデル一覧、基本情報、スクリプトおよび音声との互換性、推奨事項、デフォルト設定が含まれています。CDN にアクセスできない場合は、ローカルの代替ファイルを使用してください。

モデルの選択が機能、シナリオ、または価格によって異なる場合は、qwencloud-model-selector スキルを参照してください。CosyVoice には dashscope SDK が必要で、音声も異なります。cosyvoice-guide.md を参照してください。

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

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

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

利用可能な音声

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

音声のデフォルト設定：Qwen-Audio WebSocket モデルで音声が指定されていない場合、tts.py はそのモデルに設定されたデフォルト音声を選択し、stderr に通知を出力します。明示的に指定された音声（Cherry の明示的な指定を含む）は、変更せずに渡されます。音声を選択する前に、モデルカタログを取得してください。

実行

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

Qwen TTS（HTTP API）— tts.py

前提条件

• API キー：QWENCLOUD_API_KEY、QWEN_API_KEY、次に DASHSCOPE_API_KEY の順で、値を表示しない方法のみを使って確認してください（例：シェルでは [ -n "$QWENCLOUD_API_KEY" ] を使用し、結果は「設定済み」または「未設定」とだけ報告して、キーの値は決して表示しないでください）。未設定の場合、利用可能であれば qwencloud-ops-auth スキルを実行してください。利用できない場合は、QwenCloud Console からキーを取得し、.env ファイル（プロジェクトのルートディレクトリまたは現在のディレクトリで echo 'QWENCLOUD_API_KEY=sk-your-key-here' >> .env を実行）または環境変数を使って設定するよう、ユーザーに案内してください。スクリプトは現在の作業ディレクトリとプロジェクトのルートディレクトリにある .env を検索します。スキルは個別にインストールできるため、qwencloud-ops-auth が存在するとは限りません。 注：スクリプトは、エクスポート済みの環境変数に加えて、現在のディレクトリとプロジェクトのルートディレクトリにある .env を自動的に読み込みます。シェルで $QWENCLOUD_API_KEY が「未設定」と表示されても、スクリプトが失敗するとは限りません。.env にキーが見つかる場合があります。シェルでの確認結果は参考情報としてのみ扱ってください。キーがどこにも見つからない場合は明確なエラーを表示して終了するため、スクリプトを実行することが最終的な確認方法です。
• Python 3.9 以降（標準ライブラリのみ、pip install は不要）

環境の確認

初回実行の前に、Python が利用可能であることを確認します。

python3 --version  # must be 3.9+

python3 が利用できない、またはバージョンが 3.9 未満の場合、PAYG では **Path 2（curl）**を使用できます。Token Plan では、代わりに Python 3.9 以降をインストールする必要があります。

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

スクリプトのパス：スクリプトは、このスキルのディレクトリ（この 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":"Cherry"}' \
  --output output/qwencloud-audio-tts/ \
  --print-response

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

結果の確認

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

失敗した場合

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

Python がまったく利用できない場合 → PAYG では Path 2（curl）を使用できます。Token Plan では Python 3.9 以降をインストールする必要があります。

---

CosyVoice — tts_cosyvoice.py

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

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

トークンプラン：tts_cosyvoice.py は起動時にトークンプランのキーを拒否します。上記にリンクされているトークンプランのカタログを取得し、tts.py でサポート対象の正確な TTS モデルを指定するか、PAYG キーを使用してください。ユーザーの確認なしに、明示的に指定されたモデルを置き換えないでください。

完全ガイド：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 以降にアップグレードしてください
cosyvoice models are not available on Token Plan	トークンプランのキーが検出されました	トークンプランのカタログにあるサポート対象の正確なモデルを tts.py で使用するか、PAYG キーを使用してください
QWENCLOUD_API_KEY/QWEN_API_KEY/DASHSCOPE_API_KEY not found	API キーがありません	QwenCloud Console からキーを取得し、.env に追加してください：echo 'QWENCLOUD_API_KEY=sk-...' >> .env。または、利用可能な場合は qwencloud-ops-auth を実行してください
HTTP 401	キーが無効、または一致していません	qwencloud-ops-auth を実行してください（平文を出力しない確認のみ）。キーが有効であることを確認してください
SSL: CERTIFICATE_VERIFY_FAILED	SSL 証明書の問題（プロキシ／企業ネットワーク）	macOS：Install Certificates.command を実行してください。それ以外の場合は SSL_CERT_FILE 環境変数を設定してください
URLError / ConnectionError	ネットワークに接続できません	インターネット接続を確認してください。プロキシ経由の場合は HTTPS_PROXY を設定してください
HTTP 429	レート制限に達しました	待機し、バックオフして再試行してください
HTTP 5xx	サーバーエラー	バックオフして再試行してください
PermissionError	出力を書き込めません	--output を使用して、書き込み可能なディレクトリを指定してください

クイックリファレンス

リクエストフィールド

フィールド	型	説明
text	string	必須 — 合成するテキストです。モデル固有の制限については、上記のモデルカタログを確認してください
voice	string	音声 ID です。現在のデフォルトと互換性については、上記のモデルカタログを確認してください
model	string	モデル ID です。現在のデフォルトについては、上記のモデルカタログを確認してください
language_type	string	Auto、Chinese、English、Japanese、Korean、French、German など — コード（zh、en）ではなく正式名称を指定します
instructions	string	トーン／スタイルの指示です。現在の互換性と制限については、上記のモデルカタログを確認してください
volume	int	音量 [0-100]、デフォルトは 50 — 対応する WebSocket モデルのみ。モデルカタログを確認してください
rate	float	話速 [0.5-2.0]、デフォルトは 1.0。1.0 未満では話速が遅くなります — WebSocket モデルのみ
pitch	float	ピッチ倍率 [0.5-2.0]、デフォルトは 1.0。1.0 を超えるとピッチが高くなります — WebSocket モデルのみ
sample_rate	int	サンプルレート（Hz）、デフォルトは 24000 — WebSocket モデルのみ
format	string	音声形式：mp3／wav／pcm／opus、デフォルトは mp3 — WebSocket モデルのみ
stream	bool	SSE ストリーミング用の Qwen3-TTS 直接 HTTP API フィールドです。同梱の tts.py はこのフィールドを実装していません。execution-guide.md に記載されている直接 SSE の方法を使用してください

レスポンスフィールド

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

重要な注意事項

• text：選択したモデルの現在のリクエスト上限は、上記のモデルカタログで確認してください。
• instructions：サポート状況はモデルによって異なります。使用する前に、上記のモデルカタログで確認してください。
• language_type：複数の言語が混在する場合は Auto を指定してください。より適切な発音にするには、言語を指定してください。値にはコード（zh、en など）ではなく、正式名称（Chinese、English、Japanese など）を使用します。これは互換性のある HTTP モデルにのみ適用されます。WebSocket モデルでは、選択した音声の言語が使われるため、スクリプトはこの値を無視します。
• audio_url：有効期限は24時間です。速やかにダウンロードしてください。
• リアルタイム／ストリーミング TTS：同梱の tts.py は、Qwen3-TTS には非ストリーミング HTTP を、Qwen-Audio TTS には生の WebSocket のみを使用します。CosyVoice には tts_cosyvoice.py を使用します。Qwen3-TTS API 自体はオプションの SSE に対応しています。必要な場合は、execution-guide.md の直接実行例を使用してください。

スキル間の連携

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

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

エラー処理

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

使用状況と請求：使用状況、無料枠の上限、請求の詳細は、qwencloud-usage スキルを使って直接確認してください。または、ユーザーは QwenCloud コンソールにアクセスできます。 使用状況の分析 | 従量課金制の請求 | Coding Plan の請求

現在の料金体系におけるモデル一覧と請求単位については、CDN のモデル料金リファレンスを取得してください。CDN にアクセスできない場合は、ローカルの代替ファイルを使用してください。

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

出力先

現在の作業ディレクトリを優先してください。デフォルトのサブディレクトリは ./output/qwencloud-audio-tts/ です。

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

Token Plan のサポート

Token Plan がサポートする TTS モデルは一部に限られます。モデルを選択または検証する前に、現在の Token Plan モデルカタログを取得して確認してください。CDN にアクセスできない場合は、ローカルの代替ファイルを使用してください。

Token Plan キーと非対応モデルを組み合わせると、tts.py は現在サポートされているモデルを一覧表示し、代替モデルを提案する警告を stderr に出力しますが、呼び出しはブロックしません。この警告が表示された場合は、現在のカタログでサポートされているモデルをユーザーに伝え、カタログに記載された代替モデル、または元のモデル用の PAYG キーを提案してください。明示的に指定されたモデルを、黙って別のモデルに置き換えてはいけません。

CosyVoice については、tts_cosyvoice.py は起動時に Token Plan キーを強制的にブロックします。現在の Token Plan カタログに記載されたモデルで tts.py を使用するか、PAYG キーを使用してください。

Token Plan のスタイル制御

音声モデルカタログで選択した Token Plan モデルがサポートするスタイル制御フィールドのみを使用してください。以下は現在サポートされているモデルのプロトコル例です。ユーザー指定のモデルの代わりに使用しないでください：

{"text": "落霞与孤鹜齐飞，秋水共长天一色。", "model": "qwen-audio-3.0-tts-plus", "rate": 0.8, "pitch": 1.1, "volume": 60}

• rate が 1.0 未満の場合は音声が遅くなり、1.0 を超える場合は速くなります
• pitch が 1.0 を超える場合はピッチが高くなり、1.0 未満の場合は低くなります
• volume は線形に調整されます（0 = 無音、50 = デフォルト、100 = 最大）

プロトコルに関する注意

QwenCloud のモデルページには、qwen-audio-3.0-tts-plus の WSS（WebSocket） が記載されています。スクリプトには WebSocket 用の分岐があり、次の処理を行います：

1. wss://token-plan.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/inference（または PAYG 用の標準エンドポイント）に接続します
2. WebSocket のハンドシェイクで User-Agent: qwencloud-skills を設定します
3. run-task → continue-task → finish-task のメッセージを送信します
4. バイナリ音声フレームを受信し、出力ファイルに連結します

必須ヘッダー

User-Agent: qwencloud-skills は HTTP リクエストと WebSocket リクエストの両方に自動的に含まれます。

更新チェック（実行後に必須）

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

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

stderr にこのシグナルが含まれている場合は、次の選択肢をユーザーに提示し、処理を続ける前に回答を待ってください。黙ってスキップしてはいけません。

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

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

ユーザーの回答後：

• ユーザーが 1 を選択 → npx skills add QwenCloud/qwencloud-ai --skill qwencloud-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. 隣接するスキルディレクトリ内に qwencloud-update-check/SKILL.md があるか確認します。
2. 見つかった場合 — python3 <qwencloud-update-check-dir>/scripts/check_update.py --print-response を実行し、結果を報告します。
3. 見つからない場合 — 上記のインストール選択肢を提示します。

参考資料

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