콘텐츠로 이동

VoiceScriptPlayer Docs

Hailuo

Support on Patreon

🚫 Hailuo 사용량 초과 오류 (HailuoQuotaExceeded)¶

원인¶

이번 요청에 필요한 문자 수가 현재 남아 있는 Hailuo 월간 사용량보다 많습니다.
Free 플랜 또는 Patreon 후원 등급에서 제공되는 사용량을 모두 소진했습니다.
한 번에 너무 긴 문장을 요청하면 사용량이 급격히 증가할 수 있습니다.

해결 방법¶

월간 사용량 리셋까지 기다리기
- Hailuo 사용량은 매월 1일 자동 초기화됩니다.
- 리셋 후 다시 시도하면 정상적으로 처리될 수 있습니다.
Patreon 후원 등급 업그레이드
- 더 많은 Hailuo 사용량이 필요하다면 Patreon 후원 등급을 업그레이드해 주세요.
🔗 Patreon Membership
https://www.patreon.com/VoiceScriptPlayer/membership
Hailuo 직접 구독하기
- Voice Script Server API 대신, Hailuo API를 직접 구독하여 무제한 또는 더 큰 용량으로 사용할 수 있습니다.
- 대량 음성 변환 작업을 자주 하는 사용자에게 추천됩니다.
🔗 Hailuo 직접 연동 가이드
https://voicescriptplayer.github.io/vsp-docs/ko/ai/hailuo-subscription/
Voice Script Server API 설정 확인
- 프로그램 설정에서 API 키가 정상적으로 입력되었는지 확인하세요.
- API 키가 비활성화되었거나 잘못 입력되면 사용량 조회가 실패할 수 있습니다.

💡 네트워크 연결 오류 (NetworkConnectionError)¶

원인¶

인터넷 연결이 불안정하거나 끊어졌습니다.
VPN/Proxy 또는 방화벽이 Hailuo 서버 접근을 차단하고 있습니다.
서버가 일시적으로 응답하지 않을 수 있습니다.

해결 방법¶

인터넷 연결 상태 확인
- Wi-Fi 또는 유선 네트워크가 정상적으로 연결되어 있는지 확인하세요.
방화벽 또는 VPN 확인
- https://api.minimax.io 가 차단되어 있지 않은지 확인합니다.
- VPN 또는 Proxy를 끄고 다시 시도해 보세요.
잠시 후 다시 시도
- 일시적인 서버 장애일 수 있으므로 몇 분 뒤 재시도해 보세요.

💡 인증 실패 (HailuoAuthError)¶

원인¶

Hailuo API 키가 잘못되었거나 만료되었습니다.
인증 헤더가 올바르지 않거나 누락되었습니다.

해결 방법¶

정확한 API 키 입력
- Hailuo 사이트에서 발급받은 API 키를 정확히 복사하여 입력하세요.
API 키 재발급
- 키가 만료되었거나 삭제된 경우, Hailuo 계정에서 새로운 키를 발급받아 주세요.
Voice Script Server API 사용 시
- Patreon 연동을 통해 발급된 API 키가 활성화 상태인지 확인하세요.

💡 요청 시간 초과 (HailuoTimeoutError)¶

원인¶

Hailuo 서버 응답이 제한 시간 내에 도착하지 않았습니다.
일시적으로 서버가 과부하 상태일 수 있습니다.

해결 방법¶

잠시 후 다시 시도
- 대부분 일시적인 문제로, 재시도하면 해결됩니다.
네트워크 안정성 확인
- 느리거나 끊기는 연결은 응답 시간을 지연시킵니다.
텍스트 길이 줄이기
- 너무 긴 입력은 처리 시간이 오래 걸릴 수 있습니다.

💡 요청 제한 초과 (HailuoRateLimitError)¶

원인¶

짧은 시간 안에 너무 많은 요청(초당 요청)이 발생했습니다.

해결 방법¶

1–2분 기다린 후 다시 시도
- 요청 제한은 일정 시간 후 자동으로 해제됩니다.
요청 간 간격 늘리기
- 빠른 반복 요청을 피하고, 1초 이상의 간격을 두고 요청하세요.

💡 TPM(분당 처리량) 초과 (HailuoTPMError)¶

원인¶

분당 처리 가능한 문자 수(Token Per Minute)를 초과했습니다.

해결 방법¶

요청 텍스트 분할
- 긴 문장을 여러 번으로 나눠서 요청하세요.
요청 텀 늘리기
- 일정 시간 간격을 두고 요청하면 정상 처리됩니다.

💡 입력에 허용되지 않는 문자 포함 (HailuoIllegalCharacterError)¶

원인¶

문장에 이모지나 특수 기호 등 Hailuo가 읽지 못하는 문자가 포함되어 있습니다.

해결 방법¶

