Tutorial

So verwenden Sie qwen-audio-3.0-tts-plus über die hiapi API: Text-zu-Sprache mit curl und Python

Aug 4, 2026

qwen-audio-3.0-tts-plus ist ein Text-zu-Sprache-Modell, auf das über die einheitliche asynchrone Aufgabenwarteschlange der hiapi-Plattform zugegriffen wird – mit demselben POST /v1/tasks-Endpunkt, den auch die Bild- und Videogenerierung verwendet, nicht über eine separate Audio-API. Sie senden Text, erhalten sofort eine taskId zurück und rufen dann per Polling oder Callback die URL einer herunterladbaren Audiodatei ab. Dieses Tutorial führt Sie durch eine funktionierende Anfrage in curl und Python (Ende-zu-Ende gegen die Live-API verifiziert) und zeigt dann die Produktionsmuster, die Sie tatsächlich benötigen: Callback vs. Polling, idempotente Wiederholungen und die genauen Fehlerformen, die Sie behandeln müssen.

Was Sie erstellen werden

Ein Skript, das Text an qwen-audio-3.0-tts-plus übermittelt, auf den Abschluss der Aufgabe wartet und das generierte Audio herunterlädt – ergänzt durch eine Parameterreferenz und Fehlerbehandlungsmuster, damit Sie das Skript in eine echte Integration verwandeln können.

Voraussetzungen: Ein hiapi-API-Schlüssel. Rufen Sie ihn im hiapi-Dashboard ab – jede der folgenden Anfragen authentifiziert sich mit Authorization: Bearer sk-<your-key>.

Minimal funktionierendes Beispiel

curl

Aufgabe erstellen:

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen-audio-3.0-tts-plus",
    "input": {
      "text": "Welcome to hiapi, the unified API for AI models.",
      "voice": "longanlingxin"
    }
  }'

{"code": 200, "data": {"taskId": "tk-hiapi-01KZ59B7ZJ7012PXB5J9GE1QE7"}, "message": "success"}

Fragen Sie dann mit demselben Bearer-Token per Polling GET /v1/tasks/<taskId> ab, bis data.status "processing" verlässt. Bei diesem Modell dauerte es im Test etwa 5 Sekunden:

curl -s https://api.hiapi.ai/v1/tasks/tk-hiapi-01KZ59B7ZJ7012PXB5J9GE1QE7 \
  -H "Authorization: Bearer $HIAPI_KEY"

{
  "code": 200,
  "data": {
    "taskId": "tk-hiapi-01KZ59B7ZJ7012PXB5J9GE1QE7",
    "status": "success",
    "model": "qwen-audio-3.0-tts-plus",
    "storage": "temp",
    "created": 1785810231,
    "completed": 1785810236,
    "output": [{"type": "audio", "url": "https://temp.hiapi.ai/.../01KZ59B7ZJ7012PXB5J9GE1QE7-0.mp3", "artifactId": "66654", "expireAt": 1786415036}]
  },
  "message": "success"
}

output[0].url ist eine echte herunterladbare MP3 (content-type: audio/mpeg – durch direktes Abrufen bestätigt). Es handelt sich um einen temporären Link: solange storage den Standardwert "temp" behält, liegt expireAt fast genau 7 Tage nach created. Wenn Sie das Audio also langfristig aufbewahren möchten, laden Sie die Bytes herunter und speichern Sie sie selbst.

Python

import os
import time
import requests

API_BASE = "https://api.hiapi.ai/v1/tasks"
headers = {"Authorization": f"Bearer {os.environ['HIAPI_KEY']}"}

resp = requests.post(
    API_BASE,
    headers={**headers, "Content-Type": "application/json"},
    json={
        "model": "qwen-audio-3.0-tts-plus",
        "input": {
            "text": "Welcome to hiapi, the unified API for AI models.",
            "voice": "longanlingxin",
        },
    },
    timeout=30,
)
resp.raise_for_status()
task_id = resp.json()["data"]["taskId"]

