Cómo usar qwen-audio-3.0-tts-flash con la API de hiapi: curl, Python y un ejemplo de solicitud funcional

qwen-audio-3.0-tts-flash es el nivel de texto a voz de baja latencia lanzado por Alibaba, ya disponible en hiapi, y puede usarse para construir agentes de voz, respuestas de asistentes de IA y otros flujos de trabajo de voz sensibles a la latencia. Este tutorial muestra solicitudes que realmente funcionan, el esquema de entrada completo y cómo pasar de una prueba rápida a una integración en producción.

Qué necesitas preparar

• Una clave de API de hiapi (sk-...) obtenida en la consola de hiapi.
• curl o Python con requests; no se necesita SDK.

hiapi enruta todos los modelos de generación a través del mismo conjunto de endpoints: crea una tarea con POST /v1/tasks y luego consulta repetidamente GET /v1/tasks/<id> o recibe una devolución de llamada cuando la tarea termine.

Ejemplo mínimo funcional

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 llamada correcta devuelve inmediatamente un id de tarea; la síntesis de voz se realiza de forma asíncrona:

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

Consulta repetidamente para obtener el resultado:

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

Cuando la síntesis finaliza, status cambia a success y el archivo de audio está en 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 que la URL tiene una validez muy corta; en las pruebas, expireAt se estableció aproximadamente 7 días después de created. Descarga el archivo a tu propio almacenamiento lo antes posible tras el éxito de la tarea; no trates la URL devuelta como un enlace permanente.

Versión en 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)

Esquema de entrada completo

Solo text y voice son obligatorios; el resto son opcionales y, si se omiten, se aplica el comportamiento predeterminado del modelo.

Campo	Tipo	¿Obligatorio?	Valores
text	string	Sí	El texto que se va a leer en voz alta
voice	string (enumeración)	Sí	longanhuan_v3.6, longjielidou_v3.6, loongeva_v3.6, loongjohn
format	string (enumeración)	No	pcm, wav, mp3, opus
sample_rate	integer (enumeración)	No	8000, 16000, 22050, 24000, 44100, 48000
volume	integer	No	0–100

No hay parámetros speed ni pitch; pasar cualquiera de ellos devuelve un error de esquema (additional properties not allowed). Si necesitas controlar el ritmo del habla, ajusta el texto de origen (puntuación, pausas) en lugar de usar campos de la solicitud.

El precio es de $0.03 por cada 1,000 caracteres, facturado según el recuento de caracteres válidos de Alibaba, no por número de solicitudes ni por segundos de audio; consulta las cifras más recientes en la página de precios de hiapi.

Consideraciones para producción

Una vez superada la fase de pruebas, usa devoluciones de llamada en lugar de sondeos: resulta más económico para la infraestructura y evita la latencia del sondeo:

{
  "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 solo admite "final" (se activa una sola vez al completarse); este modelo no tiene devoluciones de llamada de progreso intermedio.

Gestiona explícitamente los errores de autenticación. Una clave no válida o no autorizada devuelve HTTP 401 junto con un cuerpo de respuesta estructurado:

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

Comprueba error.code mediante programación en lugar de hacer coincidir el texto del mensaje, ya que la redacción puede cambiar con el tiempo.

Idempotencia. La creación de tareas no es idempotente por tu parte: reintentar exactamente la misma solicitud crea una nueva tarea y vuelve a facturar. Si tu cliente puede reintentar, genera la solicitud una sola vez en el lado del cliente y guarda el taskId devuelto antes de reintentar por un fallo de red.

Para conocer las convenciones comunes a todos los modelos de /v1/tasks (autenticación, límites de sondeo, firma de devoluciones de llamada), consulta la documentación de la API de hiapi.

Preguntas frecuentes

¿qwen-audio-3.0-tts-flash es síncrono o asíncrono? Asíncrono. POST /v1/tasks devuelve inmediatamente un taskId; el audio real estará listo más tarde y se puede obtener mediante sondeo o devolución de llamada. En las pruebas, los textos cortos (de unos 20 caracteres o menos) suelen completarse en pocos segundos.

¿Qué formatos de audio puedo obtener? pcm, wav, mp3 u opus, configurados mediante input.format. Si se omite, el modelo usa su codificación predeterminada.

¿Puedo controlar la velocidad o el tono? No a través de la API de este modelo: no hay campos speed ni pitch, y el esquema rechaza propiedades desconocidas. Usa la puntuación y la redacción del texto de entrada para moldear el ritmo.

¿Cuánto tiempo es válida la URL del audio de salida? La respuesta de la tarea indica storage: "temp"; la marca de tiempo expireAt del objeto de salida es, según las pruebas, aproximadamente 7 días después de la creación. Si necesitas conservarlo a largo plazo, descarga y almacena el archivo por tu cuenta.

¿Qué voces están disponibles? Cuatro opciones fijas: longanhuan_v3.6, longjielidou_v3.6, loongeva_v3.6 y loongjohn. Cualquier otro valor devuelve un error de validación que enumera el conjunto de valores aceptables.

¿Cómo se factura? Se factura por cada 1,000 caracteres del texto de entrada (recuento de caracteres válidos de Alibaba), y en el momento de redactar este artículo es $0.03/1K; como las tarifas pueden cambiar, confirma el precio actual en la página de precios.