# 읽어주기 — /v1/audio/speech

> 글을 소리로. 글자 수로 값이 정해집니다.

> 원문: https://schoolorder.kr/docs/reference/audio-speech

보내신 글을 음성 파일로 돌려드려요. 알림 문구를 읽어주거나 학습 자료에 소리를 붙일 때 쓰세요. 응답이 오디오 바이트라 --output 으로 파일에 받으시면 돼요.

> **부르기 전에 값이 정해져요**
>
> 글자 수로 계산해서, 보내신 글자 수 × 단가가 그대로 차감돼요. 응답 헤더의 x-schoolorder-charged-nano 로 얼마 나갔는지 바로 볼 수 있어요.

**글을 소리로**

```bash
curl https://schoolorder.kr/v1/audio/speech \
  -H "Authorization: Bearer $SCHOOLORDER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "model": "tts-1", "input": "오늘 급식은 김치찌개입니다.", "voice": "alloy" }' \
  --output speech.mp3
```

## 요청 파라미터

**요청 본문 (JSON)**

| 파라미터 | 받는 값 | 저희가 하는 일 |
| --- | --- | --- |
| `model` (필수) | 읽어주기 모델 id | 다른 종류를 넣으시면 400 으로 어느 문인지 알려드려요. |
| `input` (필수) | 문자열 | 이 글자 수로 값이 정해져요. 응답 헤더 x-schoolorder-characters 에 저희가 센 글자 수가 담겨요. |
| `voice · response_format · speed` | 벤더 문서에 있는 값 | 저희가 거르지 않고 그대로 넘겨요 — 벤더 문서를 그대로 보고 쓰시면 돼요. |

**응답 헤더 — 저희가 붙이는 것**

| 파라미터 | 받는 값 | 저희가 하는 일 |
| --- | --- | --- |
| `x-schoolorder-charged-nano` | 정수 | 이 호출로 실제 차감된 금액이에요(나노 단위). 부르고 나서 바로 확인하실 수 있어요. |
| `x-schoolorder-characters` | 정수 | 값을 매길 때 저희가 센 글자 수예요. 청구가 이상하다 싶으면 이 둘을 같이 보시면 돼요. |

## 응답

JSON 이 아니라 오디오 바이트가 그대로 와요. content-type 은 요청한 형식을 따르고(기본 audio/mpeg), 그래서 --output 으로 파일에 받으시면 돼요. 값·글자 수는 위 헤더 두 개로 확인하세요.

> **쓸 수 있는 목소리는 벤더가 정해요**
>
> voice 값은 저희가 거르지 않고 그대로 넘겨서, 그 모델이 아는 이름이면 다 돼요. 목록은 벤더 문서를 보세요 — 저희가 여기 베껴 적으면 벤더가 늘렸을 때 우리 문서만 낡거든요.

## 이 문이 받는 모델

#### 읽어주기 — `POST /v1/audio/speech`

| model | 요금 |
| --- | --- |
| tts-1 | 글자 $15 / 1M 글자 |
| tts-1-hd | 글자 $30 / 1M 글자 |