> ## Documentation Index
> Fetch the complete documentation index at: https://docs.acedata.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# OpenAI 음성 합성 API (/v1/audio/speech)

> OpenAI generation API guide - Ace Data Cloud

텍스트를 자연 음성으로 합성합니다. **OpenAI의 `/v1/audio/speech`와 완전히 호환됩니다.** 모든 OpenAI SDK는 `base_url`을 `https://api.acedata.cloud`로 설정하고, 키를 당신의 AceData Token으로 변경하면 바로 사용할 수 있습니다. 인터페이스는 음성 바이트 스트림을 동기적으로 반환합니다.

* **요청 주소**: `POST https://api.acedata.cloud/v1/audio/speech` (별칭 `POST /openai/audio/speech`)
* **인증**: 요청 헤더 `Authorization: Bearer {token}`
* **요금**: 요청 텍스트 바이트 수에 따라 요금이 부과되며, 약 OpenAI 공식 가격의 85%입니다 (아래 표 참조).

## 요청 매개변수

| 필드 | 유형 | 필수 | 설명 |
| - | - | - | - |
| `input` | string | 예 | 합성할 텍스트입니다. |
| `model` | string | 아니오 | `tts-1`(더 빠름) 또는 `tts-1-hd`(더 높은 음질, 기본값). |
| `voice` | string | 아니오 | `alloy`, `echo`, `fable`, `onyx`, `nova`, `shimmer` 중 하나, 기본값 `alloy`. |
| `response_format` | string | 아니오 | `mp3`(기본값), `opus`, `aac`, `flac`, `wav`, `pcm`. |
| `speed` | number | 아니오 | 속도 0.25–4.0, 기본값 1.0. |

## 예시

```shell theme={null}
curl -X POST 'https://api.acedata.cloud/v1/audio/speech' \
  -H 'authorization: Bearer {token}' \
  -H 'content-type: application/json' \
  -o speech.mp3 \
  -d '{
    "model": "tts-1-hd",
    "input": "What if one API gave you every AI video model?",
    "voice": "nova",
    "response_format": "mp3"
  }'
```

반환되는 것은 음성 파일 자체(`Content-Type: audio/mpeg`)이며, `speech.mp3`에 직접 기록하여 재생할 수 있습니다.

공식 OpenAI Python SDK 사용:

```python theme={null}
from openai import OpenAI
client = OpenAI(base_url="https://api.acedata.cloud/v1", api_key="{token}")
client.audio.speech.create(model="tts-1-hd", voice="nova", input="Hello from AceData.").stream_to_file("speech.mp3")
```

## 가격

| 모델 | OpenAI 공식 가격 | 본 플랫폼 가격(약 85% 할인) |
| - | - | - |
| `tts-1` | \$15 / 100만 문자 | 약 \$12.75 / 100만 문자 |
| `tts-1-hd` | \$30 / 100만 문자 | 약 \$25.5 / 100만 문자 |

> 요청 텍스트 바이트 수에 따라 요금이 부과됩니다; `official_price` 필드는 OpenAI 공식 가격을 비교하기 위해 표시됩니다.

## 오류 코드

| 상태 코드 | 코드 | 설명 |
| - | - | - |
| 400 | `bad_request` | `input`이 비어 있거나 매개변수가 잘못되었습니다. |
| 401 | `authentication_failed` | 토큰이 유효하지 않습니다. |
| 403 | `used_up` | 잔액이 부족합니다. |
| 429 | `too_many_requests` | 요청이 너무 잦습니다. |
| 500 | `api_error` | 상위/내부 오류입니다. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.