hiapi API로 qwen-audio-3.0-tts-flash 사용하는 방법: curl, Python 및 실제 동작하는 요청 예시

qwen-audio-3.0-tts-flash는 알리바바가 출시한 저지연 텍스트 음성 변환 계층으로, hiapi에서 공개되어 음성 에이전트, AI 어시스턴트 응답 및 기타 지연에 민감한 음성 워크플로 구축에 사용할 수 있습니다. 이 가이드에서는 실제로 동작하는 요청, 전체 입력 스키마, 그리고 빠른 테스트에서 프로덕션 통합으로 나아가는 방법을 보여줍니다.

준비물

• 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)

전체 입력 스키마

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)가 반환됩니다. 말하기 속도와 리듬을 제어하려면 요청 필드가 아니라 소스 텍스트(구두점, 휴지)를 조정하세요.

가격은 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 필드가 없으며 스키마가 알 수 없는 속성을 거부합니다. 입력 텍스트의 구두점과 어구를 활용해 리듬을 조형하세요.

출력 오디오 URL의 유효기간은 얼마나 되나요? 작업 응답은 storage: "temp"입니다. 출력 객체의 expireAt 타임스탬프는 테스트에서 생성 후 약 7일이었습니다. 장기 보관이 필요하면 직접 파일을 다운로드하여 저장하세요.

어떤 음색을 사용할 수 있나요? 네 가지 고정 옵션이 있습니다: longanhuan_v3.6, longjielidou_v3.6, loongeva_v3.6, loongjohn. 다른 값을 사용하면 허용되는 값 집합을 나열하는 검증 오류가 반환됩니다.

과금은 어떻게 되나요? 입력 텍스트 1,000자당 과금되며(알리바바의 유효 문자 수), 이 글 작성 시점 기준 $0.03/1K입니다——요율이 변할 수 있으므로 가격 페이지에서 현재 가격을 확인하세요.