So integrieren Entwickler die Uberduck-API zur programmgesteuerten Erzeugung von Gesang und Rap-Vocals

Entwickler interaktiver Musikanwendungen, dynamischer Gaming-NPCs oder virtueller Streamer (VTuber) stoßen bei manuellen Web-Oberflächen schnell an Grenzen: Klickbasierte Arbeitsabläufe im Browser lassen sich weder in automatisierte CI/CD-Pipelines einbinden noch für parallele Massenverarbeitungen skalieren. Uberduck bietet eine offizielle REST-API, über die Audioingenieure und Softwareentwickler gesungene und gerappte Gesangsspuren direkt per Programmcode synthetisieren können.

Eine robuste Integration der Uberduck-API stützt sich auf drei architektonische Bausteine: HTTP-Basic-Authentifizierung, die Auswahl des geeigneten Syntheseverfahrens (taktgenaues Text-to-Rap via /tts/freestyle, parametrische Tonhöhensteuerung via /speak oder Voice-to-Voice-Konvertierung via /tts/convert) sowie eine asynchrone Polling-Schleife über /speak-status zum Abrufen der fertigen Audiodateien.

1. Authentifizierung und Request-Architektur

Die Uberduck-REST-API setzt auf den standardisierten HTTP-Basic-Authentifizierungsmechanismus. API-Key (Benutzername) und API-Secret (Passwort) werden durch einen Doppelpunkt getrennt, Base64-kodiert und im Authorization-Header übergeben.

Konfiguration des Auth-Headers

1. Erzeuge API Key und API Secret in den Kontoeinstellungen auf Uberduck.
2. Formatiere den HTTP-Header wie folgt:

   Authorization: Basic base64(API_KEY:API_SECRET)
   

3. Die Basis-URL lautet 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. Drei programmgesteuerte Synthese-Modi im Vergleich

Je nachdem, ob deine Applikation rhythmisch getakteten Rap oder melodischen Gesang erfordert, bietet Uberduck drei verschiedene Schnittstellen:

3. Aufbau einer automatisierten Text-to-Rap-Pipeline

Der Endpoint /tts/freestyle wurde speziell für Rap konzipiert und passt Silben automatisch an das angegebene Tempo (BPM) und die Taktstruktur des Backing-Tracks an.

Schritt 1: Verfügbare Backing-Tracks abrufen

Um Reime mit offiziellen Beats von Uberduck abzugleichen, fragst du zunächst den Beat-Katalog ab:

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()  # Gibt Tracks mit UUID, BPM und Genre-Metadaten zurück

Schritt 2: (Optional) Reime automatisiert generieren

Falls deine Pipeline Songtexte dynamisch aus Nutzereingaben erstellen soll, kann /tts/lyrics genutzt werden (oder ein LLM, das zweidimensionale Textzeilen-Arrays liefert):

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()  # Liefert strukturierte Zeilen

Schritt 3: Freestyle-Request absenden

Übermittle das Textmatrix-Array, das Ziel-BPM, die UUID des Backing-Tracks und das gewünschte Stimmenmodell:

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,  # Beispiel: [["Code läuft durch die Pipeline Takt für Takt", "API liefert Vocals absolut exakt"]]
        "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"]  # Gibt die Task-UUID für die asynchrone Verarbeitung zurück

4. Konfiguration von Tonhöhen-Kurven und Gesangsvocals

Melodischer Gesang erfordert kontinuierliche Modulationen der Grundfrequenz (F0) und präzise Haltedauern von Phonemen.

Ansatz A: Parametrische Kurven über /speak

Bei Stimmenmodellen, die erweiterte Steuerungen unterstützen (prüfbar via GET /voices/{voicemodel_uuid}/detail über das Flag controls: true), akzeptiert /speak Zahlenarrays für pitch (Halbtöne/Frequenzen) und duration (Dauer der Phoneme):

def generate_singing_notes(speech_text, voicemodel_uuid, pitch_curve, duration_curve):
    """
    pitch_curve: Zahlenarray mit Halbtönen oder Frequenzen pro Phonem.
    duration_curve: Zahlenarray mit der Zeitdauer pro Phonemeinheit.
    """
    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"]

