Nano Banana Pro 생성 전 500 오류

Higgsfield API error (HTTP 500). Internal Server Error

Nano Banana Pro는 즉시 이 메시지를 반환했습니다. 작업은 만들어지지 않았고 이미지도 생성되지 않았습니다.

실패한 명령은 nano_banana_2에 참조 이미지, --aspect_ratio auto, --resolution 4k를 사용했습니다. 로컬 경로를 넣든 업로드 ID를 넣든 같은 오류가 발생했습니다.

가장 먼저 참조 파일을 의심했습니다. 하지만 그것은 문제의 일부일 뿐이었습니다.

서로 다른 2가지 매개변수 문제가 똑같이 불친절한 서버 응답을 일으키고 있었습니다.

명세에서는 허용된 auto가 실제로는 작동하지 않았습니다

모델 스키마에는 aspect_ratio에 사용할 수 있는 값으로 auto가 명시돼 있었습니다. 그런데 이 값을 전달하면 HTTP 500이 발생했습니다.

허용 목록에 있는 값은 보통 수동으로 고른 화면비보다 안전해 보이기 때문에 이 점이 중요합니다. 저는 서버가 원본 이미지를 확인해 비율을 결정할 것이라고 예상했습니다. 하지만 요청은 작업이 만들어지기도 전에 실패했습니다.

두 번째 문제는 --image 플래그였습니다. 이 플래그도 해당 모델에서 500 오류를 일으켰습니다.

Nano Banana Pro는 input_images로 참조 이미지를 받아야 했습니다. 업로드 ID를 배열에 넣는 것만으로는 부족했습니다. 배열 안에 다음과 같은 구조의 객체가 필요했습니다.

[
  {
    "id": "<upload-id>",
    "type": "media_input"
  }
]

문자열 배열은 Input should be a valid object(유효한 객체여야 합니다)라는 오류로 실패했습니다. ID만 있고 type이 없는 객체는 Field required(필수 필드입니다)라는 오류로 실패했습니다.

이 유효성 검사 메시지들은 처음의 500 오류보다 도움이 됐습니다. 서버에 필요한 것이 단순히 업로드된 이미지가 아니라 정해진 구조를 갖춘 미디어 입력이라는 점을 보여줬습니다.

4K를 다시 시도하기 전에 요청을 최소화했습니다

전체 업스케일 명령을 계속 다시 보내지 않았습니다. 1K로 최소 테스트 요청을 만들었습니다.

먼저 원본을 업로드했습니다.

higgsfield upload create <path> --json

그러면 input_images에 필요한 업로드 ID가 반환됩니다.

다음으로 원본 이미지의 크기를 확인했습니다. PIL을 사용했습니다.

python -c "from PIL import Image; print(Image.open(p).size)"

크기를 확인한 뒤 모델이 지원하는 명시적 화면비 중 가장 가까운 값을 골랐습니다. 이번에 사용한 원본 2개는 각각 2:3과 4:3에 해당했습니다.

auto는 전달하지 않았습니다.

그다음 미디어 객체를 JSON 파일에 넣고 다음 방식으로 전달했습니다.

--input_images @file.json

실제 출력에 들어가기 전에 요청 구조를 시험할 수 있도록 1K를 사용했습니다. 그 요청으로 작업이 생성되고 완료된 것을 확인한 뒤, 4K 실행에도 같은 구조를 사용했습니다.

4K 업스케일 2건 모두 완료됐습니다. 2026년 6월 11일에 검증한 결과입니다.

최소 테스트가 중요했던 이유

처음의 업스케일은 --image와 auto 조합으로 3번 실패했습니다. 같은 명령을 반복해서는 이미지, 화면비, 해상도, 요청 구조 중 무엇이 원인인지 알 수 없었습니다.

작은 테스트로 이 변수들을 분리했습니다.

유효성 검사 오류를 통해 필요한 객체 구조를 확인했습니다. 화면비를 명시해 작동하지 않는 auto 값을 제거했습니다. 두 변경 사항이 모두 1K에서 작동한 뒤에야 원래 목표였던 4K 출력으로 돌아갔습니다.

추가 비용은 1K 테스트 1건이었습니다.

8K를 시험할 이유는 없었습니다. 이 플랫폼에서 Nano Banana Pro와 Bytedance Image Upscale은 모두 최대 4K까지만 지원합니다.

실패한 요청이 작업으로 만들어졌는지 확인합니다

즉시 반환되는 HTTP 500은 로컬 유효성 검사가 아니라 API에서 오는 오류이므로 비용이 발생했을 것처럼 보일 수 있습니다. 이번에는 작업 생성 전에 실패했고 크레딧도 사용하지 않았습니다.

그렇더라도 저는 추정하지 않고 확인합니다.

500 오류가 즉시 반환되면 다음 명령으로 확인합니다.

higgsfield generate list

작업이 만들어지지 않았다면 생성 대기열에 들어가기 전에 요청이 실패했다는 것을 알 수 있습니다. 이렇게 하면 잘못된 형식의 요청과 생성 과정의 나중 단계에서 실패한 결과를 구분할 수 있습니다.

디버깅 방식도 달라집니다. 작업 생성 전의 500 오류라면 매개변수를 살펴봐야 합니다. 같은 인수로 최대 해상도 생성을 다시 시도할 일이 아닙니다.

지금 제가 지키는 원칙

nano_banana_2에서는 --aspect_ratio auto를 사용하지 않습니다. 원본 크기를 확인하고 지원되는 명시적 화면비 중 가장 가까운 값을 선택합니다.

참조 이미지도 객체 배열 형태로 input_images에 전달합니다. 각 객체에는 업로드 ID와 "type": "media_input"을 모두 넣습니다.

비용이 발생하는 배치를 실행하기 전에 최소 1K 요청을 1번 보냅니다. 문서에 명시된 가장 작은 테스트로 미디어 입력 구조, 화면비, 작업 생성 경로를 확인합니다.

지금 Nano Banana Pro가 즉시 500 오류를 반환한다면 먼저 작업 목록을 확인해 보세요. 그런 다음 auto를 바꾸고 --image 사용을 중단한 뒤, 구조를 갖춘 input_images 요청 1건을 1K로 시험해 보세요.

---

이 글의 해결책은 모두 제가 먼저 실수의 대가를 치르고 얻은 것입니다. 여러분의 브랜드보다 제 영화에서 겪는 편이 낫습니다.