Alibaba

Qwen Audio 3.0 TTS

qwen-audio-3.0-tts-flash

알리바바 통이(Tongyi)가 호스팅하는 다국어 음성 합성 시리즈로, 저지연 Flash와 고음질 Plus 두 가지 등급을 갖추고 있으며 자연어 명령으로 감정과 표현 스타일을 제어할 수 있습니다

qwen-audio-3.0-tts-flash qwen-audio-3.0-tts-plus

qwen-audio-3.0-tts-flash 사용해 보기

입력

Instruction

출력

파라미터를 입력하고 생성하면 결과가 여기에 표시됩니다.

가격

qwen-audio-3.0-tts-flash per 1,000 characters

단가	$0.030

포지셔닝 소개

qwen-audio-3.0-tts-flash는 Qwen Audio 3.0 TTS 시리즈 중 실시간 상호작용을 겨냥한 텍스트 음성 변환 모델로, HiAPI.ai 통합 인터페이스를 통해 호출됩니다. 입력 텍스트를 자연스러운 음성으로 합성하며 중·영·일·한 등 16개 언어 프롬프트를 지원하고, 자연어 명령으로 감정과 표현 스타일을 조절할 수 있습니다. 음성 비서, 대화형 애플리케이션, 고객센터 안내 방송, 다국어 더빙을 구축하는 개발자, 특히 첫 응답 지연에 민감하고 응답 속도와 음질 사이에서 균형을 잡아야 하는 실시간 시나리오에 적합합니다. 단일 작업의 텍스트 상한은 20000 유니코드 코드 포인트입니다.

핵심 하이라이트

실시간 상호작용을 겨냥한 저지연 등급—— Flash 지향은 실시간 응답으로, 첫 응답 지연이 300밀리초 수준이어 동기 대화 및 음성 안내 경로에 적합합니다.
명령 기반 감정 및 표현 스타일 제어—— 선택적 instruction 필드로 어조와 표현 방식을 설명할 수 있어 오디오 후반 후처리를 줄입니다.
폭넓은 다국어 합성 지원—— 16개 언어 프롬프트를 지원해 동일 모델로 다국어 콘텐츠를 서비스하며 언어별로 모델을 전환할 필요가 없습니다.
출력 형식 및 샘플링 레이트 선택 가능—— pcm, wav, mp3, opus 네 가지 출력을 지원하며, 샘플링 레이트는 8000~48000 Hz로 재생 단말에 맞게 선택할 수 있습니다.

기능 설명

다국어 텍스트 음성 변환: 텍스트와 음색이 주어지면 음성을 합성하며, language_hints로 대상 언어를 지정할 수 있어 한 번의 연동으로 다국어 콘텐츠 제작을 커버합니다.

세밀한 음성 파라미터 조정: 말하기 속도와 음높이는 0.5~2배 구간에서 조정 가능하고, 볼륨은 0~100으로 다양한 재생 기기와 콘텐츠 흐름에 맞출 수 있습니다.

출력 형식 및 샘플링 레이트 제어: mp3, wav, pcm 또는 opus 출력을 선택할 수 있으며, 샘플링 레이트는 8000~48000 Hz를 커버하고 opus에서는 6~510 kbps 비트레이트도 지정할 수 있습니다.

명령 및 시드 제어: instruction 필드는 합성 스타일을 설명하는 데 사용되며, seed로 난수 시드를 고정해 동일한 합성 결과를 재현하고 안정적인 회귀 테스트에 활용할 수 있습니다.

긴 텍스트 단일 작업 합성: 단일 작업은 최대 20000 유니코드 코드 포인트의 텍스트를 받으므로 긴 문단을 호출 측에서 미리 분할할 필요가 없습니다.

적용 시나리오

실시간 음성 비서 개발자: 대화 응답 텍스트—— 대화 시스템의 응답을 실시간으로 음성 합성해 음성 비서나 대화형 애플리케이션의 안내 단계에 바로 연동합니다.
고객센터 및 콜센터: 안내 스크립트 텍스트—— 표준 안내 문구와 알림 내용을 대량으로 음성 변환해 전화 아웃바운드, IVR 안내, 티켓 상태 안내에 사용합니다.
온라인 교육 및 오디오 콘텐츠: 강의 원고—— 강의 자료와 스크립트를 말하기 속도 조절이 가능한 오디오로 합성해 강의 더빙과 오디오북 제작에 활용합니다.
다국어 콘텐츠 팀: 다국어 카피—— 동일한 카피를 언어 힌트에 따라 여러 언어 버전으로 합성해 제품 해외 진출과 다국어 영상 더빙에 사용합니다.

제한 및 선택 가이드

