如何整合 Uberduck API 程式化生成 AI 饒舌與歌唱人聲

在開發互動式音樂應用、遊戲 NPC 即時演出或虛擬主播（VTuber）音訊生成系統時，許多工程師與創意技術人員常面臨網頁端介面的技術瓶頸：手動點擊無法嵌入自動化生產流程，更無法支撐高併發與批次合成需求。Uberduck 提供了官方 REST API，讓開發團隊能直接以程式碼合成具備節奏感與旋律感的 AI 人聲音訊。

要在後端成功整合 Uberduck API 來生成歌唱與饒舌人聲，主要涵蓋三個核心技術層：HTTP Basic 身分驗證、選擇適配的合成模式（節奏對齊的 /tts/freestyle、參數化音高時間軸 /speak 或聲音轉換 /tts/convert），以及基於 /speak-status 的非同步任務輪詢機制。

1. 驗證機制與請求架構

Uberduck 官方 REST API 採用標準的 HTTP Basic Authentication 協定。開發者需將控制台取得的 API Key（作為使用者名稱）與 API Secret（作為密碼）串接後進行 Base64 編碼，填入 HTTP 標頭中。

驗證標頭建構方式

1. 在 Uberduck 帳號設定頁面中生成 API Key 與 API Secret。
2. 組合 HTTP Authorization 標頭：

   Authorization: Basic base64(API_KEY:API_SECRET)
   

3. API 基礎端點為 https://api.uberduck.ai。

import base64
import os

API_KEY = os.getenv("UBERDUCK_API_KEY", "your_api_key")
API_SECRET = os.getenv("UBERDUCK_API_SECRET", "your_api_secret")

def get_auth_headers():
    token = base64.b64encode(f"{API_KEY}:{API_SECRET}".encode("utf-8")).decode("utf-8")
    return {
        "Authorization": f"Basic {token}",
        "Content-Type": "application/json"
    }

2. 三種核心人聲合成模式比較

針對饒舌節拍卡點與旋律歌唱的不同需求，Uberduck 提供三種實作路徑：

3. 建構端到端程式化饒舌合成管線

/tts/freestyle 端點專為饒舌音樂設計，其底層神經網路會根據設定的節奏速度（BPM）與伴奏音軌自動對齊歌詞節奏。

步驟 1：查詢官方伴奏音樂庫

若希望人聲與預設伴奏精確對位，可先取得支援的伴奏清單：

import requests

def list_backing_tracks():
    url = "https://api.uberduck.ai/reference-audio/backing-tracks?detailed=true"
    response = requests.get(url, headers=get_auth_headers())
    response.raise_for_status()
    return response.json()  # 回傳包含伴奏 UUID、BPM 與曲風資訊的陣列

步驟 2：（選用）自動產生押韻歌詞

若音訊管線需由使用者主題動態產生歌詞，可呼叫 /tts/lyrics（或使用 LLM 輸出為二維字串陣列格式）：

def generate_lyrics(subject, lines=4):
    url = "https://api.uberduck.ai/tts/lyrics"
    payload = {
        "subject": subject,
        "lines": lines
    }
    response = requests.post(url, json=payload, headers=get_auth_headers())
    response.raise_for_status()
    return response.json()  # 回傳結構化歌詞行

步驟 3：發送 Freestyle 非同步合成請求

將二維歌詞矩陣、目標 BPM、伴奏 UUID 以及目標聲音模型參數發送至端點：

def generate_rap_vocal(lyrics_matrix, bpm=90, backing_track_uuid=None, voice="zwf"):
    url = "https://api.uberduck.ai/tts/freestyle"
    payload = {
        "lyrics": lyrics_matrix,  # 例如：[["程式碼在終端執行節奏不間斷", "API 呼叫人聲在音軌間穿梭"]]
        "bpm": bpm,
        "voice": voice,
        "format": "json"
    }
    if backing_track_uuid:
        payload["backing_track"] = backing_track_uuid

    response = requests.post(url, json=payload, headers=get_auth_headers())
    response.raise_for_status()
    data = response.json()
    return data["uuid"]  # 回傳非同步任務 UUID

4. 設定音高時間軸與歌唱旋律

旋律歌唱對音高過渡與音素長度有極高要求。Uberduck 提供了兩種實作架構：

方案 A：透過 /speak 控制音高陣列與音素長度

在支援進階控制的聲音模型中（可透過 GET /voices/{voicemodel_uuid}/detail 檢查回應中的 controls: true），/speak 允許傳入 pitch（音高陣列）與 duration（時長陣列）：

def generate_singing_notes(speech_text, voicemodel_uuid, pitch_curve, duration_curve):
    """
    pitch_curve: 對應每個音素目標音高或半音數值的數值陣列
    duration_curve: 對應每個音素持續時間的數值陣列
    """
    url = "https://api.uberduck.ai/speak"
    payload = {
        "speech": speech_text,
        "voicemodel_uuid": voicemodel_uuid,
        "pitch": pitch_curve,
        "duration": duration_curve,
        "pace": 1.0
    }
    response = requests.post(url, json=payload, headers=get_auth_headers())
    response.raise_for_status()
    return response.json()["uuid"]

方案 B：利用聲音轉換（V2V）生成高度自然的旋律歌聲

直接在文字層級計算音素音高容易缺乏情感表現。業界成熟的商業流程更常使用 Voice-to-Voice（聲音轉換）： 先以 MIDI 虛擬歌手或真人錄製基準導唱，再透過 POST /tts/convert 替換為目標角色音色，並使用 pitch_shift 進行半音移調：

