Fish 모델 생성 API 연동 설명

본 인터페이스는 Fish Audio 공식 Model API를 기반으로 하여 오디오 샘플을 기반으로 장기적으로 재사용 가능한 클론 음성 모델을 생성하는 데 사용됩니다. 주소는 POST https://api.acedata.cloud/fish/model입니다.

참고 음성을 일시적으로 사용할 경우 모델을 생성할 필요 없이 Fish TTS API의 references를 사용하여 즉시 클론할 수 있습니다. 기존 음색을 페이지로 검색하려면 Fish Model Query API를 참조하십시오. _id로 단일 음색 세부정보를 조회하려면 Fish Model Get API를 참조하십시오.

신청 절차

Fish Model API를 사용하려면 먼저 Ace Data Cloud 콘솔에서 API Token을 받아야 합니다. 이를 보관하십시오.

로그인 또는 등록하지 않은 경우 자동으로 로그인 페이지로 리디렉션되어 등록 및 로그인을 초대합니다. 완료 후 현재 페이지로 자동으로 돌아옵니다. 하나의 API Token으로 플랫폼의 모든 서비스를 호출할 수 있으며, 각 서비스에 대해 별도로 신청할 필요가 없습니다. 처음 신청 시 무료 할당량이 제공되어 무료로 체험할 수 있습니다. 할당량이 부족할 경우 콘솔에서 일반 잔액을 충전할 수 있습니다.

📘 전체 문서: Fish Model API →

요청 본문 필드

필드	유형	필수	설명
`title`	string	예	음색 이름, 콘솔 목록에서 인식하는 데 사용됩니다.
`voices`	string	예	오디오 샘플의 HTTP(S) URL (단일 문자열, 배열이 아님). 본 인터페이스는 multipart/바이너리 업로드를 지원하지 않으므로, 오디오를 공개적으로 접근 가능한 객체 저장소에 먼저 저장해야 합니다.
`description`	string	아니오	음색 설명.
`cover_image`	string	아니오	커버 이미지 HTTP(S) URL.
`tags`	string[]	아니오	공용 라이브러리 검색 태그, 예: `["male","narration","zh"]`.
`texts`	string[]	아니오	샘플에 해당하는 참고 텍스트(발음 교정을 위해 사용됨).
`enhance_audio_quality`	boolean	아니오	훈련 전에 샘플의 음질을 향상시킬지 여부.
`generate_sample`	boolean	아니오	훈련 완료 후 자동으로 샘플 오디오를 생성할지 여부.

필드는 상위와 완전히 일치하며, Fish 공식 문서를 참조하십시오.

예시: 개인 클론 음색 생성

curl -X POST 'https://api.acedata.cloud/fish/model' \
  -H 'authorization: Bearer {token}' \
  -H 'content-type: application/json' \
  -d '{
    "title": "내 클론 음색",
    "description": "한 편의 팟캐스트 녹음을 클론한 중국어 음색",
    "voices": "https://example.com/sample-voice.mp3",
    "cover_image": "https://cdn.acedata.cloud/e724d7f13d.png"
  }'

주의: voices는 문자열(단일 오디오 URL)이어야 하며, 배열이 아닙니다. ["..."]로 전달하면 상위에서 거부됩니다.

성공적인 응답은 Fish 플랫폼의 ModelEntity 객체를 직접 반환합니다(아래 예시는 우리가 테스트한 최소 사용 가능한 음색으로, 가독성을 위해 일부 긴 필드를 삭제했습니다):

