Como usar qwen-audio-3.0-tts-flash via API hiapi: curl, Python e um exemplo de requisição funcional

qwen-audio-3.0-tts-flash é a camada de conversão de texto em fala de baixa latência lançada pela Alibaba, já disponível na hiapi, e pode ser usada para construir agentes de voz, respostas de assistentes de IA e outros fluxos de trabalho de voz sensíveis à latência. Este guia mostra requisições que realmente funcionam, o schema de entrada completo e como avançar de um teste rápido para uma integração de produção.

O que você precisa preparar

• Uma chave de API hiapi obtida no console hiapi (sk-...).
• curl ou Python com requests — nenhum SDK é necessário.

A hiapi roteia todos os modelos de geração para o mesmo conjunto de endpoints: use POST /v1/tasks para criar uma tarefa e, em seguida, faça polling de GET /v1/tasks/<id> ou receba um callback quando a tarefa for concluída.

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

Uma chamada bem-sucedida retorna imediatamente um id de tarefa — a síntese de voz é assíncrona:

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

Faça polling para obter o resultado:

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

Quando a síntese for concluída, status passa a ser success, e o arquivo de áudio fica em 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 o URL tem validade curta — nos testes, expireAt foi definido para aproximadamente 7 dias após created. Após o sucesso da tarefa, baixe o arquivo para o seu próprio armazenamento o quanto antes; não trate o URL retornado como um link permanente.

Versão em 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 de entrada completo

Apenas text e voice são obrigatórios — os demais são opcionais e, se omitidos, o comportamento padrão do modelo é adotado.

Campo	Tipo	Obrigatório	Valores
text	string	Sim	Texto a ser sintetizado
voice	string (enum)	Sim	longanhuan_v3.6, longjielidou_v3.6, loongeva_v3.6, loongjohn
format	string (enum)	Não	pcm, wav, mp3, opus
sample_rate	integer (enum)	Não	8000, 16000, 22050, 24000, 44100, 48000
volume	integer	Não	0–100

Não há parâmetros speed ou pitch — passar qualquer um deles retorna um erro de schema (additional properties not allowed). Se precisar controlar o ritmo da fala, ajuste o texto de origem (pontuação, pausas), em vez de controlar por campos da requisição.

O preço é de $0.03 por 1.000 caracteres, cobrado com base na contagem de caracteres efetivos da Alibaba, e não pelo número de requisições ou segundos de áudio — confira os números mais recentes na página de preços da hiapi.

Considerações para produção

Após a fase de testes, use callbacks em vez de polling — isso reduz o custo de infraestrutura e evita a latência do 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 aceita apenas "final" (disparado uma única vez na conclusão) — este modelo não tem callbacks de progresso intermediário.

Trate erros de autenticação explicitamente. Chaves inválidas ou não autorizadas retornam HTTP 401 com um corpo de resposta estruturado:

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

Verifique error.code programaticamente, em vez de comparar o texto da mensagem, pois a redação pode mudar com o tempo.

Idempotência. A criação de tarefas não é idempotente do seu lado — repetir exatamente a mesma requisição cria uma nova tarefa e cobra novamente. Se o seu chamador puder repetir a chamada, gere a requisição uma única vez no cliente e salve o taskId retornado antes de repetir a chamada por falha de rede.

Para as convenções comuns a todos os modelos de /v1/tasks (autenticação, limites de polling, assinatura de callbacks), consulte a documentação da API da hiapi.

Perguntas frequentes

qwen-audio-3.0-tts-flash é síncrono ou assíncrono? Assíncrono. POST /v1/tasks retorna imediatamente o taskId; o áudio real fica pronto logo depois e pode ser obtido por polling ou callback. Nos testes, textos curtos (abaixo de cerca de 20 caracteres) costumam ficar prontos em poucos segundos.

Quais formatos de áudio posso receber? pcm, wav, mp3 ou opus, definidos via input.format. Se omitido, o modelo usa sua codificação padrão.

Posso controlar a velocidade ou o tom da fala? Não por meio da API deste modelo — não há campos speed ou pitch, e o schema rejeita propriedades desconhecidas. Use a pontuação e a redação do texto de entrada para moldar o ritmo.

Qual é a validade do URL do áudio gerado? A resposta da tarefa traz storage: "temp"; o timestamp expireAt no objeto de saída fica em torno de 7 dias após a criação nos testes. Para armazenamento de longo prazo, baixe e guarde o arquivo por conta própria.

Quais vozes estão disponíveis? Quatro opções fixas: longanhuan_v3.6, longjielidou_v3.6, loongeva_v3.6 e loongjohn. Qualquer outro valor retorna um erro de validação, listando o conjunto de valores aceitos.

Como é cobrado? Por 1.000 caracteres do texto de entrada (contagem de caracteres efetivos da Alibaba); no momento da redação deste artigo, $0.03/1K — como as tarifas podem mudar, confirme o preço atual na página de preços.