Coze에서 FishAudio 사용하기

FishAudio는 Coze 플러그인 스토어에서 두 개의 플러그인을 제공합니다. 일반적으로 플러그인을 설치하고, 사용자 지정 요청이 필요할 때만 HTTP API를 직접 설정하세요.

API Key 준비

1. Fish Audio API 관리 페이지에서 Coze 전용 API Key를 만듭니다.
2. API 크레딧을 확인합니다.
3. 도구에 다음 형식으로 전달합니다.

Authorization: Bearer YOUR_FISH_AUDIO_API_KEY

Bearer 뒤에는 공백이 하나 있어야 합니다. 각 사용자는 자신의 Key를 사용하며 사용량은 해당 Fish Audio 계정에 청구됩니다.

개인 플러그인 직접 만들기

스토어 플러그인을 사용하지 않으려면 FishAudio TTS 文字转语音 OpenAPI, FishAudio 图片/视频对口型 OpenAPI, FishAudio 文字对口型 OpenAPI 또는 FishAudio 专属语音合成 OpenAPI를 다운로드해 기존 서비스 기반 클라우드 플러그인으로 Coze에 가져오세요. 인증 없음을 선택하고 실행 시 고객 자신의 Authorization을 입력합니다. 자세한 절차는 English guide를 참고하세요.

오른쪽 위의 Import 사용을 권장합니다. 이 경로에는 OpenAPI YAML만 필요합니다. 왼쪽에 ai_plugin (JSON), 오른쪽에 openapi (YAML)가 보이면 </> 코드 생성 페이지입니다. ai_plugin을 비워 두지 말고 왼쪽에는 대응하는 *.ai-plugin.json, 오른쪽에는 같은 접두사의 *.openapi.yaml을 붙여 넣으세요. manifest.json은 FishAudio 배포 패키지 목록일 뿐 ai_plugin 파일이 아닙니다.

현재 FishAudio TTS 文字转语音과 FishAudio 图片/视频对口型은 스토어에서 제공되며, FishAudio 文字对口型과 FishAudio 专属语音合成은 비공개 가져오기용 플러그인으로만 제공됩니다.

FishAudio TTS 文字转语音 사용

1. FishAudio TTS 文字转语音를 자신의 Coze 공간에 추가합니다.
2. 에이전트 또는 워크플로에 TTS 도구를 추가합니다.
3. Authorization, 입력 텍스트, Voice ID와 선택 설정을 입력합니다.
4. 반환된 audio_url을 재생, 다운로드 또는 Media Sync 플러그인에 연결합니다.

첫 테스트에는 짧은 문장을 사용하세요. Voice ID는 유효한 시스템 음성이거나 현재 계정에서 사용할 수 있는 사용자 지정 음성이어야 합니다.

FishAudio 图片/视频对口型 사용

FishAudio 图片/视频对口型는 두 개의 도구를 제공합니다.

create_media_sync에 Authorization, video_url, audio_url을 전달합니다. 응답의 data.id를 저장하고 이후 조회에서 jobId로 사용하세요. 작업 생성에는 API 크레딧이 사용됩니다.

get_media_sync_job 결과는 다음과 같이 처리합니다.

• processing: 기다린 후 같은 jobId를 다시 조회합니다.
• completed: data.result_url을 읽습니다.
• failed: data.error_message를 읽습니다.

조회가 시간 초과되거나 처리 중이어도 create_media_sync를 다시 호출하지 마세요. 중복 작업과 중복 과금이 발생할 수 있습니다.

텍스트에서 동기화 비디오 생성

아래처럼 스토어 플러그인 두 개를 연결하거나, TTS와 립싱크를 한 번의 생성 작업으로 결합한 비공개 플러그인 FishAudio 文字对口型을 가져올 수 있습니다.

텍스트 + Voice ID
      ↓
FishAudio TTS 文字转语音
      ↓ audio_url
비디오 URL + audio_url
      ↓
create_media_sync
      ↓ data.id
jobId 저장 → 15~30초 대기 → get_media_sync_job
      ↓
completed: data.result_url
failed: data.error_message

비공개 플러그인은 create_text_lip_sync 다음에 get_text_lip_sync_job을 사용합니다. 새 작업마다 새로운 Idempotency-Key를 사용하고, 완전히 동일한 요청을 재시도할 때만 기존 값을 재사용하세요.

자동 폴링에는 최대 조회 횟수와 전체 제한 시간을 설정하세요.

미디어 URL 및 Key 보안

비디오와 오디오 URL은 Fish Audio 서비스에서 직접 다운로드할 수 있어야 합니다. 웹 페이지 URL, 로컬 경로, 만료된 서명 URL은 사용할 수 없습니다. Coze 임시 URL은 Fish Audio 다운로드가 끝날 때까지 유효해야 합니다.

Authorization은 일반 도구 입력이므로 Coze 대화, 디버그 또는 실행 로그에 표시될 수 있습니다. Coze 전용 Key를 만들고 실제 Key가 포함된 화면이나 템플릿을 공유하지 말며 테스트 후 교체하거나 폐기하세요. 공개 플러그인에 공용 Key를 포함하지 마세요.

문제 해결

• 401: Bearer 형식, 불필요한 공백 및 Key 유효성을 확인합니다.
• 402: API 크레딧을 확인합니다. 멤버십 크레딧과는 별도 잔액입니다.
• 미디어 다운로드 실패: URL이 직접 접근 가능하고 충분히 오래 유효한지 확인합니다.
• processing 유지: 같은 jobId를 계속 조회하고 작업을 다시 만들지 마세요.
• Key가 로그에 표시됨: 해당 Key를 폐기하고 새 Coze 전용 Key를 만드세요.

고급: TTS HTTP API 직접 호출

Coze HTTP 노드에서 POST https://fishaudio.org/v1/audio/speech를 호출하고 Authorization 및 Content-Type: application/json을 설정할 수 있습니다. 본문에는 model, voice, input, response_format: "mp3"를 넣고 응답 형식은 JSON이 아닌 파일 또는 바이너리로 설정하세요.

관련 문서

• OpenAI 호환 TTS
• Lip Sync API
• 사용자 지정 음성 만들기
• Coze 플러그인 스토어