So verwendest du qwen-audio-3.0-tts-flash über die hiapi API: curl, Python und ein funktionierendes Anfragebeispiel

qwen-audio-3.0-tts-flash ist eine von Alibaba eingeführte Text-to-Speech-Ebene mit niedriger Latenz, die auf hiapi verfügbar ist und sich für den Aufbau von Sprachagenten, AI-Assistenten-Antworten und anderen latenzempfindlichen Sprach-Workflows eignet. Diese Anleitung zeigt eine tatsächlich funktionierende Anfrage, das vollständige Eingabe-Schema und wie du von einem schnellen Test zu einer Produktionsintegration gelangst.

Was du vorbereiten musst

• Einen hiapi-API-Schlüssel (sk-...), den du in der hiapi-Konsole erhältst.
• curl oder Python mit requests – kein SDK erforderlich.

hiapi routet alle Generierungsmodelle einheitlich auf dieselbe Gruppe von Endpunkten: Mit POST /v1/tasks wird eine Aufgabe erstellt, danach entweder GET /v1/tasks/<id> per Polling abgefragt oder nach Abschluss der Aufgabe ein Callback empfangen.

Minimales funktionierendes Beispiel

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-<your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen-audio-3.0-tts-flash",
    "input": {
      "text": "Hello, this is a test of the hiapi text to speech API.",
      "voice": "longanhuan_v3.6"
    }
  }'

Ein erfolgreicher Aufruf gibt sofort eine Aufgaben-ID zurück – die Sprachsynthese erfolgt asynchron:

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

Ergebnis per Polling abrufen:

curl https://api.hiapi.ai/v1/tasks/tk-hiapi-01KZ59P6KDXAXJMGW832X0M2R2 \
  -H "Authorization: Bearer sk-<your-api-key>"

Nach Abschluss der Synthese wechselt status zu success, und in output[0].url befindet sich die Audiodatei:

{
  "code": 200,
  "data": {
    "status": "success",
    "storage": "temp",
    "output": [
      {
        "type": "audio",
        "url": "https://temp.hiapi.ai/7c6ttvrbpt/01KZ59P6KDXAXJMGW832X0M2R2-0.mp3",
        "expireAt": 1786415395
      }
    ]
  },
  "message": "success"
}

storage: "temp" bedeutet, dass die URL nur kurz gültig ist – in Tests wurde expireAt auf etwa 7 Tage nach created gesetzt. Lade die Datei nach erfolgreicher Aufgabe so bald wie möglich in deinen eigenen Speicher herunter; betrachte die zurückgegebene URL nicht als permanenten Link.

Python-Version

import time
import requests

API_KEY = "sk-<your-api-key>"
BASE = "https://api.hiapi.ai/v1"
headers = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}

resp = requests.post(f"{BASE}/tasks", headers=headers, json={
    "model": "qwen-audio-3.0-tts-flash",
    "input": {
        "text": "Hello, this is a test of the hiapi text to speech API.",
        "voice": "longanhuan_v3.6",
    },
})
task_id = resp.json()["data"]["taskId"]

while True:
    task = requests.get(f"{BASE}/tasks/{task_id}", headers=headers).json()["data"]
    if task["status"] == "success":
        audio_url = task["output"][0]["url"]
        break
    if task["status"] in ("failed", "error"):
        raise RuntimeError(task)
    time.sleep(1)

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

Vollständiges Eingabe-Schema

Nur text und voice sind Pflichtfelder – alle übrigen sind optional und verwenden bei Auslassung das standardmäßige Verhalten des Modells.

Feld	Typ	Pflichtfeld	Werte
text	string	Ja	Der vorzulesende Text
voice	string (Enum)	Ja	longanhuan_v3.6, longjielidou_v3.6, loongeva_v3.6, loongjohn
format	string (Enum)	Nein	pcm, wav, mp3, opus
sample_rate	integer (Enum)	Nein	8000, 16000, 22050, 24000, 44100, 48000
volume	integer	Nein	0–100

