사용 가이드

HiAPI OpenAI 호환 인터페이스의 "Model Not Found"(model_not_found) 오류 수정

Oct 22, 2026

문제 현상

HiAPI의 OpenAI 호환 인터페이스(POST /v1/chat/completions)를 호출할 때 전달한 model id를 HiAPI가 인식하지 못하거나 라우팅할 수 없으면, 인터페이스는 HTTP 400을 반환하며 응답 본문에 model_not_found 오류 코드가 담깁니다. 다음과 같습니다:

{
  "error": {
    "message": "The requested model does not exist or is not available. Check the exact model ID with GET /v1/models and try again. If the issue persists, contact support with request ID: ...",
    "type": "hiapi_error",
    "code": "model_not_found",
    "request_id": "..."
  }
}

이것은 "키에 문제가 생긴 것"과는 다른 문제입니다. API key 자체가 유효하지 않거나 만료된 경우 HiAPI는 HTTP 401 + permission_denied를 반환하며, model_not_found가 아닙니다:

{
  "error": {
    "code": "permission_denied",
    "message": "This API key is invalid. Check that it is correct or use another API key and try again. If the issue persists, contact support with request ID: ...",
    "type": "hiapi_error",
    "request_id": "..."
  }
}

permission_denied가 보이면 먼저 key를 고치고, model id는 신경 쓰지 마세요. 아래에서는 model_not_found만 다룹니다.

흔한 원인

실제 발생 확률이 높은 순서대로 정렬:

model id의 철자 / 대소문자가 틀렸거나, 웹페이지 주소창의 slug를 그대로 복사한 경우. model id는 대소문자를 구분하며, 점, 하이픈, 슬래시가 자주 포함됩니다(예: seedream-5.0-lite이지 seedream-5-0-lite가 아님). 브라우저 주소창에서 모델 페이지의 slug를 복사해 id로 사용하는 것이 이 오류의 가장 흔한 원인입니다——모델 페이지 URL의 짧은 slug가 실제 API id와 반드시 같지는 않습니다.
이 모델이 대화 모델이 아니라 다른 인터페이스를 사용하는 경우. HiAPI의 대부분 이미지 / 비디오 / 오디오 모델은 비동기 작업 인터페이스 POST /v1/tasks만 지원하며, gpt-5.6 / gpt-6 같은 추론 모델은 POST /v1/responses만 지원합니다. 이것들을 /v1/chat/completions로 보내면 인터페이스는 invalid_request(HTTP 400)로 거부합니다:
```
{
  "error": {
    "message": "The request is incomplete or incorrectly formatted. Please check it and try again...",
    "type": "hiapi_error",
    "param": "",
    "code": "invalid_request",
    "request_id": "..."
  }
}
```
GET /v1/models가 반환하는 각 모델에는 supported_endpoint_types 필드가 있으며, 이것이 바로 "이 모델이 어떤 인터페이스를 써야 하는지"의 유일한 근거입니다(아래 참조).
모델이 이미 서비스 종료되었거나 이름이 변경된 경우. id 철자는 완전히 맞지만 현재 /v1/models 목록에 없습니다——오래된 노트나 캐시에 있는 예전 id는 만료되었을 수 있습니다.
key / 권한 문제를 model 문제로 오판한 경우. 계정 키가 유효하지 않으면 permission_denied(401)가 보고되며, model_not_found(400)가 아닙니다. 먼저 오류 코드로 어떤 유형인지 구분한 후 원인에 맞게 수정하세요.

수정 단계

먼저 실시간 목록과 정확한 id를 확인: key를 사용해 GET https://api.hiapi.ai/v1/models를 호출하세요. 이것은 실시간 카탈로그이며, 오류 메시지가 확인하라고 안내하는 바로 그곳입니다——코드나 노트에 하드코딩된 어떤 id보다 권위가 높습니다.
supported_endpoint_types를 보고 인터페이스 판단. 각 모델 항목은 다음과 같습니다:
```
{ "id": "gpt-image-2/text-to-image", "object": "model", "owned_by": "custom", "supported_endpoint_types": ["task"] }
```
- task → 비동기 POST /v1/tasks를 사용하며, chat/completions는 사용할 수 없습니다;
- openai → POST /v1/chat/completions를 사용합니다(이 글에서 다루는 경로);
- openai-response → POST /v1/responses를 사용합니다.
목록에 있는 id를 한 글자도 다르지 않게 사용해 요청을 다시 보내세요. 멀티태스크 모델은 목록에서 작업 유형 접미사(예: /text-to-image, /image-to-video)가 붙습니다. 목록에 적힌 그 전체 id를 사용하고, 모델 페이지 URL의 맨 slug만 사용하지 마세요.
인터페이스를 올바르게 선택: task 유형이면 /v1/tasks로, openai-response 유형이면 /v1/responses로 변경하세요. 인터페이스를 바꾸는 것이 chat/completions에서 id를 반복 시험하는 것보다 한 번에 해결됩니다.
오류 코드가 실제로 permission_denied(401)라면 문제는 model id가 아니라 key에 있습니다——별도로 API key를 재설정하거나 교체하세요.