while True:
    task = requests.get(f"{API_BASE}/{task_id}", headers=headers, timeout=30).json()["data"]
    if task["status"] == "success":
        audio_url = task["output"][0]["url"]
        break
    if task["status"] == "fail":
        raise RuntimeError(task["error"])
    time.sleep(2)

audio_bytes = requests.get(audio_url, timeout=60).content
with open("output.mp3", "wb") as f:
    f.write(audio_bytes)

Produktionsmuster

Vollständiges Eingabeschema

Das input-Objekt akzeptiert nur die folgenden Felder – bei allem anderen lehnt die API mit 400 ab, übernehmen Sie daher keine Parameternamen von anderen TTS-Anbietern:

Feld	Erforderlich	Typ / Wert
`text`	Ja	String
`voice`	Ja	Einer von `"longanlingxin"`, `"longanlufeng"` (für dieses Modell sind derzeit nur zwei Stimmen verfügbar)
`format`	Nein	Einer von `"pcm"`, `"wav"`, `"mp3"`, `"opus"` – bei Weglassen wird standardmäßig `mp3` verwendet
`sample_rate`	Nein	Einer von `8000`, `16000`, `22050`, `24000`, `44100`, `48000`
`pitch`	Nein	Zahl, `0.5`–`2`
`volume`	Nein	Zahl, `0`–`100`

Jede der oben genannten Grenzen und Enum-Werte stammt aus den Validierungsfehlern der API selbst – wenn Sie eine ungültige voice oder einen pitch außerhalb des Bereichs übergeben, teilt Ihnen hiapi genau mit, welche Werte zulässig sind:

{"code": 400, "data": null, "error_code": "INVALID_REQUEST", "message": "invalid input: voice: value must be one of 'longanlingxin', 'longanlufeng'"}

Dieses Modell hat keine emotion-, speed- oder SSML-artigen Steuerungsfelder – Anfragen, die diese Felder enthalten, schlagen mit "additional properties '...' not allowed" fehl.

Callback vs. Polling

Für alles, was über ein schnelles Skript hinausgeht, überspringen Sie das Polling und lassen Sie hiapi die Ergebnisse pushen. Fügen Sie der Aufgaben-Erstellungsanfrage ein callback-Objekt hinzu:

{
  "model": "qwen-audio-3.0-tts-plus",
  "callback": {"url": "https://example.com/hiapi/callback", "when": "final"},
  "input": {"text": "Welcome to hiapi.", "voice": "longanlingxin"}
}

"final" ist derzeit der einzige unterstützte Wert für when – unabhängig davon, ob die Aufgabe erfolgreich ist oder fehlschlägt, sendet hiapi einmalig ein POST an Ihre callback.url, und Sie lesen aus dieser Nutzlast dieselbe Aufgaben-Detailstruktur, die Sie auch per Polling von GET /v1/tasks/<taskId> erhalten. Lassen Sie callback ganz weg und führen Sie stattdessen selbst Polling durch, wie in den obigen Beispielen gezeigt.

Ebenfalls wissenswert: Aufgabenausgaben verwenden standardmäßig storage: "temp" (Dateien bleiben etwa eine Woche bestehen, wie der obige expireAt-Wert zeigt). Wenn Sie Audio langfristig abrufbar benötigen, setzen Sie "storage": "persistent" auf der Aufgabe – dauerhafter Speicher wird nach Größe abgerechnet, daher ist es für einmalige Generierungen oft günstiger, herunterzuladen und selbst zu speichern.

Idempotenz und Wiederholungen

POST /v1/tasks akzeptiert den Idempotency-Key-Header (bis zu 255 Bytes). Wenn Sie dieselbe Anfrage unter demselben Konto mit demselben Schlüssel wiederholen, wird die Aufgabe nur einmal erstellt – die Wiederholung gibt die ursprüngliche taskId zurück, statt eine zweite kostenpflichtige Generierung zu starten. Verwenden Sie dies für Wiederholungen nach einem Timeout oder 5xx, wenn Sie nicht wissen, ob die erste Anfrage angekommen ist:

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: tts-job-42" \
  -d '{"model": "qwen-audio-3.0-tts-plus", "input": {"text": "...", "voice": "longanlingxin"}}'