이 모델은 Flash 등급으로 응답 속도를 우선시하여 음색의 자연스러움과 충실도는 같은 시리즈의 Plus 변형보다 낮으므로, 완성 음질 요구가 높은 시나리오에서는 Plus로 전환하는 것이 좋습니다. 시스템 음색은 네 가지 값만 제공되며 텍스트 설명으로 음색을 설계하는 것은 지원하지 않습니다. 음성 복제 기능은 이 모델의 파라미터 범위에 포함되지 않습니다. 합성은 출력 문자 기준으로 과금되며 CJK 문자는 2자로 계산되므로 긴 텍스트를 대량 생성할 때는 사용량을 예측해야 합니다. 자체 호스팅 배포나 오픈소스 가중치가 필요한 경우는 이 모델의 적용 범위에 속하지 않습니다.

생성 작업 제출

POST https://api.hiapi.ai/v1/tasks

헤더

Authorizationstring필수

계정 API 키. 모든 요청에 필수입니다. 예: Bearer YOUR_HIAPI_API_KEY. API 키 받기

Content-Typestring선택

요청 본문은 항상 JSON으로 파싱됩니다. 전송 시 application/json(charset 포함 가능)만 허용되며, 다른 값은 415를 반환합니다. 예: application/json.

Idempotency-Keystring선택

멱등 키. 최대 255바이트. 같은 계정에서 같은 키의 재시도는 태스크를 한 번만 생성하며, 재전송 시 최초의 taskId를 반환합니다.

멱등 키

네트워크 타임아웃이나 클라이언트 자동 재시도 시 같은 키로는 태스크를 한 번만 생성하고 이중 과금되지 않습니다(범위 = API 키의 계정). 업무 고유 식별자(예: "order-42")를 키로 사용할 것을 권장합니다. 같은 키 재전송 시 최초 taskId를 반환하며, 키는 첫 제출 후 24시간 뒤 만료됩니다. 자세한 시나리오 표는 통합 비동기 API 소개 페이지를 참고하세요.

본문

modelstring필수

현재 고정 값: qwen-audio-3.0-tts-flash

routestring선택

현재 고정 값: default

inputobject필수

qwen-audio-3.0-tts-flash 및 루트 default의 비즈니스 파라미터 객체. 아래 파라미터 표를 참조하세요.

ratenumber선택기본값: 1min 0.5max 2

음성 속도 배율로, 기본값은 1이며 이는 정상 속도입니다. 값이 1보다 크면 빨라지고, 1보다 작으면 느려집니다.

seedinteger선택기본값: 0min 0max 65535

결정론적 합성을 위한 난수 시드로, 기본값은 0입니다. 동일한 시드와 입력을 사용하면 합성 결과를 재현할 수 있습니다.

textstring필수minLength 1maxLength 20000

음성으로 합성할 텍스트입니다. hiAPI는 작업당 최대 20,000개의 유니코드 코드 포인트를 허용하며, Alibaba는 과금 시 CJK 표의 문자를 두 글자로, 그 외 문자는 한 글자로 계산합니다.

pitchnumber선택기본값: 1min 0.5max 2

음높이 배율로, 기본값은 1이며 이는 원래 음높이입니다. 값이 커지면 음높이가 높아지고, 작아지면 낮아집니다.

voicestring필수기본값: "longanhuan_v3.6"

Flash 등급에서 지원하는 시스템 음색을 지정하며, 기본값은 longanhuan_v3.6입니다.

옵션:longanhuan_v3.6longjielidou_v3.6loongeva_v3.6loongjohn

formatstring선택기본값: "mp3"

출력 오디오의 컨테이너 형식 또는 원시 PCM 형식이며, 기본값은 mp3입니다.

옵션:pcmwavmp3opus

volumeinteger선택기본값: 50min 0max 100

출력 볼륨으로, 범위는 0에서 100까지이며 기본값은 50입니다.

bit_rateinteger선택기본값: 32min 6max 510

Opus 인코딩의 비트레이트로, 단위는 kbps이며 기본값은 32입니다. 이 매개변수는 format이 opus일 때만 적용됩니다.

instructionstring선택minLength 1

선택적 합성 스타일 지시문으로, 합성 제어 요구 사항을 추가하는 데 사용됩니다. 제공하지 않으면 기본 방식으로 합성합니다.

sample_rateinteger선택기본값: 22050

출력 오디오의 샘플링 레이트로, 단위는 Hz이며 기본값은 22050입니다.

옵션:80001600022050240004410048000

language_hintsarray선택minItems 1maxItems 1

선택적 언어 힌트 배열로, Qwen은 배열의 첫 번째 요소만 처리합니다.

Array [ string ]

callbackobject선택

종료 상태 알림 설정. 생략하면 콜백이 전송되지 않으며 호출 측에서 폴링합니다.

콜백(Webhook)

생성 시 callback.url을 지정하면 태스크 종료 시 HiAPI가 서비스로 POST하여 폴링이 필요 없습니다. 콜백 본문은 태스크 상세와 동일한 구조입니다. 서명 검증·재시도·멱등에 대한 자세한 내용은 통합 비동기 API 소개 페이지의 콜백 설명을 참고하세요.

urlstring필수

callback 사용 시 필수. 태스크 종료 후 이 URL로 POST됩니다. 유효한 http(s) URL이어야 합니다.

whenstring선택기본값: "final"

