Come usare qwen-audio-3.0-tts-flash tramite l'API hiapi: curl, Python e un esempio di richiesta funzionante

qwen-audio-3.0-tts-flash è il livello di sintesi vocale a bassa latenza di Alibaba, ora disponibile su hiapi, utilizzabile per creare agenti vocali, risposte di assistenti AI e altri flussi di lavoro vocali sensibili alla latenza. Questa guida mostra richieste realmente funzionanti, lo schema completo degli input e come passare da un test rapido a un'integrazione in produzione.

Cosa ti serve

• Una chiave API hiapi (sk-...) ottenuta dalla console hiapi.
• curl oppure Python con requests — nessun SDK necessario.

hiapi instrada tutti i modelli generativi verso lo stesso set di endpoint: crea un'attività con POST /v1/tasks, poi interroga GET /v1/tasks/<id> oppure ricevi un callback al completamento dell'attività.

Esempio minimo funzionante

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

Una chiamata riuscita restituisce immediatamente un id attività — la sintesi vocale avviene in modo asincrono:

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

Esegui il polling per ottenere il risultato:

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

Al termine della sintesi, status diventa success e il file audio è disponibile in 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" indica che l'URL ha una validità molto breve — nei test, expireAt è impostato a circa 7 giorni dopo created. Scarica il file nel tuo storage il prima possibile dopo il successo dell'attività; non trattare l'URL restituito come un link permanente.

Versione 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)

Schema completo degli input

Solo text e voice sono obbligatori — tutti gli altri sono facoltativi e, se omessi, si applica il comportamento predefinito standard del modello.

Campo	Tipo	Obbligatorio	Valori
text	string	Sì	Il testo da leggere ad alta voce
voice	string (enumerazione)	Sì	longanhuan_v3.6, longjielidou_v3.6, loongeva_v3.6, loongjohn
format	string (enumerazione)	No	pcm, wav, mp3, opus
sample_rate	integer (enumerazione)	No	8000, 16000, 22050, 24000, 44100, 48000
volume	integer	No	0–100

Non esistono parametri speed o pitch — passare uno di essi restituisce un errore di schema (additional properties not allowed). Se devi controllare il ritmo del parlato, regola il testo di origine (punteggiatura, pause) invece di usare campi della richiesta.

Il prezzo è di $0,03 ogni 1.000 caratteri, calcolato sul numero di caratteri validi di Alibaba, non sul numero di richieste o sui secondi di audio — consulta i dati aggiornati sulla pagina dei prezzi di hiapi.

Considerazioni per la produzione

Dopo la fase di test, usa i callback invece del polling — è più economico per l'infrastruttura ed evita la latenza del 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 supporta solo "final" (viene attivato una sola volta al completamento) — questo modello non offre callback di avanzamento intermedi.

Gestisci esplicitamente gli errori di autenticazione. Una chiave non valida o non autorizzata restituisce HTTP 401 e un corpo di risposta strutturato:

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

Controlla error.code a livello di codice, invece di confrontare il testo del messaggio, poiché la formulazione può cambiare nel tempo.

Idempotenza. La creazione dell'attività non è idempotente dal tuo lato — ripetere esattamente la stessa richiesta crea una nuova attività e viene addebitata di nuovo. Se il tuo chiamante potrebbe riprovare, genera la richiesta una sola volta sul client e salva il taskId restituito prima di riprovare in caso di errore di rete.

Per le convenzioni comuni a tutti i modelli /v1/tasks (autenticazione, limiti di polling, firma dei callback), consulta la documentazione API di hiapi.

Domande frequenti

qwen-audio-3.0-tts-flash è sincrono o asincrono? Asincrono. POST /v1/tasks restituisce immediatamente un taskId; l'audio effettivo sarà pronto poco dopo, ottenibile tramite polling o callback. Nei test, testi brevi (circa 20 caratteri o meno) si completano di solito in pochi secondi.

Quali formati audio posso ottenere? pcm, wav, mp3 o opus, impostati tramite input.format. Se omesso, il modello usa la sua codifica predefinita.

Posso controllare la velocità o il tono? No tramite l'API di questo modello — non esistono campi speed o pitch, e lo schema rifiuta proprietà sconosciute. Sfrutta la punteggiatura e la formulazione del testo di input per modellare il ritmo.

Quanto dura l'URL dell'audio di output? La risposta dell'attività riporta storage: "temp"; il timestamp expireAt nell'oggetto di output nei test è di circa 7 giorni dopo la creazione. Per una conservazione a lungo termine, scarica e archivia il file autonomamente.

Quali voci sono disponibili? Quattro opzioni fisse: longanhuan_v3.6, longjielidou_v3.6, loongeva_v3.6 e loongjohn. Qualsiasi altro valore restituisce un errore di convalida che elenca l'insieme dei valori accettabili.

Come viene fatturato? In base ai caratteri del testo di input ogni 1.000 caratteri (numero di caratteri validi di Alibaba), al momento della stesura pari a $0,03/1K — poiché le tariffe possono cambiare, verifica il prezzo attuale sulla pagina dei prezzi.