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://platform2.cdn.acedata.cloud/fish/e2ffcc06-18da-4a8c-b9aa-9337d0f9ec1d.mp3"
}

audio_url은 본 플랫폼 CDN을 가리키며, 직접 GET으로 다운로드하거나 <audio>에서 재생할 수 있습니다. 최종 성공 응답은 최상위 cost를 반환하며, 여기서 amount는 이번에 실제로 차감된 크레딧입니다; 계정 할인 시 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://platform2.cdn.acedata.cloud/fish/b6f161f2-a100-4818-add2-47694f234659.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://platform2.cdn.acedata.cloud/fish/6220d605-39d0-4d43-9e58-0f12949dc9b9.mp3",
      "text": "春天的清晨，阳光穿过树叶，落在安静的小路上。"
    }]
  }'

실제 측정 성공 응답:

{
  "audio_url": "https://platform2.cdn.acedata.cloud/fish/995dfe37-b187-474d-8323-b08d6678ed8f.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://platform2.cdn.acedata.cloud/fish/5ade0339-5f11-487e-aacc-06a908271706.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://platform2.cdn.acedata.cloud/fish/7e7abf3d-3d72-4c9f-8eb6-8af932d7c96e.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://platform2.cdn.acedata.cloud/fish/64adc04b-c196-4a0f-9070-222ba101ce6c.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://platform2.cdn.acedata.cloud/fish/bd66b8c5-7543-4557-b684-baa72407e336.mp3"
}

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

오류 처리

400 token_mismatched: 요청 매개변수가 누락되었거나 유효하지 않음 (가장 흔한 경우는 text가 비어 있거나 format이 mp3/wav/pcm 외의 값을 전달한 경우).
401 invalid_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를 호출하는 코드에서 인증을 이 플랫폼의 토큰으로 변경하고 요청 본문에 명시적으로 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`)

오류 처리

결론