def convert_guide_vocal_to_singer(guide_audio_url, target_voice_uuid, semitone_shift=0):
    url = "https://api.uberduck.ai/tts/convert"
    payload = {
        "input": guide_audio_url,
        "voicemodel_uuid": target_voice_uuid,
        "pitch_shift": semitone_shift
    }
    response = requests.post(url, json=payload, headers=get_auth_headers())
    response.raise_for_status()
    return response.json()["uuid"]

5. 非同步生命週期與輪詢架構

語音神經網路生成需要數秒運算，無法在一般同步 HTTP 請求中直接返回。每次發送任務後，API 會回傳任務代碼（uuid）。後端需實作具備逾時控制的輪詢函式：

import time

def poll_render_completion(job_uuid, max_attempts=30, delay_seconds=2):
    status_url = f"https://api.uberduck.ai/speak-status?uuid={job_uuid}"
    headers = get_auth_headers()
    
    for attempt in range(max_attempts):
        response = requests.get(status_url, headers=headers)
        response.raise_for_status()
        data = response.json()
        
        # 異常失敗檢查
        if data.get("failed_at"):
            raise RuntimeError(f"音訊合成任務失敗：{data}")
            
        # 成功完成檢查
        if data.get("finished_at"):
            audio_url = data.get("path")
            return audio_url  # 渲染完成之 CDN 檔案路徑
            
        time.sleep(delay_seconds)
        
    raise TimeoutError("合成任務逾時未完成。")

6. 端到端可執行 Python 腳本

以下是一份完整的端到端程式碼，整合了身分驗證、任務發送、狀態輪詢與音訊檔案下載：

import requests
import base64
import time
import os

UBERDUCK_API_KEY = os.getenv("UBERDUCK_API_KEY")
UBERDUCK_API_SECRET = os.getenv("UBERDUCK_API_SECRET")

HEADERS = {
    "Authorization": f"Basic {base64.b64encode(f'{UBERDUCK_API_KEY}:{UBERDUCK_API_SECRET}'.encode()).decode()}",
    "Content-Type": "application/json"
}

def create_rap_track(lyrics, bpm=95, voice="zwf", output_file="vocal_output.wav"):
    # 1. 提交饒舌生成任務
    print("正在提交人聲合成請求...")
    freestyle_url = "https://api.uberduck.ai/tts/freestyle"
    payload = {
        "lyrics": lyrics,
        "bpm": bpm,
        "voice": voice,
        "format": "json"
    }
    
    resp = requests.post(freestyle_url, json=payload, headers=HEADERS)
    resp.raise_for_status()
    task_id = resp.json()["uuid"]
    print(f"任務已建立，UUID: {task_id}")
    
    # 2. 輪詢任務狀態
    status_url = f"https://api.uberduck.ai/speak-status?uuid={task_id}"
    audio_url = None
    for _ in range(40):
        time.sleep(2)
        status_resp = requests.get(status_url, headers=HEADERS)
        status_resp.raise_for_status()
        status_data = status_resp.json()
        
        if status_data.get("failed_at"):
            raise RuntimeError("伺服端處理任務失敗。")
        if status_data.get("finished_at"):
            audio_url = status_data.get("path")
            print(f"音訊生成完成，下載位置: {audio_url}")
            break
            
    if not audio_url:
        raise TimeoutError("渲染耗時超過 80 秒，已中止。")
        
    # 3. 下載並儲存音訊檔案
    audio_data = requests.get(audio_url).content
    with open(output_file, "wb") as f:
        f.write(audio_data)
    print(f"音訊已儲存至: {output_file}")
    return output_file

if __name__ == "__main__":
    bars = [
        ["啟動生成管線程式碼注入節奏動態", "全自動化流程擺脫繁瑣剪輯等待"],
        ["節奏咬字完美契合端點持續回應", "Uberduck API 驅動智慧音樂全新境界"]
    ]
    create_rap_track(lyrics=bars, bpm=95)

7. 正式上線與架構考量

將 Uberduck API 部署至正式生產環境時，請注意以下架構原則：

• 音節密度與節奏配比：單行歌詞的字數與音節長度需與 BPM 保持協調。若速度設定在 110 BPM 以上且文字過於密集，模型容易產生吞字或語音破音。
• 背景任務佇列解耦：單次生成通常耗時 4 至 15 秒。請務必使用 Celery、BullMQ 或 SQS 等非同步任務佇列解耦 API 請求，避免阻塞 Web 伺服器主執行緒。
• 商業授權方案規範：API 存取需具備 Pro 或 Enterprise 等付費方案資格。免費方案受限於呼叫額度，且通常不涵蓋商業發行授權。
• 後製音訊混音處理：API 回傳的音訊多為乾音（Dry Stems）。正式發布前，建議透過 FFmpeg 或專業音訊處理流程加上等化（EQ）、壓縮（Compressor）與空間殘響（Reverb）以達到商業發行標準。

參考資料

• Uberduck API Documentation
• Generate Freestyle - Uberduck Text To Speech API
• Generate Lyrics - Uberduck Text To Speech API
• Generate Speech - Uberduck Text To Speech API
• Voice To Voice Conversion - Uberduck Text To Speech API
• Get text-to-speech request status - Uberduck Text To Speech API
• List Backing Tracks - Uberduck Text To Speech API
• Uberduck AI Pricing and Plans