튜토리얼

hiapi "모델 사용 불가" / "모델을 찾을 수 없음" 오류: 원인과 해결 방법

Jun 26, 2026

POST https://api.hiapi.ai/v1/tasks가 모델 사용 불가 또는 유효하지 않은 요청으로 인해 요청을 거부하면 작업이 생성되지 않습니다. 재시도하기 전에 현재 모델 문서와 대조하여 정확한 모델 이름과 요청 필드를 확인하세요.

일반적인 원인

모델 이름이 오래되었거나 불완전합니다.HiAPI의 모델 이름이 모두 같은 형식을 따르지는 않습니다. 일부는 순수 이름이고, 다른 일부는 모달리티 경로를 포함합니다. GPT Image 2의 텍스트-이미지 요청은 gpt-image-2/text-to-image를 사용합니다.
오타, 대소문자 차이 또는 숨은 공백이 이름을 바꿉니다.모델 이름은 기억에 의존하지 말고 현재 문서에서 복사하고, 환경 변수에서 불러온 값의 공백을 제거하세요.
모델 또는 라우트가 비활성화되었거나 이름이 변경되었습니다.오래된 문서나 저장된 스니펫의 이름은 더 이상 사용할 수 없을 수 있습니다. 현재 모델 페이지와 변경 로그를 기준으로 하세요.
요청이 라우트 형식을 혼용했습니다.모델이 여러 라우트를 제공할 때는 문서에 설명된 최상위 route 필드나 지원되는 @route 형식을 사용하되, 서로 충돌하는 값을 보내지 마세요.
라우팅 전에 인증이 실패했습니다.401은 API 키가 없거나 유효하지 않음을 의미합니다. 403은 키에 권한이 없음을 의미합니다. 이러한 경우는 모델 필드와 별도로 처리하세요.

해결 단계

현재 GPT Image 2 문서 또는 관련 모델 페이지를 열고 정확한 모델 이름을 복사합니다.
문서 이름의 일부인 모달리티 접미사를 유지합니다. GPT Image 2의 텍스트-이미지에는 gpt-image-2/text-to-image를 사용하세요.
input의 각 필드를 해당 모델의 매개변수 표와 비교합니다. 모델 이름이 유효하더라도 입력 필드가 지원되지 않으면 400 INVALID_REQUEST가 반환될 수 있습니다.
호출 지점에서 공백을 제거합니다. Python에서는 model = os.environ["MODEL"].strip()을 사용하고, Node.js에서는 model.trim()을 사용하세요.
모델에 여러 라우트가 있으면 문서에 설명된 최상위 route 값을 전달하고 해당 라우트에 맞는 매개변수 구조를 사용하세요.
전체 HTTP 상태 코드와 응답 본문을 기록합니다. 모델 검증 오류에서 키 문제를 추론하지 말고, 401/403에서 모델 문제를 추론하지 마세요.

최소 요청으로 검증하기

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2/text-to-image",
    "input": {
      "prompt": "나무 테이블 위의 작은 세라믹 머그컵, 부드러운 창문 빛",
      "aspect_ratio": "1:1",
      "resolution": "1K"
    }
  }'

HTTP 200이 반환되고 data.taskId가 포함되어 있으면 작업이 수락된 것입니다. data.status가 success 또는 fail이 될 때까지 GET /v1/tasks/:id를 폴링하거나 프로덕션 환경용 콜백을 구성하세요. 400이 반환되면 검증 메시지를 읽고 모델 페이지를 다시 확인하세요. 401 또는 403이 반환되면 키 또는 해당 권한을 수정하세요.

자주 묻는 질문

모든 모델 이름에서 /text-to-image를 제거해야 하나요? 아니요. 모델 명명은 시리즈마다 다릅니다. 현재 모델 문서에서 고정 값을 복사하세요. GPT Image 2의 텍스트-이미지에서 /text-to-image는 모델 이름의 일부입니다.

모델 오류가 내 키가 잘못되었음을 의미하나요? 반드시 그렇지는 않습니다. 요청 검증과 인증은 별개입니다. 401은 키가 없거나 유효하지 않음을 의미하고, 403은 키에 권한이 없음을 의미합니다. 400은 요청 구조, 모델 이름, 라우트 또는 입력 필드를 가리킵니다.

클라이언트에서 모든 모델 이름을 정규화할 수 있나요? 자체 정규화 규칙을 만들지 마세요. 현재 모델 문서에 공개된 정확한 이름을 저장하고 전송하세요.