Fehlerbehandlung

Ein ungültiger oder nicht autorisierter Schlüssel liefert HTTP 401 mit dem Standard-Fehlerumschlag von hiapi (direkt gegen dieses Modell verifiziert):

{"error": {"code": "permission_denied", "message": "This API key cannot use the selected model...", "request_id": "...", "type": "hiapi_error"}}

Eine fehlerhafte input-Nutzlast liefert HTTP 400 mit error_code: "INVALID_REQUEST" und einer message, die das fehlerhafte Feld angibt, wie im obigen Schemaabschnitt gezeigt – verzweigen Sie nach error_code / error.code, nicht nach dem menschenlesbaren Nachrichtentext. Wenn eine Aufgabe den Endzustand "fail" erreicht, anstatt bereits bei der Erstellung zu scheitern, enthält die Aufgaben-Detailantwort dieselbe Struktur unter data.error (code + message) statt unter dem obersten error-Schlüssel.

Weiterführende Lektüre

hiapi-Dashboard — API-Schlüssel erstellen und verwalten.
Dokumentation zum Erstellen von Aufgaben — der vollständige POST /v1/tasks-Vertrag, einschließlich Header, Callback und Idempotenz.
Dokumentation zum Abrufen von Aufgaben-Details — der oben verwendete Polling-Endpunkt.
hiapi-Authentifizierungsdokumentation — wie der Authorization-Header und Schlüsselbereiche plattformweit funktionieren.
hiapi-Rate-Limit-Dokumentation — 429-Verhalten und Retry-After.
Audiomodelle auf hiapi — durchsuchen Sie weitere Sprach- und Audiomodelle der Plattform.
Die aktuellen Preise für dieses Modell finden Sie auf der Live-Preisseite; sie werden hier nicht wiederholt.

Häufige Fragen

Unterscheidet sich die Audiogenerierung von der Bild-/Video-Aufgaben-API von hiapi? Nein – dieselbe POST /v1/tasks-Warteschlange, derselbe Ablauf mit Erstellen und anschließendem Polling oder Callback, dieselbe output[0].url-Struktur. Nur output[0].type (hier "audio") und das input-Schema unterscheiden sich je nach Modell.

Was passiert, wenn ich format nicht setze? Sie erhalten eine MP3 – im Test durch Weglassen bestätigt. Wenn Sie wav, pcm oder opus benötigen, setzen Sie format explizit.

Kann ich Audio streamen, anstatt auf den Abschluss der Aufgabe zu warten? Nein. Dieses Modell bietet nur den standardmäßigen Aufgabenablauf aus Erstellen/Polling/Callback – sein Eingabeschema enthält keinen Streaming-Parameter, und die Generierung ist schnell genug (bei kurzem Text nur wenige Sekunden), dass Polling alle 1-2 Sekunden in der Regel ausreicht.

Wie lange bleibt die Ausgabe-URL gültig? Standardmäßig etwa 7 Tage (storage: "temp"), basierend auf dem Abstand zwischen den Zeitstempeln created und expireAt der Aufgabe. Laden Sie das Audio rechtzeitig herunter, oder setzen Sie "storage": "persistent" auf der Aufgabe, wenn Sie es länger abrufbar benötigen.

Warum schlägt meine Anfrage mit "additional properties ... not allowed" fehl? Das Schema ist streng – dieses Modell akzeptiert nur text, voice, format, sample_rate, pitch und volume. Parameter aus anderen TTS-APIs (wie emotion oder speed) werden hier nicht erkannt und führen zu einem 400.

Wo finde ich die aktuellen Preise? Auf der Preisseite – dieses Tutorial kodiert bewusst keine Kosten pro Zeichen oder pro Anfrage fest, da sich Preise ändern können.