Ansatz B: Lebendiger Gesang über Voice-to-Voice (/tts/convert)

Phonemgenaue Frequenzarrays direkt aus Text zu berechnen, ist fehleranfällig und klingt oft mechanisch. In professionellen Audio-Pipelines dominiert daher Voice-to-Voice (V2V): Ein Guide-Vocal (etwa über ein einfaches MIDI-Vocal-VST oder eine menschliche Führungsstimme) wird über POST /tts/convert in die Zielstimme transformiert, wobei pitch_shift Tonartwechsel ermöglicht:

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. Asynchroner Lifecycle und Polling-Pipeline

Da neuronale Audiomodelle rechenintensiv sind, werden Aufträge nicht innerhalb eines synchronen HTTP-Timeouts abgeschlossen. Die API gibt eine Job-uuid zurück. Das Backend fragt den Status über /speak-status ab:

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()
        
        # Fehlerprüfung
        if data.get("failed_at"):
            raise RuntimeError(f"Synthese-Job fehlgeschlagen: {data}")
            
        # Erfolgsprüfung
        if data.get("finished_at"):
            audio_url = data.get("path")
            return audio_url  # Finale CDN-Download-Adresse der WAV-Datei
            
        time.sleep(delay_seconds)
        
    raise TimeoutError("Audio-Generierung hat das Zeitlimit überschritten.")

6. Vollständiges Python-Orchestrierungsskript

Das folgende Skript demonstriert den gesamten Ablauf von der Authentifizierung bis zum Herunterladen der gerenderten Datei:

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. Rap-Generierung anfordern
    print("Sende Syntheseauftrag an Uberduck...")
    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"Task gestartet mit UUID: {task_id}")
    
    # 2. Status abfragen (Polling)
    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("Rendering-Fehler auf dem Server aufgetreten.")
        if status_data.get("finished_at"):
            audio_url = status_data.get("path")
            print(f"Generierung abgeschlossen: {audio_url}")
            break
            
    if not audio_url:
        raise TimeoutError("Generierung dauerte länger als 80 Sekunden.")
        
    # 3. Audiodatei herunterladen
    audio_data = requests.get(audio_url).content
    with open(output_file, "wb") as f:
        f.write(audio_data)
    print(f"Audiodatei erfolgreich gespeichert unter: {output_file}")
    return output_file

if __name__ == "__main__":
    bars = [
        ["Starte die Routine mit dem Beat synchronisiert", "Audio-Pipeline läuft während der Server operiert"],
        ["Präzise im Timing mit den BPM exakt im Lot", "Uberduck API liefert Tracks auf jedes Gebot"]
    ]
    create_rap_track(lyrics=bars, bpm=95)

7. Best Practices und Produktionsempfehlungen

Beim Betrieb in Produktivumgebungen sollten Entwickler folgende Faktoren berücksichtigen:

• Silbendichte und BPM-Verhältnis: Die Silbenanzahl pro Zeile muss zum eingestellten Tempo passen. Bei Geschwindigkeiten über 110 BPM führen überladene Textzeilen zu Sprachartefakten oder undeutlicher Aussprache.
• Asynchrone Worker-Architektur: Die Synthese benötigt im Schnitt 4 bis 15 Sekunden. Blockiere keine Web-Server-Threads, sondern lagere API-Aufrufe an Queue-Systeme wie Celery, BullMQ oder SQS aus.
• Lizenzierung und Tarifgrenzen: Die Nutzung der API für kommerzielle Produkte setzt kostenpflichtige Abonnements (Pro oder Enterprise) voraus. Kostenfreie Tarife sind auf nicht-kommerzielle Tests beschränkt.
• DSP-Nachbearbeitung: Die API liefert Rohspuren (Dry Stems). Um einen sendefähigen Sound zu erzielen, sollten nachgelagerte Audio-Pipelines mit Equalizern, Kompressoren und Hall (Reverb) integriert werden.

Referenzen

• 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