Fish TTS API 연동 안내

본 인터페이스는 텍스트 음성 변환, 저장된 음성 호출 및 일회성 즉시 음성 복제를 제공하며, 주소는 POST https://api.acedata.cloud/fish/tts입니다.

신청 절차

Fish TTS API를 사용하려면 먼저 Ace Data Cloud 콘솔에서 API Token을 발급받아 예비용으로 보관하세요.

아직 로그인하거나 등록하지 않았다면 로그인 페이지로 자동 이동하여 등록 및 로그인을 안내하며, 완료 후 현재 페이지로 자동 돌아옵니다. 하나의 API Token으로 플랫폼의 모든 서비스를 호출할 수 있으며, 서비스별로 별도 신청할 필요가 없습니다. 최초 신청 시 무료 할당량이 제공되어 무료로 체험할 수 있으며, 할당량이 부족할 경우 콘솔에서 공통 잔액을 충전할 수 있습니다.

📘 전체 문서: Fish TTS API →

요청 헤더

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에서 생성하거나 Fish Model Query에서 검색할 수 있습니다. `references`와 동시에 사용할 수 없습니다.
`references`	object[]	아니요	일회성 즉시 음성 복제로, 하나의 `{audio, text}` 샘플만 지원합니다. `audio`는 공개 HTTPS MP3/WAV URL이고, `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	아니요	비동기 콜백 주소이며, 자세한 내용은 아래 「비동기 콜백」을 참조하세요. 이는 공식 인터페이스 대비 확장 기능입니다.

일회성 복제는 HTTPS 오디오 URL만 허용하며, MessagePack, Base64, data URI 또는 자격 증명이 포함된 URL은 허용하지 않습니다. 참고 오디오는 10–270초를 권장하며, Studio는 더 보수적인 10–60초 범위를 사용합니다.

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

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

반환(실측):

{
  "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/e2ffcc06-18da-4a8c-b9aa-9337d0f9ec1d-230825dfc559.mp3"
}

audio_url은 이 플랫폼 CDN을 가리키며, 직접 GET으로 다운로드하거나 <audio>에서 재생할 수 있습니다. 최종 성공 응답은 최상위 cost도 반환하며, 그중 amount는 이번에 실제로 차감된 Credits입니다. 계정 할인이 있는 경우 list_amount는 할인 전 할당량을 나타냅니다. 링크는 장기간 사용할 수 있지만, 자체 스토리지에 사본을 보관하는 것을 권장합니다.

예시 2: 복제 음색 `reference_id` 사용

아래에서는 Fish 플랫폼의 공개 스페인어 음색 하나를 사용합니다(_id는 Fish Model Query로 검색하여 얻을 수 있습니다):

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"
  }'

반환(실측):

{
  "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/b6f161f2-a100-4818-add2-47694f234659-6532864739de.mp3"
}

예시 3: 일회성 즉시 음성 복제(`references`)

참고 오디오를 공개 HTTPS 주소에 배치하고, 그 안에서 실제로 말한 정확한 원문을 제공하세요. 이 음성은 이번 합성에만 사용되며 장기 모델을 생성하지 않습니다:

curl -X POST 'https://api.acedata.cloud/fish/tts' \
  -H 'authorization: Bearer {token}' \
  -H 'content-type: application/json' \
  -H 'model: s2-pro' \
  -d '{
    "text": "新的旅程从这一刻开始，让我们一起向前。",
    "format": "mp3",
    "references": [{
      "audio": "https://cdn.acedata.cloud/assets/examples/fish/6220d605-39d0-4d43-9e58-0f12949dc9b9-570cfdf96ad9.mp3",
      "text": "春天的清晨，阳光穿过树叶，落在安静的小路上。"
    }]
  }'

실측 성공 응답:

{
  "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/995dfe37-b187-474d-8323-b08d6678ed8f-6359be9f8873.mp3",
  "cost": {"amount": 0.007609319999999999, "currency": "credit"}
}

방식	수명 주기	적용 시나리오
`references`	이번 TTS 요청에만	임시 사용 또는 매번 음성이 다른 경우
`reference_id`	반복 사용 가능	공용 음성 또는 `/fish/model`을 통해 생성한 장기 음성

예시 3: 말하기 속도 / 볼륨 조절(`prosody`)

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"
  }'

반환(실측):

{
  "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3"
}

speed가 1보다 크면 빨라지고, 1보다 작으면 느려집니다. volume의 단위는 dB이며, 0은 변화 없음을 나타내고, 양수는 증폭, 음수는 감쇠를 나타냅니다.

예시 5: 모델 전환 + 비트레이트 제어

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

curl -X POST 'https://api.acedata.cloud/fish/tts' \
  -H 'authorization: Bearer {token}' \
  -H 'content-type: application/json' \
  -H 'model: s1' \
  -d '{
    "text": "high bitrate mp3",
    "format": "mp3",
    "mp3_bitrate": 128
  }'

반환(실측):

{
  "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/7e7abf3d-3d72-4c9f-8eb6-8af932d7c96e-6f11bf2f30e9.mp3"
}

예시 6: PCM 원시 파형

브라우저에서 실시간 연결을 수행하거나, 클라이언트에서 후속 처리(믹싱, 속도 변경)를 해야 하는 시나리오에서는 pcm 사용을 권장합니다:

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

반환(실측):

{
  "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/64adc04b-c196-4a0f-9070-222ba101ce6c-fc50de38c165.wav"
}

링크의 확장자는 요청의 format을 따릅니다: mp3는 .mp3를 얻고, wav 및 pcm은 .wav를 얻습니다(WAV 컨테이너, 16 bit PCM).

비동기 콜백(`callback_url`)

긴 텍스트를 한 번에 합성하는 데는 수십 초가 걸릴 수 있으며, 연결이 중단되면 재시도가 필요합니다. 요청 본문에 callback_url을 전달하면 인터페이스는 즉시 {task_id, started_at}를 반환하고, 업스트림이 실제로 완료되면 전체 결과를 POST JSON 형식으로 해당 URL에 콜백합니다. 요청 본문에는 동일한 task_id와 이번 최종 청구의 최상위 cost가 포함됩니다. 초기 작업 확인은 아직 합성이 완료되지 않았으므로 cost를 포함하지 않습니다.

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"
  }'

즉시 반환(실측):

{
  "task_id": "79d82713-2897-4eeb-9934-e7544d471aa7",
  "started_at": 1778462584.742
}

잠시 후 callback_url은 다음과 같은 형식으로 수신합니다:

{
  "task_id": "79d82713-2897-4eeb-9934-e7544d471aa7",
  "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/bd66b8c5-7543-4557-b684-baa72407e336-52f2e79732f2.mp3"
}

Fish Tasks API를 사용하여 task_id로 결과를 능동적으로 가져올 수도 있습니다. 최종 상태 기록의 response.cost는 콜백의 cost와 일치하며, 자세한 내용은 해당 문서를 참조하세요.

오류 처리

400 token_mismatched: 요청 매개변수가 누락되었거나 유효하지 않습니다(가장 흔한 경우는 text가 비어 있거나, format에 mp3/wav/pcm 이외의 값을 전달한 경우입니다).
401 invalid_token: 인증 token이 존재하지 않거나 유효하지 않습니다.
429 too_many_requests: 계정 속도 제한이 트리거되었습니다.
500 api_error: 서버 내부 오류입니다.

오류 응답 예시:

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

매개변수 검증 오류는 message 필드에 유효하지 않은 필드를 설명합니다. 예:

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

결론

Fish TTS 연동의 최소 비용은 기존의 api.fish.audio/v1/tts 호출 코드에서 인증을 이 플랫폼 token으로 교체하고, 요청 본문에 명시적으로 format: "mp3"를 포함하는 것입니다. 긴 텍스트 시나리오에는 callback_url 비동기 콜백 사용을 권장합니다. 복제 음색의 reference_id를 찾으려면 Fish Model Query 및 Fish Model Get을 함께 사용하세요.

시작하기

AI 채팅

AI 이미지

AI 비디오

AI 오디오

웹 & 데이터

CAPTCHA

신원

Coding

추가 가이드

Fish TTS API 연동 안내

신청 절차

요청 헤더

요청 본문 필드

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

예시 2: 복제 음색 `reference_id` 사용

예시 3: 일회성 즉시 음성 복제(`references`)

예시 3: 말하기 속도 / 볼륨 조절(`prosody`)

예시 5: 모델 전환 + 비트레이트 제어

예시 6: PCM 원시 파형

비동기 콜백(`callback_url`)

오류 처리

결론

​신청 절차

​요청 헤더

​요청 본문 필드

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

​예시 2: 복제 음색 reference_id 사용

​예시 3: 일회성 즉시 음성 복제(references)

​예시 3: 말하기 속도 / 볼륨 조절(prosody)

​예시 5: 모델 전환 + 비트레이트 제어

​예시 6: PCM 원시 파형

​비동기 콜백(callback_url)

​오류 처리

​결론

신청 절차

요청 헤더

요청 본문 필드

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

예시 2: 복제 음색 `reference_id` 사용

예시 3: 일회성 즉시 음성 복제(`references`)

예시 3: 말하기 속도 / 볼륨 조절(`prosody`)

예시 5: 모델 전환 + 비트레이트 제어

예시 6: PCM 원시 파형

비동기 콜백(`callback_url`)

오류 처리

결론