文字轉音樂 (Text-to-Music) 是做什麼的？
兩種方式產生帶有人聲與伴奏的歌曲，並儲存為 MP3 格式。每次請求會產出 兩個變體。
- 生成 — 根據音樂描述與歌詞創作全新歌曲。
- 改編 — 保留原曲旋律，以新風格重新演唱。歌詞可使用原曲（自動辨識）或全新撰寫。
觸發條件
- 寫一首歌 / 生成音樂 / 文字轉音樂 / 作曲
- 把這些歌詞變成一首歌 / 唱這首歌 / 廣告曲 / 主題曲 / 生日歌
- 翻唱這首歌 / 做一個爵士版本 / 換另一個風格重製
- make a song / generate music / text to music / compose
- turn these lyrics into a song / sing this / jingle / theme song / birthday song
- cover this song / make a jazz version / remake in another style
生成 — 從文字創作新歌
請求需要一個 提示（音樂描述）以及 恰好一個 歌詞來源：
# 讓伺服器根據主題撰寫歌詞
python3 skills/text-to-music/scripts/t2m.py "歡快的獨立流行，明亮的吉他，120 BPM" \
--lyrics-prompt "一首關於和朋友夏日公路旅行的歌"
# 使用自己的歌詞（內嵌或從檔案讀取）
python3 skills/text-to-music/scripts/t2m.py "華語流行抒情曲，鋼琴與弦樂" \
--lyrics $'[主歌]\n窗外的雨停了\n[副歌]\n我還在等你' --vocal-gender Female --title "雨停了"
python3 skills/text-to-music/scripts/t2m.py "低傳真嘻哈，柔和，黑膠噪點" \
--lyrics-file song.txt --duration 120 -o chill.mp3
# 以參考歌曲作為人聲/風格的模型（本地檔案 ≤20 MB 或公開 URL）
python3 skills/text-to-music/scripts/t2m.py "夢幻合成器流行" --lyrics-file song.txt --ref-audio ./ref.mp3
輸出：song_v1.mp3 和 song_v2.mp3（若使用 -o 則為 <stem>_v1.mp3 / <stem>_v2.mp3）。當歌詞由伺服器生成時，歌詞也會儲存至 <stem>_lyrics.txt。
| 參數 | 預設值 | 說明 |
|---|---|---|
prompt | 必填 | 音樂描述：曲風、情緒、樂器、速度（≤1500 字元） |
--lyrics / -l | — | 歌詞文字；使用 [主歌]、[副歌]、[橋段] 標記有助於結構化 |
--lyrics-file | — | UTF-8 .txt 歌詞檔案（≤64 KB） |
--lyrics-prompt | — | 伺服端創作歌詞的主題 |
--tags | — | 風格標籤，以逗號分隔（≤50 字元） |
--negative-tags | — | 要避免的風格 |
--duration / -d | 自動 | 目標長度提示：60、120 或 180 秒。僅供參考，並非保證。 |
--ref-audio | — | 參考歌曲，本地路徑或公開 URL |
--yrics、--lyrics-file 和 --lyrics-prompt 互斥；必須提供其中一個。
改編 — 重新演唱現有歌曲
需要提供 來源歌曲、歌詞，以及新聲音的描述（--style 和/或 --prompt）：
# 相同歌詞，新風格：從原曲辨識歌詞，然後改編
python3 skills/text-to-music/scripts/t2m.py cover original.mp3 \
--style "爵士，煙嗓女聲" --recognize-lyrics -o jazz_cover.mp3
# 原曲旋律配上新歌詞，編曲更自由
python3 skills/text-to-music/scripts/t2m.py cover https://example.com/song.mp3 \
--prompt "原聲民謠，指彈吉他，親密" --lyrics-file new_lyrics.txt \
--adherence main_melody --vocal-gender Male
# 僅辨識歌詞（以便檢閱或編輯後再改編）
python3 skills/text-to-music/scripts/t2m.py lyrics original.mp3 -o lyrics.txt
若使用者想調整歌詞，建議流程為：執行 lyrics → 編輯檔案 → cover --lyrics-file。
| 參數 | 預設值 | 說明 |
|---|---|---|
source | 必填 | 原曲：本地檔案（≤100 MB；mp3/wav/m4a/aac/flac/ogg）或公開 URL |
--style / -s | — | 簡短風格標籤，例如 "搖滾，男聲"（≤50 字元） |
--prompt / -p | — | 改編版聲音的詳細描述（≤1500 字元） |
--adherence | high | high = 緊密遵循原曲編排；main_melody = 僅保留主旋律，自由度更高 |
--lyrics / -l | — | 要演唱的歌詞 |
--lyrics-file | — | UTF-8 .txt 歌詞檔案（≤64 KB） |
--recognize-lyrics | 關閉 | 先轉錄來源歌曲的歌詞再使用 |
--output / -o | cover.mp3 | 輸出路徑；變體會加上 _v1 / _v2 後綴 |
至少需要提供 --style / --prompt 其中之一；且必須提供恰好一個歌詞來源。
共用參數
| 參數 | 預設值 | 說明 |
|---|---|---|
--title | — | 歌曲標題（≤80 字元） |
--vocal-gender | — | Male 或 Female |
--vocal-timbre | — | 自由描述人聲，例如 "沙啞溫暖的女低音"（≤50 字元） |
--output / -o | song.mp3（改編為 cover.mp3） | 輸出路徑；變體會加上 _v1 / _v2 後綴 |
--no-wait | 關閉 | 提交後直接印出任務 ID 並結束 |
--poll-interval | 10 | 狀態檢查間隔秒數 |
--timeout | 1800 | 最長等待秒數（任務會持續在伺服器端執行） |
--api-key | 來自環境/設定檔 | Noiz API 金鑰（覆蓋已儲存的金鑰） |
恢復 / 檢查任務
生成任務會印出兩個 gen_product_id；改編任務會印出一個 task_id。若等待逾時或使用了 --no-wait，可用下列指令恢復：
python3 skills/text-to-music/scripts/t2m.py status <id_v1> <id_v2> -o song.mp3
python3 skills/text-to-music/scripts/t2m.py status --cover <task_id> -o cover.mp3
python3 skills/text-to-music/scripts/t2m.py status --cover <task_id> --no-wait # 僅印出狀態
狀態依序為 submitted → running → succeeded / failed。改編任務還會回報 stage（分析階段在演唱之前執行，因此改編耗時較長）。下載網址約 24 小時後過期；重新執行 status 可取得新的網址。
撰寫有效提示
- 提示 / 風格 = 聲音：曲風 + 情緒 + 樂器 + 速度。例如
"電影感管弦流行，高亢弦樂，90 BPM，充滿希望"。 - 歌詞：段落保持簡短並加上標籤。中文、英文或混合歌詞皆可。
- 短歌曲：若為廣告曲或問候語，可傳入
-d 60並只寫一段主歌加副歌。 - 改編：選擇
high可保持原曲辨識度；選擇main_melody可進行大幅度的風格轉變。 - 不滿意？重新執行即可 — 每次執行都會產出兩個新的變體。
費用
- 歌曲與改編 按 每項任務收費一次（而非每個變體）：
ceil(最長變體秒數) × 15點數，在兩個變體皆成功後扣款。一首 2 分鐘的歌曲約需 1,800 點數。若訂閱點數不足以支付整項任務，則按即用即付計費，每 0.00015 美元/秒。完成時腳本會輸出扣款金額。 - 歌詞辨識（
lyrics/--recognize-lyrics）：100 點數（即用即付為 $0.001），僅在偵測到人聲時收費。
速率限制：每個金鑰、每個端點每分鐘 5 次提交；狀態查詢每分鐘 60 次。
限制
- 不支援純器樂 — 歌詞為必填。
--duration僅為提示；實際長度可能不同。改編版本會跟隨來源歌曲的長度。- 包含敏感內容的提示或歌詞將被拒絕（
code=400）。
設定
python3 skills/text-to-music/scripts/t2m.py config --set-api-key 你的金鑰
# 或
export NOIZ_API_KEY=你的金鑰
請在 developers.noiz.ai 取得您的 API 金鑰。
需求
- Python 3.6+
requests套件：uv pip install requests- 來自 developers.noiz.ai 的 Noiz API 金鑰
安全性與資料揭露
- API 金鑰：儲存在
~/.config/noiz/api_key（權限設為0600）或透過NOIZ_API_KEY環境變數設定。 - 網路：提示、歌詞以及任何參考/來源音訊（檔案上傳或 URL）會被傳送至
https://noiz.ai/v1/text-to-music和https://noiz.ai/v1/text-to-music/cover*；任務狀態從相同端點輪詢。不會傳送其他資料。 - 輸出：生成的 MP3（以及歌詞文字檔）會從 Noiz 簽署的儲存網址下載並儲存至輸出路徑。不會修改其他檔案。