Comment utiliser qwen-audio-3.0-tts-flash via l'API hiapi : curl, Python et un exemple de requête fonctionnel

qwen-audio-3.0-tts-flash est le niveau de synthèse vocale à faible latence lancé par Alibaba, désormais disponible sur hiapi pour construire des agents vocaux, des réponses d'assistants IA et d'autres flux de travail vocaux sensibles à la latence. Cette présentation montre des requêtes réellement fonctionnelles, le schéma d'entrée complet, et comment passer d'un test rapide à une intégration en production.

Ce qu'il vous faut

• Une clé API hiapi (sk-...) obtenue dans la console hiapi.
• curl ou Python avec requests — aucun SDK nécessaire.

hiapi route tous les modèles de génération vers un ensemble d'endpoints communs : créez une tâche avec POST /v1/tasks, puis soit interrogez GET /v1/tasks/<id> en boucle, soit recevez un callback une fois la tâche terminée.

Exemple minimal fonctionnel

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"
    }
  }'

Un appel réussi renvoie immédiatement un identifiant de tâche — la synthèse vocale est asynchrone :

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

Interrogez le résultat :

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

Une fois la synthèse terminée, status passe à success et le fichier audio se trouve dans output[0].url :

{
  "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" signifie que cette URL a une durée de validité très courte — lors des tests, expireAt était fixé à environ 7 jours après created. Téléchargez le fichier dans votre propre stockage dès que la tâche réussit ; ne traitez pas l'URL renvoyée comme un lien permanent.

Version Python

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)

Schéma d'entrée complet

Seuls text et voice sont obligatoires — tous les autres sont facultatifs et, s'ils sont omis, le comportement par défaut standard du modèle s'applique.

Champ	Type	Obligatoire	Valeurs
text	string	Oui	Texte à lire à voix haute
voice	string (énumération)	Oui	longanhuan_v3.6, longjielidou_v3.6, loongeva_v3.6, loongjohn
format	string (énumération)	Non	pcm, wav, mp3, opus
sample_rate	integer (énumération)	Non	8000, 16000, 22050, 24000, 44100, 48000
volume	integer	Non	0–100

Il n'existe aucun paramètre speed ou pitch — en transmettre un renvoie une erreur de schéma (additional properties not allowed). Pour contrôler le rythme de la parole, ajustez le texte source (ponctuation, pauses) plutôt que de passer par un champ de requête.

Le prix est de 0,03 $ pour 1 000 caractères, facturé selon le nombre de caractères effectifs d'Alibaba, et non par nombre de requêtes ou par seconde d'audio — consultez les chiffres les plus récents sur la page de tarification hiapi.

Considérations pour la production

Passez aux callbacks plutôt qu'au polling après la phase de test — c'est moins coûteux pour l'infrastructure et évite la latence du polling :

{
  "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 ne prend en charge que "final" (déclenché une seule fois à la fin) — ce modèle ne propose pas de callback de progression intermédiaire.

Gérez explicitement les erreurs d'authentification. Une clé invalide ou non autorisée renvoie un HTTP 401 avec un corps de réponse structuré :

{
  "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": "..."
  }
}

Vérifiez error.code par programmation plutôt que de faire correspondre le texte du message, car la formulation peut évoluer avec le temps.

Idempotence. La création de tâche n'est pas idempotente de votre côté — réessayer exactement la même requête crée une nouvelle tâche et facture à nouveau. Si votre appelant est susceptible de réessayer, générez la requête une seule fois côté client et conservez le taskId renvoyé avant de réessayer en cas de défaillance réseau.

Pour les conventions communes à tous les modèles /v1/tasks (authentification, limites de polling, signature des callbacks), consultez la documentation API de hiapi.

Questions fréquentes

qwen-audio-3.0-tts-flash est-il synchrone ou asynchrone ? Asynchrone. POST /v1/tasks renvoie immédiatement un taskId ; l'audio réel est prêt plus tard, récupérable par polling ou callback. Lors des tests, un texte court (environ 20 caractères ou moins) est généralement terminé en quelques secondes.

Quels formats audio puis-je récupérer ? pcm, wav, mp3 ou opus, définis via input.format. En cas d'omission, le modèle utilise son encodage par défaut.

Puis-je contrôler la vitesse ou la hauteur de la voix ? Non, pas via l'API de ce modèle — il n'existe aucun champ speed ou pitch, et le schéma rejette les propriétés inconnues. Utilisez la ponctuation et la formulation du texte d'entrée pour façonner le rythme.

Combien de temps l'URL audio de sortie reste-t-elle valide ? La réponse de la tâche indique storage: "temp" ; l'horodatage expireAt de l'objet de sortie était d'environ 7 jours après la création lors des tests. Pour une conservation à long terme, téléchargez et stockez le fichier vous-même.

Quelles voix sont disponibles ? Quatre options fixes : longanhuan_v3.6, longjielidou_v3.6, loongeva_v3.6 et loongjohn. Toute autre valeur renvoie une erreur de validation listant l'ensemble des valeurs acceptées.

Comment la facturation fonctionne-t-elle ? Facturation par 1 000 caractères de texte d'entrée (nombre de caractères effectifs d'Alibaba), soit 0,03 $/1K au moment de la rédaction — les tarifs étant susceptibles de changer, vérifiez le prix actuel sur la page de tarification.