Fish Model Get API 연동 설명

본 인터페이스는 Fish Audio 공식 Model API를 기반으로 하며, _id로 단일 클론 음색의 전체 세부정보를 조회하는 데 사용됩니다. 주소는 GET https://api.acedata.cloud/fish/model/{id}입니다.

음색 생성은 Fish Model Create API를 참조하시기 바랍니다. 페이지네이션 검색은 Fish Model Query API를 참조하시기 바랍니다.

신청 절차

Fish Model API를 사용하려면 먼저 Ace Data Cloud 콘솔에서 API Token을 받아야 하며, 이를 보관해 두시기 바랍니다.

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

📘 전체 문서: Fish Model API →

경로 매개변수

매개변수	필수	설명
`id`	예	음색의 `_id` (32자리 16진수 문자열). Fish Model Create 생성 시 반환되거나, Fish Model Query로 검색하여 얻을 수 있습니다.

요청 본체 및 쿼리 매개변수는 없습니다.

예시: 공개 스페인어 음색의 전체 세부정보 가져오기

curl 'https://api.acedata.cloud/fish/model/8d2c17a9b26d4d83888ea67a1ee565b2' \
  -H 'authorization: Bearer {token}'

반환 (실제 측정, 읽기 편하도록 samples[].audio의 서명 쿼리 문자열을 삭제했습니다):

{
  "_id": "8d2c17a9b26d4d83888ea67a1ee565b2",
  "type": "tts",
  "title": "Valentino Narración Biblica Fer",
  "description": "차분하고 영적인 톤을 가진 성숙하고 권위 있는 남성 목소리입니다. 종교적 내레이션, 교육 콘텐츠 및 스페인어로 된 전문적인 스토리텔링에 적합합니다.",
  "cover_image": "coverimage/8d2c17a9b26d4d83888ea67a1ee565b2",
  "train_mode": "fast",
  "state": "trained",
  "tags": [
    "male", "old", "narration", "calm", "serious",
    "authoritative", "professional", "clear", "Spanish"
  ],
  "samples": [
    {
      "title": "기본 샘플",
      "text": "Hermanos míos, recordemos las palabras del Señor en estos tiempos difíciles. Como dice la Escritura, la fe mueve montañas, y el amor de Dios nos guía en cada paso del camino. Mantengamos firme nuestra confianza en Su divina providencia.",
      "task_id": "59ce7df6935c42249759327ddf70f37b",
      "audio": "https://c97f3361a1c971323738e24f451a0225.r2.cloudflarestorage.com/fish-platform-data/task/59ce7df6935c42249759327ddf70f37b.mp3?X-Amz-...signed..."
    }
  ],
  "created_at": "2025-03-13T08:11:10.326000Z",
  "updated_at": "2026-05-03T09:01:41.437000Z",
  "languages": ["es"],
  "visibility": "public",
  "lock_visibility": false,
  "dmca_taken_down": false,
  "default_text": "Hermanos míos, recordemos las palabras del Señor...",
  "quality": null,
  "like_count": 4344,
  "mark_count": 4409,
  "shared_count": 590,
  "task_count": 708461,
  "unliked": false,
  "liked": false,
  "marked": false,
  "author": {
    "_id": "1b82fb6a329c4462b67aa9ee0a42046f",
    "nickname": "Fernando Caicedo",
    "avatar": "avatars/1b82fb6a329c4462b67aa9ee0a42046f.jpg"
  }
}

얻은 _id를 Fish TTS의 reference_id에 직접 입력하면 동일한 음색의 음성을 합성할 수 있습니다:

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

목록 인터페이스와의 차이점

필드	`GET /fish/model` (목록)	`GET /fish/model/{id}` (상세)
`samples[].audio`	단기 R2 캐시 URL	현재 서명된 R2 직링크 (쿼리 서명 포함)
`unliked` / `liked` / `marked` / `dmca_taken_down`	동일하게 존재	동일하게 존재
`default_text` / `lock_visibility`	동일하게 존재	동일하게 존재

단순히 미리 듣기만 원하신다면 목록 인터페이스의 samples[].audio로 충분합니다. 더 안정적인 다운로드 링크가 필요하다면 본 인터페이스를 사용하는 것이 좋습니다.

응답 필드 (발췌)

필드	유형	설명
`_id`	string	음색 ID ( `/fish/tts`의 `reference_id`에 사용).
`type`	string	모델 유형, 일반적으로 `tts`.
`title`	string	음색 이름.
`description`	string	긴 설명.
`state`	string	훈련 상태: `trained`는 사용 가능, `training`은 아직 훈련 중임을 나타냅니다.
`tags`	string[]	공용 라이브러리 태그.
`samples`	object[]	미리 설정된 샘플, `title`, `text`, `task_id`, `audio` 직링크 포함.
`languages`	string[]	음색이 잘하는 언어 코드.
`visibility`	string	`public` 또는 `private`.
`like_count`	integer	공용 라이브러리 좋아요 수.
`task_count`	integer	역사적 합성 횟수 (인기 순위 참고용).
`author`	object	상위 저자 정보: `_id` / `nickname` / `avatar`.
`created_at`	string	ISO 8601 생성 시간.
`updated_at`	string	ISO 8601 최근 업데이트 시간.

요금 설명

본 인터페이스는 요금이 부과되지 않습니다 — ID로 단일 음색 세부정보를 조회하는 것은 무료 작업입니다. 음색 생성(Fish Model Create) 또한 무료이며, Fish TTS로 음성을 합성할 때만 사용량에 따라 요금이 발생합니다.

오류 처리

400 token_mismatched：경로의 id가 유효한 형식이 아니거나 상위에서 “모델을 찾을 수 없음”이라고 보고합니다.
401 invalid_token：인증 토큰이 존재하지 않거나 유효하지 않습니다.
404 not_found：지정된 _id가 Fish 상위에서 보이지 않습니다(음색이 삭제되었거나, 비공개이거나, 다른 계정에 속함).
429 too_many_requests：계정 속도 제한이 발생했습니다.
500 api_error：서버 내부 오류입니다.

존재하지 않는 ID를 실제로 요청할 때 상위는 직접 400 Model not found를 반환합니다(실제 테스트):

curl 'https://api.acedata.cloud/fish/model/test123' \
  -H 'authorization: Bearer {token}'

반환:

{ "status": 400, "message": "Model not found" }

오류 응답 예시:

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

결론

음색 _id를 알고 있을 때 이 인터페이스를 사용하여 전체 ModelEntity를 가져오는 것이 가장 일반적인 사용법입니다: (1) samples[].audio를 미리 듣기, (2) _id를 /fish/tts의 reference_id에 제공하여 합성을 완료합니다. 제목이나 태그만 있는 경우 먼저 Fish Model Query를 사용하여 검색하십시오.

시작하기

AI 채팅

AI 이미지

AI 비디오

AI 오디오

웹 & 데이터

CAPTCHA

신원

프록시

고급

Coding

Fish Model Get API 연동 설명

신청 절차

경로 매개변수

예시: 공개 스페인어 음색의 전체 세부정보 가져오기

목록 인터페이스와의 차이점

응답 필드 (발췌)

요금 설명

오류 처리

결론

​신청 절차

​경로 매개변수

​예시: 공개 스페인어 음색의 전체 세부정보 가져오기

​목록 인터페이스와의 차이점

​응답 필드 (발췌)

​요금 설명

​오류 처리

​결론

신청 절차

경로 매개변수

예시: 공개 스페인어 음색의 전체 세부정보 가져오기

목록 인터페이스와의 차이점

응답 필드 (발췌)

요금 설명

오류 처리

결론