HiAPI 400 Bad Request: 작업 API의 파라미터 오류를 수정하는 방법

통합 비동기 작업 인터페이스가 400 Bad Request를 반환한다는 것은 요청이 HiAPI에 도달했지만 어떤 모델도 실행되기 전에 거부되었다는 뜻입니다. JSON 자체나 input 객체가 해당 모델의 schema를 충족하지 않기 때문입니다. 응답은 다음과 같습니다:

{
  "code": 400,
  "data": null,
  "error_code": "INVALID_REQUEST",
  "message": "invalid input: aspect_ratio: value must be one of '1:1', '4:3', '3:4', '16:9', '9:16'"
}

가장 유용한 필드는 message입니다. 구체적으로 어느 파라미터가 왜 잘못되었는지 알려줍니다. 400은 요청 자체의 문제이며 인증이나 잔액 문제가 아닙니다. 그리고 작업이 아예 생성되지 않았으므로 거부된 400에는 요금이 청구되지 않습니다.

어떤 경우에 400이 발생하는가 (발생 확률 높은 순)

아래 각 경우 모두 HTTP 400을 반환합니다. schema 문제의 error_code는 INVALID_REQUEST이고, 모델 id가 존재하지 않을 때는 MODEL_UNAVAILABLE입니다. 아래는 모두 HiAPI가 실제로 반환하는 오류 문구입니다:

발생 원인	실제로 보게 되는 message	error_code
열거값이 유효하지 않음	invalid input: aspect_ratio: value must be one of '1:1', '4:3', '3:4', '16:9', '9:16'	INVALID_REQUEST
값 타입 오류	invalid input: prompt: got number, want string	INVALID_REQUEST
필수 필드 누락 / 필드명 오타	invalid input: prompt: missing required field "prompt"; <root>: additional properties 'promptt' not allowed	INVALID_REQUEST
JSON 형식 오류	invalid json body: unexpected end of JSON input	INVALID_REQUEST
모델 id가 존재하지 않음 / 오타	model not available via /v1/tasks	MODEL_UNAVAILABLE

schema 검증기가 실제로 잡아내는 것에 주목하세요: 열거값(aspect_ratio, resolution 등의 값이 해당 모델이 허용하는 집합을 벗어남), 타입(문자열을 보내야 할 곳에 숫자를 보냈거나, 배열을 보내야 할 곳에 문자열만 보냄), 필드명(promptt 같은 오타, 또는 이름이 바뀌거나 제거된 필드 — 검증기는 '누락된 필수 필드'와 '추가된 알 수 없는 필드'를 동시에 보고합니다), 그리고 모델 id 자체(값이 작업 인터페이스의 온라인 모델이 아님)입니다.

응답 본문에서 진단하는 방법

1. 먼저 HTTP 상태 코드를 확인하세요. 400 = 요청에 문제가 있음. 401, 402, 403, 429 또는 504가 보인다면 다른 종류의 문제입니다 — 문서 끝의 '관련 글'을 참고하세요. 상태 코드가 실제로 401인데 파라미터를 고쳐 400인 것처럼 처리하지 마세요.
2. 다음으로 error_code를 보세요. INVALID_REQUEST는 요청 본문 / input이 schema 검증을 통과하지 못했음을, MODEL_UNAVAILABLE은 model 값이 /v1/tasks에서 확인되지 않음을 뜻합니다.
3. message를 글자 그대로 읽으세요. 이는 필드 단위입니다: invalid input: <필드>: <이유>. invalid input: 뒤에 나오는 단어가 바로 고쳐야 할 파라미터입니다. value must be one of ...라고 적혀 있다면 허용되는 값이 그 자리에 출력되어 있으니, 그중 하나를 그대로 복사하면 됩니다.
4. additional properties '<x>' not allowed가 나오면, 해당 모델 schema에 정의되지 않은 필드를 보낸 것입니다 — 보통 오타이거나 다른 모델에서 복사해 온 파라미터입니다. 삭제하거나 올바른 필드명으로 바꾸세요.

이 필드 단위 오류는 따로 언급할 가치가 있습니다. 많은 이미지·비디오 API는 잘못된 요청에 대해 아무런 세부 정보 없이 400 Bad Request만 반환합니다. HiAPI는 여러분의 input을 각 모델의 schema와 대조해 검증하고, 어느 필드가 무엇을 기대하는지 알려줍니다 — 덕분에 추측하지 않고 한 번에 한 필드씩 정확히 고칠 수 있습니다.

수정 단계 (checklist)