{
  "_id": "e5c6db52c3ed417f9cb2e5a33fb04667",
  "type": "tts",
  "title": "copilot-smoke-test",
  "description": "api.acedata.cloud의 스모크 테스트",
  "cover_image": "coverimage/e5c6db52c3ed417f9cb2e5a33fb04667",
  "train_mode": "fast",
  "state": "trained",
  "tags": [],
  "samples": [
    {
      "title": "기본 샘플",
      "text": "스승님, [어조가 단호하게] 저는 정말 이 산의 쌀쌀한 날들이 지긋지긋합니다!...",
      "task_id": "6a1bf398dfae49dca0e23159214342a0",
      "audio": "https://platform.r2.fish.audio/task/6a1bf398dfae49dca0e23159214342a0.mp3"
    }
  ],
  "created_at": "2026-05-10T03:52:55.601000Z",
  "updated_at": "2026-05-10T03:52:55.601000Z",
  "languages": ["zh"],
  "visibility": "public",
  "default_text": "스승님, [어조가 단호하게] 저는 정말 이 산의 쌀쌀한 날들이 지긋지긋합니다!...",
  "like_count": 0,
  "mark_count": 0,
  "shared_count": 0,
  "task_count": 0,
  "author": {
    "_id": "780f2b2f862d41a08c0507bbbda77eb6",
    "nickname": "Penny Conrad",
    "avatar": "avatars/780f2b2f862d41a08c0507bbbda77eb6.jpg"
  }
}

_id는 이후 Fish TTS API에서 reference_id 필드의 값으로 사용되어 해당 클론 음색으로 음성 합성을 수행하는 데 사용됩니다:

curl -X POST 'https://api.acedata.cloud/fish/tts' \
  -H 'authorization: Bearer {token}' \
  -H 'content-type: application/json' \
  -d '{
    "text": "안녕하세요, 이것은 제가 방금 생성한 클론 음색으로 합성한 음성입니다.",
    "reference_id": "e5c6db52c3ed417f9cb2e5a33fb04667",
    "format": "mp3"
  }'

샘플 요구 사항

경험치(상위와 일치하며, Fish 공식 문서를 참조할 수 있습니다):

길이는 30초 이상, 5분 이내가 가장 효과적입니다; 10분을 초과하면 한계 수익이 크지 않습니다.
샘플링 주파수는 16 kHz 이상, 단일 채널 또는 스테레오 모두 가능합니다.
내용은 최대한 깨끗해야 합니다: 배경 음악, 에코, 명백한 환경 소음이 없어야 하며, 동일한 화자가 말해야 합니다.
형식은 mp3 / wav를 권장합니다.

샘플 품질에 대한 확신이 없다면 enhance_audio_quality: true를 함께 전달하여 상위에서 먼저 음질 향상을 수행하도록 할 수 있습니다.

요금 설명

음색 클론 모델 생성(POST /fish/model)은 무료이며, 어떠한 비용도 발생하지 않습니다; 음색 조회 인터페이스(Fish Model Query, Fish Model Get) 또한 요금이 발생하지 않습니다. 비용은 이후 Fish TTS 호출 시 사용량에 따라 발생합니다.

오류 처리

400 token_mismatched：요청 매개변수가 누락되었거나 유효하지 않음(가장 흔한 경우는 voices가 URL이 아니거나 배열로 전달됨).
401 invalid_token：인증 토큰이 존재하지 않거나 유효하지 않음.
429 too_many_requests：계정 속도 제한이 발생함.
500 api_error：서버 내부 오류.

오류 응답 예시:

{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "voices is required and must be an HTTP(S) URL pointing to an audio file"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}

결론

이 API를 호출하려면 공개적으로 접근 가능한 샘플 오디오 URL을 준비하고, 이를 voices 필드에 넣으면 _id를 얻을 수 있으며, 이를 /fish/tts의 reference_id에 제공하면 엔드 투 엔드의 “클론 → 합성”이 완료됩니다. 흔한 함정은 voices가 문자열이어야 하며, 배열이 될 수 없다는 것입니다.

시작하기

AI 채팅

AI 이미지

AI 비디오

AI 오디오

웹 & 데이터

CAPTCHA

신원

프록시

고급

Coding

Fish 모델 생성 API 연동 설명

신청 절차

요청 본문 필드

예시: 개인 클론 음색 생성

샘플 요구 사항

요금 설명

오류 처리

결론

​신청 절차

​요청 본문 필드

​예시: 개인 클론 음색 생성

​샘플 요구 사항

​요금 설명

​오류 처리

​결론

신청 절차

요청 본문 필드

예시: 개인 클론 음색 생성

샘플 요구 사항

요금 설명

오류 처리

결론