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 日でした。長期保存が必要な場合は、ご自身でファイルをダウンロードして保存してください。

利用可能な音色は？ 4 つの固定オプション：longanhuan_v3.6、longjielidou_v3.6、loongeva_v3.6、loongjohn です。それ以外の値は検証エラーを返し、許容される値のセットが示されます。

課金はどのように行われますか？ 入力テキストの 1,000 文字あたりで課金されます（アリババの有効文字数）。本稿執筆時点では $0.03/1K です——料率は変更される可能性があるため、現在の価格は料金ページでご確認ください。