如何通过 hiapi API 使用 qwen-audio-3.0-tts-flash：curl、Python 与一个可用的请求示例

qwen-audio-3.0-tts-flash 是阿里推出的低延迟文本转语音层级，已在 hiapi 上开放，可用于构建语音智能体、AI 助手回复以及其他对延迟敏感的语音工作流。本演练展示了确实可用的请求、完整的输入 schema，以及如何从快速测试推进到生产集成。

你需要准备什么

• 在 hiapi 控制台获取的 hiapi API 密钥（sk-...）。
• curl 或带 requests 的 Python——无需 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 被设置为大约在 created 之后 7 天。任务成功后请尽快将文件下载到你自己的存储；不要把返回的 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)

完整输入 schema

只有 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 参数——传入其中任何一个都会返回 schema 错误（additional properties not allowed）。如需控制语速节奏，请调整源文本（标点、停顿），而不是通过请求字段控制。

价格为 每 1,000 字符 $0.03，按阿里的有效字符数计费，而非按请求次数或音频秒数——请查看 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 模型通用的约定（鉴权、轮询限制、回调签名），请参阅 hiapi 的 API 文档。

常见问题

qwen-audio-3.0-tts-flash 是同步还是异步？ 异步。POST /v1/tasks 会立即返回 taskId；实际音频稍后即可就绪，可通过轮询或回调获取。在测试中，短文本（约 20 字符以下）通常几秒内即可完成。

我可以拿回哪些音频格式？ pcm、wav、mp3 或 opus，通过 input.format 设置。若省略，模型使用其默认编码。

我能控制语速或音调吗？ 不能通过此模型的 API 控制——没有 speed 或 pitch 字段，且 schema 会拒绝未知属性。请利用输入文本中的标点和措辞来塑造节奏。

输出音频 URL 的有效期是多久？ 任务响应为 storage: "temp"；输出对象中的 expireAt 时间戳在测试中大约是创建后 7 天。若需长期保存，请自行下载并存储文件。

有哪些可用音色？ 四个固定选项：longanhuan_v3.6、longjielidou_v3.6、loongeva_v3.6 和 loongjohn。任何其他值都会返回校验错误，并列出可接受的取值集合。

如何计费？ 按输入文本每 1,000 字符计费（阿里的有效字符数），截至本文撰写时为 $0.03/1K——由于费率可能变化，请在定价页面确认当前价格。