1. 먼저 JSON 형식을 고치세요. message가 invalid json body로 시작한다면 payload 자체가 유효한 JSON이 아닙니다 — 닫히지 않은 중괄호, 대괄호, 불필요한 쉼표, 이스케이프되지 않은 따옴표가 없는지 확인하세요. 전송 전에 jq나 python -m json.tool로 문자열을 한 번 검증하세요.
2. model이 순수한 온라인 id인지 확인하세요. z-image, gpt-image-2 같은 순수 id를 사용하세요 — 임의의 라우팅 접미사를 만들지 마세요. 모델 목록이나 모델 페이지와 대조해 확인하세요. id가 존재하지 않으면 MODEL_UNAVAILABLE이 반환됩니다.
3. 해당 모델의 schema에 맞추세요. 각 모델은 자체 input 필드를 선언합니다. 생성 파라미터를 최상위가 아니라 input 안에 넣으세요. schema에 나열되지 않은 필드를 삭제하세요(additional properties ... not allowed의 원인이 바로 이것입니다).
4. 열거값은 그대로 복사하세요. message가 value must be one of ...를 출력하면 그중 하나의 값을 글자 그대로 복사하세요(예: "aspect_ratio": "1:1").
5. 타입을 올바르게 보내세요. prompt는 문자열입니다. 참조 이미지는 배열 필드에 넣으세요(예: image_urls). 숫자 필드는 숫자여야 하며 따옴표로 감싼 문자열이어서는 안 됩니다. 모델마다 필드명이 다를 수 있습니다(참조 이미지는 input_urls / image_urls / image_input, 가로세로 비율은 aspect_ratio / ratio / size, 길이는 문자열일 수도 정수일 수도 있음). 모두 해당 모델 schema를 기준으로 하세요.
6. 다시 보내고 다시 읽으세요. 여전히 400이라면 message가 이번에는 다음 필드를 가리킬 것입니다. 호출이 taskId와 함께 200을 반환할 때까지 한 번에 하나씩 고치세요.

최소 사용 가능 요청

형식이 올바른 최소 텍스트-이미지 호출입니다. 이것이 data.taskId와 함께 200을 반환한다면 key, 접속 주소, 요청 구조에 문제가 없다는 뜻입니다 — 이전에 겪은 400은 연결 문제가 아니라 파라미터 문제였습니다:

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "z-image",
    "input": {
      "prompt": "a red ceramic mug on a wooden table, soft daylight",
      "aspect_ratio": "1:1"
    }
  }'

제출에 성공하면 data에 taskId가 포함됩니다. 그런 다음 GET https://api.hiapi.ai/v1/tasks/<taskId>를 폴링하여 data.status가 success(또는 fail)로 바뀔 때까지 기다린 뒤 data.output에서 결과를 읽으세요. 디버깅 중에는 요청을 최소한으로 유지하세요: 선택 필드를 하나씩 다시 추가하면 새로 나타나는 400이 방금 추가한 필드를 정확히 가리킵니다. 전체 필드 목록은 모델 페이지에서, 작업 생명주기는 API 문서에서 확인하세요.

관련 글

• API Key 무효 오류: 원인, 수정, 연동 checklist —— 상태 코드가 400이 아니라 401일 때 읽어 보세요.
• HiAPI의 'Model Not Found' 수정하기 —— MODEL_UNAVAILABLE과 모델 id 문제를 다룹니다.
• HiAPI 속도 제한(429) 오류를 수정하는 방법 —— 요청 검증이 아닌 스로틀링을 다룹니다.
• HiAPI 실패한 요청에 요금이 부과되나요? —— 400과 '작업이 실행된 후 실패'의 과금 차이를 다룹니다.
• 요금 페이지와 대시보드: 크레딧 확인, key 발급.

FAQ

error_code: INVALID_REQUEST는 무슨 뜻인가요? 요청 본문이나 input 객체가 schema 검증을 통과하지 못했다는 뜻입니다. message 필드가 어느 파라미터가 잘못되었는지 지목합니다. 인증 문제(그건 401)도, 잔액 문제(그건 402)도 아닙니다.

additional properties '<필드>' not allowed는 왜 나타나나요? 해당 모델 schema에 정의되지 않은 필드를 보냈기 때문입니다 — 보통 오타(prompt를 promptt로 씀), 다른 모델에 속한 필드, 또는 파라미터를 input이 아닌 최상위에 둔 경우입니다. 삭제하거나 이름을 바꾸면 됩니다.

400 Bad Request에 크레딧이 차감되나요? 아니요. 400은 검증 단계에서 거부되어 작업이 아예 생성되지 않았으므로 과금될 수 없습니다. 실제로 접수되어 실행된 작업만 요금이 부과됩니다.

JSON이 틀림없다고 확신하는데 여전히 400이라면 어떻게 하나요? message를 글자 그대로 읽으세요. 필드 단위이므로 정확한 파라미터와 기대하는 값 또는 타입을 알려줍니다. value must be one of ...라고 적혀 있다면 값이 허용된 열거형에 속하지 않는다는 뜻이니 허용된 값 하나를 그대로 복사하세요. 타입을 지적한다면(got number, want string) 타입을 올바르게 고치세요.

모델 id를 잘못 쓰면 같은 오류인가요? 여전히 HTTP 400이지만 error_code는 MODEL_UNAVAILABLE이고 문구는 model not available via /v1/tasks입니다. 순수한, 현재 온라인인 모델 id를 사용하고 임의의 라우팅 접미사를 붙이지 마세요.

한 모델이 어떤 필드를 허용하는지 어떻게 확인하나요? 각 모델 페이지에 해당 input schema와 예시 요청이 나열되어 있습니다. 위의 최소 사용 가능 요청에서 시작해 모델 페이지 문서에 따라 필드를 하나씩 추가하세요.