현재는 final만 지원(success / fail 모두 알림).

옵션:final

storagestring선택기본값: "temp"

산출물 저장 등급: temp(기본·약 7일) 또는 persistent(장기 보관·용량 과금). 잔액 부족이나 저장 한도 초과 시 자동으로 temp로 강등됩니다. 실제 적용된 등급은 태스크 상세 응답에서 확인할 수 있습니다.

옵션:temppersistent

요청 예시

# 비동기 태스크 제출. 성공 시 즉시 taskId 반환(생성 완료 대기 없음)
curl -X POST "https://api.hiapi.ai/v1/tasks" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "qwen-audio-3.0-tts-flash",
  "input": {
    "rate": 1,
    "seed": 0,
    "text": "…",
    "pitch": 1,
    "voice": "longanhuan_v3.6",
    "format": "mp3",
    "volume": 50,
    "bit_rate": 32,
    "sample_rate": 22050
  }
}'

const res = await fetch("https://api.hiapi.ai/v1/tasks", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.HIAPI_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "qwen-audio-3.0-tts-flash",
    input: {
      "rate": 1,
      "seed": 0,
      "text": "…",
      "pitch": 1,
      "voice": "longanhuan_v3.6",
      "format": "mp3",
      "volume": 50,
      "bit_rate": 32,
      "sample_rate": 22050
    }
  }),
});
const task = await res.json();
// { code: 200, message: "success", data: { taskId } }

import os, requests

res = requests.post(
    "https://api.hiapi.ai/v1/tasks",
    headers={"Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}"},
    json={
        "model": "qwen-audio-3.0-tts-flash",
        "input": {
          "rate": 1,
          "seed": 0,
          "text": "…",
          "pitch": 1,
          "voice": "longanhuan_v3.6",
          "format": "mp3",
          "volume": 50,
          "bit_rate": 32,
          "sample_rate": 22050
        }
    },
)
print(res.json())  # { code, message, data: { taskId } }

200 OK

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

400 Bad Request

{
  "code": 400,
  "message": "invalid request",
  "data": null,
  "error_code": "INVALID_REQUEST"
}

작업 상세 조회

GET https://api.hiapi.ai/v1/tasks/:id

응답 필드

taskIdstring필수

태스크 ID. 접두사는 항상 tk-hiapi-.

modelstring필수

확인된 전체 모델명. route 파라미터로 제출한 태스크는 base@route(예: gpt-image-2/text-to-image@ext)를 반환하며, 그 외에는 제출 시의 모델명과 동일합니다.

routestring선택

route 파라미터를 명시해 제출한 태스크에만 나타나며, 제출한 값을 그대로 반환합니다.

statusstring필수

태스크 상태.

상태 값

queued 대기 중, 아직 시작되지 않음. handling 처리 중. archiving 처리 완료, 산출물 준비 중. success 종료: 완료. 산출물 사용 가능(output 반환). fail 종료: 실패(error 반환). 제출 후 status로 판단합니다: success와 fail이 종료 상태이며 나머지는 비종료입니다. 1~3초 간격으로 종료까지 폴링하세요. 성공 시 output[].url에서 산출물을 다운로드하고 expireAt 전에 옮기세요. 장기 보관이 필요하면 생성 시 storage: "persistent"를 사용하세요.

creatednumber필수

태스크 생성 시각(Unix 초).

completednumber필수

종료 상태가 된 Unix 초. 비종료 상태에서는 0.

outputarray선택

status == success일 때만 나타납니다. 산출물 목록 — 항상 배열이며, 하나의 태스크에서 여러 type을 동시에 반환할 수 있습니다(예: video + first_frame).

Array [ object ]

배열 항목

urlstring필수

산출물 URL. 바로 다운로드할 수 있습니다.

typestring필수

현재 가능한 값: video, image, audio, first_frame, last_frame, thumbnail. 이후 확장될 수 있습니다.

expireAtnumber필수

산출물 접근 가능 기한(Unix 초). 만료 전에 다운로드하거나 이전하세요.

errorobject선택

status == fail일 때만 나타납니다.

codestring필수

비즈니스 오류 코드.

messagestring필수

오류 설명.

응답 예시

성공

{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "tk-hiapi-01HZTQ8BX2N3GM3YFK4Z9D7VQR",
    "model": "happyhorse-1-0",
    "status": "success",
    "created": 1777282033,
    "completed": 1777282099,
    "output": [
      {
        "url": "https://cdn.hiapi.ai/tasks/.../video.mp4",
        "type": "video",
        "expireAt": 1777886899
      }
    ]
  }
}

처리 중(비종료)

{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "tk-hiapi-...",
    "model": "happyhorse-1-0",
    "status": "archiving",
    "created": 1777282033,
    "completed": 0
  }
}

실패

{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "tk-hiapi-...",
    "model": "happyhorse-1-0",
    "status": "fail",
    "created": 1777282033,
    "completed": 1777282099,
    "error": {
      "code": "TASK_FAILED",
      "message": "task failed"
    }
  }
}