이모지 및 특수문자 제거
- 예: 💕 ✨ 🔥 ❌ 등
문장 단순화
- 문제되는 문자를 제거하고 다시 시도하세요.

💡 입력 형식 오류 (HailuoInvalidInputFormat)¶

원인¶

음성 변환에 필요한 설정 값이 잘못되었거나 누락되었습니다.
텍스트 또는 음성 설정 데이터가 정상적으로 인식되지 않았습니다.

해결 방법¶

음성 설정 초기화
- 속도/볼륨/피치 값을 기본값으로 되돌려 다시 시도하세요.
텍스트 수정
- 너무 긴 문장, 복잡한 문장보다 간단한 문장이 더 안정적입니다.
프로그램 최신 버전 사용
- 최신 버전에서는 대부분의 설정 오류가 자동 해결됩니다.

💡 크레딧 부족 (HailuoCreditError)¶

원인¶

Hailuo 계정의 크레딧이 부족합니다.
무료 사용 한도를 초과했습니다.

해결 방법¶

Hailuo 계정에서 잔액 확인
크레딧 충전 후 재시도
대량 사용 시 유료 플랜 고려

💡 잘못된 요청 (HailuoRequestError)¶

원인¶

요청한 텍스트 또는 음성 설정 값이 비정상적이거나 범위를 벗어났습니다.

해결 방법¶

텍스트 단순화
음성 설정 값 초기화
짧은 문장으로 다시 시도

💡 서버 오류 (HailuoServerError)¶

원인¶

Hailuo 서버 내부 오류
일시적인 서버 장애 또는 점검

해결 방법¶

잠시 후 다시 시도
Hailuo 상태 페이지 또는 공지 확인
문제가 반복되면 다른 음성으로 시도

💡 응답 분석 실패 (HailuoParseError)¶

원인¶

Hailuo 서버에서 정상적인 데이터가 반환되지 않았습니다.
예상치 못한 형식의 응답입니다.

해결 방법¶

다시 시도
텍스트 길이 줄이기
프로그램 최신 버전 사용

💡 오디오 데이터 없음 (HailuoEmptyAudio)¶

원인¶

매우 짧은 문장은 음성으로 변환되지 않을 수 있습니다.
특정 음성에서만 발생하는 문제일 가능성도 있습니다.

해결 방법¶

조금 더 긴 문장으로 시도
다른 음성(VoiceId) 사용
재시도

💡 오디오 포맷 오류 (HailuoInvalidAudioFormat)¶

원인¶

서버가 잘못된 오디오 데이터를 반환했습니다.

해결 방법¶

다시 시도
짧은 문장으로 테스트
프로그램 최신 버전 확인

💡 오디오 처리 실패 (HailuoAudioProcessingError)¶

원인¶

음성 변환 과정에서 오류가 발생했습니다.
오디오 데이터가 손상되었을 수 있습니다.

해결 방법¶

다시 시도
다른 문장으로 테스트
다른 음성 설정으로 시도

💡 잔액 부족 (HailuoInsufficientBalanceError)¶

원인¶

Hailuo 계정의 크레딧 또는 잔액이 부족하여 요청을 처리할 수 없습니다.

해결 방법¶

계정 잔액 확인
- Hailuo 대시보드에서 남은 잔액을 확인해 주세요.
충전 진행
- 서비스를 계속 이용하려면 계정을 충전해야 합니다.

💡 내부 서버 오류 (HailuoInternalError)¶

원인¶

Hailuo 서버 내부에서 예상치 못한 문제가 발생했습니다.

해결 방법¶

잠시 후 재시도
- 일시적인 장애일 가능성이 높습니다. 잠시 기다린 후 다시 시도해 주세요.
상태 확인
- 문제가 지속될 경우 서비스 공지사항을 확인하세요.

💡 민감한 입력 감지 (HailuoSensitiveInputError)¶

원인¶

입력한 텍스트 프롬프트에 정책상 허용되지 않는 민감한 내용(정치, 폭력, 성인물 등)이 포함되어 있습니다.

해결 방법¶

프롬프트 수정
- 입력한 텍스트 내용을 검토하고, 민감한 단어나 표현을 순화하거나 제거해 주세요.

💡 민감한 출력 감지 (HailuoSensitiveOutputError)¶

원인¶

생성된 결과물이 민감한 내용으로 판단되어 출력이 차단되었습니다.

해결 방법¶

입력 내용 조정
- 입력 프롬프트를 수정하여 다른 결과가 생성되도록 유도해 주세요.

💡 시스템 오류 (HailuoSystemError)¶

원인¶

데이터베이스 또는 시스템 구성 요소의 문제로 요청이 실패했습니다.

해결 방법¶

재시도
- 서버 부하 등으로 인한 일시적 문제일 수 있으므로 잠시 후 다시 시도해 주세요.

💡 연결 제한 초과 (HailuoConnectionLimitError)¶