Es gibt keine Parameter speed oder pitch – wird einer davon übergeben, führt das zu einem Schemafehler (additional properties not allowed). Wenn du das Sprechtempo steuern möchtest, passe den Ausgangstext an (Satzzeichen, Pausen) statt über Anfragefelder.

Der Preis beträgt 0,03 USD pro 1.000 Zeichen und wird nach der effektiven Zeichenzahl von Alibaba abgerechnet, nicht nach Anzahl der Anfragen oder Audiodauer – die aktuellen Zahlen findest du auf der hiapi-Preisseite.

Hinweise für die Produktionsumgebung

Wechsle nach der Testphase von Polling zu Callbacks – das ist kostengünstiger für die Infrastruktur und vermeidet Polling-Latenz:

{
  "model": "qwen-audio-3.0-tts-flash",
  "input": { "text": "...", "voice": "longanhuan_v3.6" },
  "callback": { "url": "https://your-server.com/hooks/tts", "when": "final" }
}

callback.when unterstützt nur "final" (wird nur einmal bei Abschluss ausgelöst) – dieses Modell hat keine Zwischenfortschritts-Callbacks.

Behandle Authentifizierungsfehler explizit. Ein ungültiger oder nicht autorisierter Schlüssel gibt HTTP 401 sowie einen strukturierten Antwortkörper zurück:

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

Prüfe error.code programmatisch statt den Nachrichtentext abzugleichen, da sich die Formulierung im Laufe der Zeit ändern kann.

Idempotenz. Die Aufgabenerstellung ist auf deiner Seite nicht idempotent – das Wiederholen derselben Anfrage erstellt eine neue Aufgabe und wird erneut berechnet. Falls dein Aufrufer Wiederholungen ausführen könnte, erzeuge die Anfrage clientseitig nur einmal und speichere die zurückgegebene taskId, bevor du bei Netzwerkfehlern erneut versuchst.

Zu den für alle /v1/tasks-Modelle gemeinsamen Konventionen (Authentifizierung, Polling-Limits, Callback-Signaturen) siehe die API-Dokumentation von hiapi.

Häufige Fragen

Ist qwen-audio-3.0-tts-flash synchron oder asynchron? Asynchron. POST /v1/tasks gibt sofort eine taskId zurück; das eigentliche Audio liegt etwas später vor und kann per Polling oder Callback abgerufen werden. In Tests ist kurzer Text (etwa unter 20 Zeichen) in der Regel innerhalb weniger Sekunden fertig.

Welche Audioformate kann ich erhalten? pcm, wav, mp3 oder opus, festgelegt über input.format. Wird es ausgelassen, verwendet das Modell seine Standardkodierung.

Kann ich Sprechtempo oder Tonhöhe steuern? Über die API dieses Modells nicht – es gibt keine Felder speed oder pitch, und das Schema lehnt unbekannte Eigenschaften ab. Nutze Satzzeichen und Formulierungen im Eingabetext, um den Rhythmus zu gestalten.

Wie lange ist die Ausgabe-Audio-URL gültig? Die Aufgabenantwort enthält storage: "temp"; der expireAt-Zeitstempel im Ausgabeobjekt liegt in Tests etwa 7 Tage nach der Erstellung. Für eine langfristige Aufbewahrung lade die Datei selbst herunter und speichere sie.

Welche Stimmen sind verfügbar? Vier feste Optionen: longanhuan_v3.6, longjielidou_v3.6, loongeva_v3.6 und loongjohn. Jeder andere Wert gibt einen Validierungsfehler zurück, der die akzeptablen Werte auflistet.

Wie wird abgerechnet? Nach Eingabetext pro 1.000 Zeichen (effektive Zeichenzahl von Alibaba), zum Zeitpunkt der Erstellung dieses Artikels 0,03 USD/1K – da sich die Tarife ändern können, bestätige den aktuellen Preis auf der Preisseite.