최소 검증 예시

이 오류를排查할 때 첫 번째 명령은 항상 GET /v1/models입니다——비용이 없고 부작용도 없으며, 한 번에 두 가지를 검증합니다: key가 통하는지, 이 id가 실제로 존재하는지, 어떤 인터페이스를 써야 하는지.

curl -s https://api.hiapi.ai/v1/models \
  -H "Authorization: Bearer $HIAPI_API_KEY"

200 + 모델 목록 반환 → key 정상, 다음으로 목록에서 id와 그 supported_endpoint_types를 확인;
401 + permission_denied 반환 → key 문제이므로 먼저 key를 수정.

어떤 모델이 task 유형임을 확인한 후 올바른 호출 방식은 통합 작업 인터페이스입니다(model은 맨 id를 사용하면 되며, 작업 유형 접미사 없이도 라우팅 가능):

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "input": { "prompt": "a red apple on a white table" }
  }'

/v1/tasks는 요청을 받는 즉시 실제로 과금 작업을 생성하고 taskId를 반환하므로, 이것은 "수정 후 정식 호출"이지 연결성을 가볍게 시험하는 용도가 아닙니다——순수 연결성 확인은 위의 GET /v1/models를 사용하세요. id를 사용할 수 없으면 /v1/tasks의 오류는 다른 평면 구조입니다(chat/completions와 다름):

{ "code": 400, "data": null, "error_code": "MODEL_UNAVAILABLE", "message": "model not available via /v1/tasks" }

FAQ

Q: 모델 페이지 URL에서 id를 그대로 복사했는데 왜 사용할 수 없나요? A: 모델 페이지 URL에는 보통 짧은 slug가 있으며, 실제 API id(특히 멀티태스크 모델)는 작업 유형 접미사가 붙습니다. 예: gpt-image-2/text-to-image. GET /v1/models가 반환하는 id를 기준으로 하고, 브라우저 주소창을 기준으로 하지 마세요.

Q: GET /v1/models/{id}가 존재하지 않는 id에 대해 HTTP 200을 반환하는데, 버그인가요? A: 아닙니다. 단일 모델 조회 인터페이스는 id가 존재하지 않아도 200을 반환하지만, 응답 본문은 404/400 상태 코드가 아니라 invalid_request_error / model_not_found 구조입니다. 이 인터페이스는 HTTP 상태 코드만 보지 말고 body를 보세요. 목록 인터페이스 GET /v1/models와 /v1/chat/completions의 동작은 위에 설명한 바와 같습니다.

Q: OpenAI SDK를 HiAPI로 지정했는데 model_not_found가 발생합니다. OpenAI 쪽 문제인가요? A: 아닙니다. OpenAI 호환 SDK의 base_url을 HiAPI로 지정하면 모델 해석은 전적으로 HiAPI가 담당합니다. model_not_found는 HiAPI가 전달한 id를 등록된 모델과 매칭하지 못했다는 뜻이므로, 위 단계에 따라 수정하면 됩니다.

Q: 어떤 모델이 어떤 인터페이스를 써야 하는지 빠르게 판단하는 방법은? A: GET /v1/models에서 해당 모델의 supported_endpoint_types를 보세요: task가 포함되면 POST /v1/tasks, openai가 포함되면 POST /v1/chat/completions, openai-response가 포함되면 POST /v1/responses를 사용합니다.

Q: /v1/tasks와 /v1/chat/completions의 오류 코드는 같은가요? A: 다릅니다. /v1/chat/completions는 소문자 code(예: model_not_found, invalid_request)를 {"error": {...}} 안에 담습니다; /v1/tasks는 대문자 error_code(예: MODEL_UNAVAILABLE)를 평면적인 {"code","message","data","error_code"} 안에 넣습니다. 두 인터페이스의 오류 처리를 작성할 때 하나의 세트가 범용될 것이라고 가정하지 마세요.