> ## 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.

# Fish TTS API 연동 설명

> Fish voice generation API guide - Ace Data Cloud

본 인터페이스는 [Fish Audio 공식 TTS API](https://docs.fish.audio/text-to-speech/text-to-speech)를 기반으로 하며, 인증 방식(본 플랫폼 토큰 사용)과 비동기 콜백(`callback_url` 확장)에서만 차이가 있으며, 요청 본체 구조는 상류와 일치합니다. 주소는 `POST https://api.acedata.cloud/fish/tts`입니다.

## 신청 절차

Fish TTS API를 사용하려면 먼저 [Ace Data Cloud 콘솔](https://platform.acedata.cloud/console/applications)에서 API 토큰을 받아야 하며, 이를 보관해 두십시오.

![](https://cdn.acedata.cloud/5hmkdg.jpg)

로그인 또는 등록이 되어 있지 않은 경우 자동으로 로그인 페이지로 리디렉션되어 등록 및 로그인을 초대합니다. 완료 후 현재 페이지로 자동으로 돌아옵니다.

**하나의 API 토큰으로 플랫폼의 모든 서비스를 호출할 수 있으며, 각 서비스마다 별도로 신청할 필요가 없습니다.** 처음 신청 시 무료 할당량이 제공되어 무료로 체험할 수 있습니다; 할당량이 부족할 경우 [콘솔](https://platform.acedata.cloud/console/coin)에서 일반 잔액을 충전할 수 있습니다.

> 📘 전체 문서: [Fish TTS API →](https://platform.acedata.cloud/services/fish)

## 요청 헤더

| Header          | 필수  | 설명                                                                                                                                                           |
| --------------- | --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `authorization` | 예   | `Bearer {token}`，`{token}`은 본 플랫폼에서 신청한 비밀 키입니다.                                                                                                             |
| `content-type`  | 예   | `application/json`입니다.                                                                                                                                       |
| `accept`        | 아니요 | `application/json`입니다.                                                                                                                                       |
| `model`         | 아니요 | TTS 모델, 선택 가능 `s1`、`s2-pro` 또는 `s2.1-pro`이며, 기본값은 `s2-pro`입니다. `s2.1-pro`는 최신 세대이며, `s2-pro`는 표현력이 강합니다; `s1`은 더 안정적이며 긴 텍스트에서 이탈하지 않습니다. 세 가지 모두 동일한 가격입니다. |

## 요청 본체 필드

| 필드             | 유형                  | 필수  | 설명                                                                                                                                                                                   |
| -------------- | ------------------- | --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `text`         | string              | 예   | 합성할 텍스트, 비어 있지 않은 문자열입니다.                                                                                                                                                            |
| `format`       | string              | 아니요 | 출력 오디오 형식, 선택 가능 `mp3`(기본값), `wav`, `pcm`입니다. `wav`와 `pcm`은 모두 WAV 컨테이너로 반환됩니다. `opus`는 지원되지 않으며, 전달 시 직접 `400`을 반환합니다.                                                              |
| `reference_id` | string \| string\[] | 아니요 | 클론 음색 ID( [Fish Model API](https://platform.acedata.cloud/documents/fish-model)에서 생성하거나 [Fish Model Query](https://platform.acedata.cloud/documents/fish-model-query)에서 검색할 수 있습니다). |
| `references`   | object\[]           | 아니요 | 인라인 참조 샘플, 구조는 상류와 일치하며, 각 항목은 `audio`와 `text`를 포함합니다. `reference_id`와 둘 중 하나를 선택해야 합니다.                                                                                             |
| `sample_rate`  | integer             | 아니요 | 샘플링 주파수, 일반적으로 `16000`、`22050`、`44100`입니다. `format=mp3`의 경우 기본값은 44100입니다.                                                                                                           |
| `mp3_bitrate`  | integer             | 아니요 | MP3 비트 전송률, 선택 가능 `64`、`128`、`192`입니다. 오직 `format=mp3`에서만 유효합니다.                                                                                                                     |
| `prosody`      | object              | 아니요 | 운율 오버라이드, `speed`(속도, 1.0은 원속)와 `volume`(음량 이득 dB)을 지원합니다. 예: `{"speed":1.2,"volume":0}`.                                                                                            |
| `chunk_length` | integer             | 아니요 | 상류 분할 길이, 기본적으로 상류에서 결정합니다.                                                                                                                                                          |
| `temperature`  | number              | 아니요 | 샘플링 온도, 범위는 약 0.0–1.0입니다.                                                                                                                                                            |
| `top_p`        | number              | 아니요 | top-p 샘플링 매개변수입니다.                                                                                                                                                                   |
| `latency`      | string              | 아니요 | `normal` 또는 `balanced`이며, 기본적으로 본 인터페이스에서 자동으로 `normal`로 보완합니다(빈 문자열을 전달하면 상류에서 거부됩니다).                                                                                              |
| `normalize`    | boolean             | 아니요 | 텍스트를 정규화할지 여부입니다.                                                                                                                                                                    |
| `callback_url` | string              | 아니요 | 비동기 콜백 주소, 아래의 "비동기 콜백"을 참조하십시오. **이는 공식 인터페이스에 대한 확장입니다.**                                                                                                                          |

> 필드 명칭은 상류와 완전히 일치합니다. `callback_url`을 제외한 나머지 필드의 의미와 값은 [Fish 공식 TTS 문서](https://docs.fish.audio/text-to-speech/text-to-speech)를 참조하십시오.

## 예시 1: 최소 요청(`text` + `format=mp3`)

```shell theme={null}
curl -X POST 'https://api.acedata.cloud/fish/tts' \
  -H 'authorization: Bearer {token}' \
  -H 'content-type: application/json' \
  -d '{
    "text": "Hello world.",
    "format": "mp3"
  }'
```

반환(실제 측정):

```json theme={null}
{
  "audio_url": "https://platform2.cdn.acedata.cloud/fish/e2ffcc06-18da-4a8c-b9aa-9337d0f9ec1d.mp3"
}
```

`audio_url`은 본 플랫폼 CDN을 가리키며, 직접 GET으로 다운로드하거나 `<audio>`에서 재생할 수 있습니다. 링크는 장기적으로 사용 가능하지만, 여전히 자신의 저장소에 한 부를 남기는 것이 좋습니다.

## 예시 2: 클론 음색 `reference_id` 사용

아래는 Fish 플랫폼에서 공개된 스페인어 음색(`_id`는 [Fish Model Query](https://platform.acedata.cloud/documents/fish-model-query)에서 검색할 수 있습니다):

```shell theme={null}
curl -X POST 'https://api.acedata.cloud/fish/tts' \
  -H 'authorization: Bearer {token}' \
  -H 'content-type: application/json' \
  -d '{
    "text": "Hermanos míos, hoy es un buen día.",
    "reference_id": "8d2c17a9b26d4d83888ea67a1ee565b2",
    "format": "mp3"
  }'
```

반환(실제 측정):

```json theme={null}
{
  "audio_url": "https://platform2.cdn.acedata.cloud/fish/b6f161f2-a100-4818-add2-47694f234659.mp3"
}
```

## 예시 3: 속도 / 음량 조절(`prosody`)

```shell theme={null}
curl -X POST 'https://api.acedata.cloud/fish/tts' \
  -H 'authorization: Bearer {token}' \
  -H 'content-type: application/json' \
  -d '{
    "text": "Faster speech with prosody overrides.",
    "prosody": { "speed": 1.2, "volume": 0 },
    "format": "mp3"
  }'
```

반환(실제 측정):

```json theme={null}
{
  "audio_url": "https://platform2.cdn.acedata.cloud/fish/5ade0339-5f11-487e-aacc-06a908271706.mp3"
}
```

`speed`가 1보다 크면 빨라지고, 1보다 작으면 느려집니다; `volume`의 단위는 dB이며, 0은 변하지 않음을 의미하고, 양수는 이득, 음수는 감쇠를 나타냅니다.

## 예시 4: 모델 전환 + 비트 전송률 제어

HTTP 헤더 `model: s1`을 통해 안정형 모델로 전환하고, 요청 본체에 `mp3_bitrate: 128`을 추가하여 MP3 비트 전송률을 제어합니다:

```shell theme={null}
curl -X POST 'https://api.acedata.cloud/fish/tts' \
  -H 'authorization: Bearer {token}' \
  -H 'content-type: application/json' \
  -H 'model: s1' \
  -d '{
    "text": "고음질 비트레이트 mp3",
    "format": "mp3",
    "mp3_bitrate": 128
  }'
```

반환(실측)：

```json theme={null}
{
  "audio_url": "https://platform2.cdn.acedata.cloud/fish/7e7abf3d-3d72-4c9f-8eb6-8af932d7c96e.mp3"
}
```

## 예시 5：PCM 원시 파형

브라우저에서 실시간으로 조합하거나 클라이언트에서 후속 처리(믹싱, 속도 변경)를 해야 하는 경우, `pcm` 사용을 권장합니다：

```shell theme={null}
curl -X POST 'https://api.acedata.cloud/fish/tts' \
  -H 'authorization: Bearer {token}' \
  -H 'content-type: application/json' \
  -d '{
    "text": "안녕",
    "format": "pcm",
    "sample_rate": 16000
  }'
```

반환(실측)：

```json theme={null}
{
  "audio_url": "https://platform2.cdn.acedata.cloud/fish/64adc04b-c196-4a0f-9070-222ba101ce6c.wav"
}
```

> 링크의 확장자는 요청의 `format`을 따릅니다：`mp3`는 `.mp3`를, `wav`와 `pcm`은 `.wav`를 얻습니다(웨이브 컨테이너, 16비트 PCM).

## 비동기 콜백(`callback_url`)

긴 텍스트를 한 번에 합성하는 데는 수초에서 수십 초가 걸릴 수 있으며, 연결이 중단되면 재시도해야 합니다. 요청 본문에 `callback_url`을 전달하면, 인터페이스는 즉시 `{task_id, started_at}`를 반환하고, 상위에서 실제로 완료되면 전체 결과를 POST JSON 형식으로 해당 URL로 콜백합니다. 요청 본문에는 동일한 `task_id`가 포함됩니다.

```shell theme={null}
curl -X POST 'https://api.acedata.cloud/fish/tts' \
  -H 'authorization: Bearer {token}' \
  -H 'content-type: application/json' \
  -d '{
    "text": "오늘 날씨가 정말 좋네요, 함께 산책하러 나가요.",
    "format": "mp3",
    "callback_url": "https://webhook.site/4815f79f-a40f-4078-ac85-1cc126b6bb34"
  }'
```

즉시 반환(실측)：

```json theme={null}
{
  "task_id": "79d82713-2897-4eeb-9934-e7544d471aa7",
  "started_at": 1778462584.742
}
```

조금 후 `callback_url`은 다음과 같은 형식으로 수신합니다：

```json theme={null}
{
  "task_id": "79d82713-2897-4eeb-9934-e7544d471aa7",
  "audio_url": "https://platform2.cdn.acedata.cloud/fish/bd66b8c5-7543-4557-b684-baa72407e336.mp3"
}
```

또한 [Fish Tasks API](https://platform.acedata.cloud/documents/fish-tasks)를 사용하여 `task_id`로 결과를 수동으로 가져올 수 있으며, 자세한 내용은 해당 문서를 참조하십시오.

## 오류 처리

* `400 token_mismatched`：요청 매개변수가 누락되었거나 유효하지 않음(가장 흔한 경우는 `text`가 비어 있거나 `format`에 `mp3`/`wav`/`pcm` 외의 값이 전달됨).
* `401 invalid_token`：인증 토큰이 존재하지 않거나 유효하지 않음.
* `429 too_many_requests`：계정 속도 제한이 발생함.
* `500 api_error`：서버 내부 오류.

오류 응답 예시：

```json theme={null}
{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "fetch failed"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}
```

매개변수 검증 오류는 상위의 pydantic 오류 원문을 `message` 필드에 포함시켜 어떤 필드가 유효하지 않은지 쉽게 찾을 수 있도록 합니다. 예를 들어：

```json theme={null}
{
  "status": 400,
  "message": "[{\"type\":\"literal_error\",\"loc\":[\"format\"],\"msg\":\"Input should be 'pcm' or 'mp3'\",\"input\":\"wav\"}]"
}
```

## 결론

Fish TTS에 접속하는 최소 비용은：이미 `api.fish.audio/v1/tts`를 호출하는 코드에서 인증을 플랫폼 토큰으로 변경하고 요청 본문에 **명시적으로** `format: "mp3"`를 포함하는 것입니다. 긴 텍스트 상황에서는 `callback_url` 비동기 콜백 사용을 권장합니다; 클론 음색 `reference_id`의 발견은 [Fish Model Query](https://platform.acedata.cloud/documents/fish-model-query) 및 [Fish Model Get](https://platform.acedata.cloud/documents/fish-model-get)와 함께 사용하십시오.