Source: https://ailoot.ai/docs/ko/api/audio/
Canonical: https://ailoot.ai/docs/ko/api/audio/
Language: ko

[API](https://ailoot.ai/docs/ko/) 

# Audio

[Markdown](https://ailoot.ai/docs/ko/api/audio/index.md)

OpenAI Audio 형식의 텍스트 음성 변환(TTS)과 음성 인식(STT).

POST`https://api.ailoot.ai/v1/audio/speech`

Audio

```bash
# 음성 합성
curl https://api.ailoot.ai/v1/audio/speech \
  -H "Authorization: Bearer $AILOOT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "qwen-audio-3.0-tts-plus", "input": "안녕하세요! 음성 합성 예제입니다.", "voice": "longanlingxin"}' \
  --output speech.mp3

# 음성 인식
curl https://api.ailoot.ai/v1/audio/transcriptions \
  -H "Authorization: Bearer $AILOOT_API_KEY" \
  -F model=qwen-asr \
  -F file=@meeting.wav
```

```python
# 음성 인식
with open("meeting.wav", "rb") as f:
    tr = client.audio.transcriptions.create(model="qwen-asr", file=f)
print(tr.text)
```

200 OK · 음성 인식

```json
{
  "text": "안녕하세요, 여러분. 이번 주 성과부터 살펴보겠습니다…"
}
```

## 인증

| 매개변수 | 유형 | 필수 | 설명 |
| --- | --- | --- | --- |
| `Authorization` | header | 필수 | 키 형식: `Bearer sk-…`. 다음 헤더도 사용할 수 있습니다: `x-api-key` 또는 `x-goog-api-key`. |

## 음성 합성: 요청 본문

| 매개변수 | 유형 | 필수 | 설명 |
| --- | --- | --- | --- |
| `model` | string | 필수 | 음성 합성 모델: `gemini-3.8-flash-tts`, `qwen-audio-3.0-tts-plus`, `speech-2.8-turbo`, `gemini-3.8-flash-lite-tts`, `speech-2.8-hd`, `gemini-3.1-flash-tts-preview`, `speech-2.6-turbo`, `speech-2.6-hd`, `speech-02-turbo`, `speech-02-hd`. |
| `input` | string | 필수 | 음성으로 변환할 텍스트입니다. MiniMax 모델은 10 000자 미만이며, `qwen-audio-3.0-tts-plus` — 최대 600자입니다. |
| `voice` | string |  | 음성. **MiniMax 모델에서 필수** (`speech-2.8-hd` 및 기타 모델 `speech-…`): MiniMax 음성 식별자(라틴 문자, 숫자, `_` 및 `-`, 최대 128자). 다음 모델의 경우 `qwen-audio-3.0-tts-plus` 기본값은 `longanlingxin`, Gemini TTS 모델의 경우 — `Kore`. |
| `response_format` | string | 선택 사항 | MiniMax — 다음 형식만 지원: `mp3`; `qwen-audio-3.0-tts-plus` — `mp3`, `wav` 또는 `pcm`; Gemini TTS — `wav` 또는 `json` (파일 링크). |

응답은 오디오 파일입니다(MiniMax의 경우 — `audio/mpeg`). 카탈로그에 표시된 대로 텍스트 문자 수 또는 토큰 수를 기준으로 결제됩니다.

## 음성 인식

POST`https://api.ailoot.ai/v1/audio/transcriptions`

| 매개변수 | 유형 | 필수 | 설명 |
| --- | --- | --- | --- |
| `file` | file | 필수 | WAV 오디오 파일 형식: `multipart/form-data`. `qwen-asr`, `qwen-asr-latest` 및 `qwen-audio-3.0-asr-flash` — 최대 5분의 완전한 비압축 PCM WAV, 파일 크기 약 7,5 MB 이하(base64에서는 최대 10 MB). `asr-1.0` — 최대 500초, 50 MB의 PCM WAV. `gemini-3.5-transcribe` — 최대 64 MB의 WAV. |
| `model` | string | 필수 | 음성 인식 모델: `gemini-3.5-transcribe`, `qwen-audio-3.0-asr-flash`, `asr-1.0`. |
| `response_format` | string | 선택 사항 | 오직 `json` (또는 생략). |

필드 `language` 는 이 모델들에서 사용되지 않습니다. 응답: `{"text": "…"}`. 녹음 길이에 따라 결제됩니다(초, 분 또는 시간 — 모델마다 단위가 다릅니다).

## 실시간 음성

대상 모델: `qwen-audio-3.0-realtime-plus` — 다음 WebSocket을 여세요: `wss://api.ailoot.ai/v1/realtime?model=qwen-audio-3.0-realtime-plus` 헤더: `Authorization: Bearer <API_KEY>`. 키는 서버 측에서 전달하세요. 쿼리 문자열의 키는 허용되지 않습니다. 다음 이벤트를 기다리세요: `session.created` (선택한 모델 포함). 그다음 설정, 메시지와 `response.create`를 보내세요. 아래는 오디오 세션에서 텍스트 응답을 받기 위한 연속된 JSON 텍스트 프레임 세 개입니다:

```json
{"type":"session.update","session":{"modalities":["text"],"turn_detection":null,"max_history_turns":20,"instructions":"간결하게 답하세요."}}
```

```json
{"type":"conversation.item.create","item":{"type":"message","role":"user","content":[{"type":"input_text","text":"‘네’라고 말하세요."}]}}
```

```json
{"type":"response.create"}
```

다음 이벤트까지 응답 이벤트를 읽으세요: `response.done` 및 최종 usage. 오류는 다음 이벤트로 전달됩니다: `error`. 매번 확인된 응답의 텍스트·오디오 토큰을 기준으로 결제됩니다. 오디오 입력 이벤트: `input_audio_buffer.append` 및 `audio` — base64 PCM16 mono 16 kHz. 그다음 `input_audio_buffer.commit` 및 `response.create`. 오디오 출력은 PCM16 mono 24 kHz입니다. 이 세션에서는 바이너리 프레임을 허용하지 않습니다.

지원되는 클라이언트 이벤트: `session.update`, `input_audio_buffer.append/commit/clear`, `response.create/cancel`, `conversation.item.create/retrieve/delete`. conversation items에는 메시지/텍스트만 허용됩니다. function tools, 웹 검색, voiceprint는 지원되지 않습니다. 세션 제한: 600초, 응답 20개, 대화 기록 턴 20개, instructions 2000바이트, 클라이언트 텍스트 8000바이트. 비활성 타임아웃은 설정에 따라 다릅니다(기본값 60초).

여기에서 설명하는 음성 모드는 `qwen-audio-3.0-realtime-plus`입니다. 다른 실시간 모델은 규칙이 다릅니다. 경로 `/v1/realtime/sessions` 및 임시 토큰(ephemeral tokens)은 지원되지 않습니다.

궁금한 점이 남았나요? Request ID와 설명을 보내 주시면 해결을 도와드리겠습니다.[지원팀에 문의](mailto:support@ailoot.ai)

## Ailoot · 회사와 그 프로젝트 포트폴리오





Ailoot는 축적된 운영 경험, 폭넓은 고객 기반, 안정적인 서비스, 지속적인 KPI 관리를 바탕으로 합니다.





회사와 그 프로젝트 포트폴리오: 수백만 고객, 매월 수십억 규모의 매출.





Ailoot는 이러한 운영 경험을 고객의 제품, 에이전트, 애플리케이션, 자동화에서 AI 기능을 이용할 수 있는 API 접근에 활용합니다.