원인¶

동시에 너무 많은 연결이 요청되어 서버가 처리를 거부했습니다.

해결 방법¶

요청 빈도 조절
- 동시 요청 수를 줄이거나 잠시 기다렸다가 요청해 주세요.
문의하기
- 문제가 지속되면 Hailuo 지원팀에 문의가 필요할 수 있습니다.

💡 ASR 유사성 검사 실패 (HailuoASRCheckError)¶

원인¶

제공된 오디오 파일의 음성과 입력한 텍스트 검증 내용이 일치하지 않습니다.

해결 방법¶

파일 및 텍스트 확인
- 업로드한 오디오(file_id)와 검증 텍스트(text_validation)가 정확히 매칭되는지 확인하세요.

💡 복제 프롬프트 오류 (HailuoClonePromptError)¶

원인¶

음성 복제(Voice Cloning)를 위한 프롬프트 오디오 또는 텍스트에 문제가 있습니다.

해결 방법¶

오디오 품질 확인
- 프롬프트 오디오가 명확한지, 배경 소음이 없는지 확인하세요.
프롬프트 텍스트 대조
- 오디오 내용과 프롬프트 텍스트가 정확히 일치하는지 확인해 주세요.

💡 매개변수 오류 (HailuoInvalidParamsError)¶

원인¶

API 요청에 포함된 설정값이나 JSON 구조가 올바르지 않습니다.

해결 방법¶

요청 파라미터 검토
- 전송하는 데이터의 필드명과 값 형식이 API 명세서와 일치하는지 확인하세요.

💡 잘못된 Voice ID (HailuoInvalidVoiceIDError)¶

원인¶

요청한 Voice ID가 존재하지 않거나 형식이 잘못되었습니다.
사용 불가능한 샘플을 참조하고 있습니다.

해결 방법¶

ID 확인
- 사용하려는 모델 또는 보이스의 ID가 정확한지 목록에서 다시 확인하세요.

💡 음성 길이 오류 (HailuoDurationError)¶

원인¶

업로드한 음성 파일의 길이가 너무 짧거나 너무 깁니다.

해결 방법¶

파일 길이 조정
- 음성 복제에 적합한 길이(권장 길이를 확인하세요)로 오디오를 편집하여 다시 시도해 주세요.

💡 Voice ID 중복 (HailuoDuplicateVoiceIDError)¶

원인¶

생성하려는 Voice ID가 이미 시스템에 존재합니다.

해결 방법¶

ID 변경
- 다른 Voice ID를 사용하여 생성을 시도해 주세요.

💡 접근 권한 없음 (HailuoAccessDeniedError)¶

원인¶

해당 Voice ID를 사용할 권한이 없습니다. (본인이 생성하지 않았거나 공유받지 못함)

해결 방법¶

소유권 확인
- 본인이 생성한 보이스인지, 혹은 공개된 보이스인지 확인하세요.

💡 요청 증가율 제한 (HailuoRateGrowthError)¶

원인¶

짧은 시간 동안 요청량이 급격하게 증가하여 시스템 보호를 위해 차단되었습니다.

해결 방법¶

요청 속도 조절
- 갑작스러운 대량 요청을 피하고, 천천히 요청 빈도를 늘려주세요.

💡 프롬프트 오디오 길이 초과 (HailuoPromptAudioTooLongError)¶

원인¶

음성 복제에 사용된 프롬프트 오디오가 허용된 길이를 초과했습니다.

해결 방법¶

오디오 자르기
- 프롬프트 오디오 파일을 8초 미만으로 편집하여 다시 업로드해 주세요.

💡 유효하지 않은 API 키 (HailuoInvalidApiKeyError)¶

원인¶

API 키 형식이 잘못되었거나 비활성화된 키입니다.

해결 방법¶

API 키 재확인
- 키가 정확한지 확인하고, 만료된 경우 재발급 받으세요.

💡 사용량 제한 초과 (HailuoUsageLimitExceededError)¶

원인¶

해당 기간(시간/일/월)에 허용된 API 호출 횟수 또는 사용량을 모두 소진했습니다.

해결 방법¶

리소스 갱신 대기
- 다음 갱신 주기(일반적으로 5시간 윈도우)까지 기다려 주세요.

hailuo-unexpected¶

💡 예상치 못한 응답 (HailuoUnexpectedResponse)¶

원인¶

서버 응답 구조가 정상적이지 않거나, 일부 데이터가 누락되었습니다.

해결 방법¶

잠시 후 다시 시도
텍스트 길이 줄이기
프로그램 최신 버전으로 업데이트

hailuo-unknown¶

💡 알 수 없는 오류 (HailuoUnknownError)¶

원인¶

예기치 못한 오류가 발생했습니다.

해결 방법¶

프로그램 재시작
설정값 초기화 후 다시 시도
문제 지속 시 개발자에게 문의