Как использовать qwen-audio-3.0-tts-flash через API hiapi: curl, Python и рабочий пример запроса

qwen-audio-3.0-tts-flash — это низколатентный уровень синтеза речи от Alibaba, уже доступный на hiapi. Его можно использовать для голосовых агентов, ответов ИИ-ассистентов и других голосовых сценариев, чувствительных к задержкам. В этом руководстве показаны реально работающий запрос, полная схема входных данных и то, как перейти от быстрой проверки к производственной интеграции.

Что вам понадобится

• API-ключ hiapi (sk-...), полученный в консоли hiapi.
• curl или Python с requests — SDK не нужен.

hiapi маршрутизирует все генеративные модели через один и тот же набор эндпоинтов: создайте задачу с помощью POST /v1/tasks, а затем либо опрашивайте GET /v1/tasks/<id>, либо получайте обратный вызов после завершения задачи.

Минимальный рабочий пример

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

Успешный вызов сразу возвращает id задачи — синтез речи выполняется асинхронно:

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

Опрашивайте результат:

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

После завершения синтеза status станет success, а в 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" означает, что URL действует очень недолго — в тестах expireAt устанавливается примерно через 7 дней после created. Скачайте файл в собственное хранилище как можно скорее после успешного завершения задачи; не рассматривайте возвращённый URL как постоянную ссылку.

Версия на 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)

Полная схема входных данных

Обязательны только text и voice — остальные параметры необязательны, и при их пропуске применяется стандартное поведение модели по умолчанию.

Поле	Тип	Обязательно	Значения
text	string	Да	Текст для озвучивания
voice	string (перечисление)	Да	longanhuan_v3.6, longjielidou_v3.6, loongeva_v3.6, loongjohn
format	string (перечисление)	Нет	pcm, wav, mp3, opus
sample_rate	integer (перечисление)	Нет	8000, 16000, 22050, 24000, 44100, 48000
volume	integer	Нет	0–100

Параметров speed или pitch нет — передача любого из них вернёт ошибку схемы (additional properties not allowed). Если нужно управлять темпом речи, корректируйте исходный текст (пунктуацию, паузы), а не поля запроса.

Цена — $0.03 за 1 000 символов, оплата идёт по количеству действительных символов Alibaba, а не по числу запросов или секундам аудио — актуальные цифры смотрите на странице цен hiapi.

Рекомендации для производственной среды

После тестовой фазы переходите с опроса на обратные вызовы — это дешевле для инфраструктуры и позволяет избежать задержек опроса:

{
  "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 поддерживает только "final" (срабатывает один раз при завершении) — у этой модели нет промежуточных обратных вызовов о прогрессе.

Явно обрабатывайте ошибки аутентификации. Недействительный или неавторизованный ключ возвращает HTTP 401 и структурированное тело ответа:

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

Проверяйте error.code программно, а не сопоставляйте текст сообщения, поскольку формулировка может со временем меняться.

Идемпотентность. Создание задачи не является идемпотентным на вашей стороне — повтор完全相同ного запроса создаст новую задачу и снова спишет средства. Если ваш вызывающий код может выполнять повторные попытки, генерируйте запрос на клиенте только один раз и сохраняйте возвращённый taskId перед повторной попыткой из-за сетевого сбоя.

Общие соглашения для всех моделей /v1/tasks (аутентификация, ограничения опроса, подпись обратных вызовов) описаны в документации API hiapi.

Частые вопросы

qwen-audio-3.0-tts-flash — синхронный или асинхронный? Асинхронный. POST /v1/tasks сразу возвращает taskId; само аудио будет готово позже, его можно получить опросом или через обратный вызов. В тестах короткий текст (примерно до 20 символов) обычно обрабатывается за несколько секунд.

Какие аудиоформаты я могу получить? pcm, wav, mp3 или opus, задаётся через input.format. Если не указан, модель использует кодирование по умолчанию.

Могу ли я управлять скоростью или тоном? Через API этой модели — нет: полей speed или pitch нет, а схема отклоняет неизвестные свойства. Формируйте ритм с помощью пунктуации и формулировок во входном тексте.

Как долго действует URL выходного аудио? В ответе задачи storage: "temp"; временная метка expireAt в объекте вывода в тестах составляет примерно 7 дней после создания. Для долгосрочного хранения скачайте и сохраните файл самостоятельно.

Какие голоса доступны? Четыре фиксированных варианта: longanhuan_v3.6, longjielidou_v3.6, loongeva_v3.6 и loongjohn. Любое другое значение вернёт ошибку валидации со списком допустимых значений.

Как рассчитывается оплата? По входному тексту за каждые 1 000 символов (действительные символы Alibaba), на момент написания — $0.03/1K; поскольку тарифы могут меняться, проверяйте актуальную цену на странице цен.