Nano Banana Pro (Gemini 3 Pro Image)

Nano Banana Pro(나노 바나나 프로)는 전문가용 결과물과 복잡한 지시를 위해 만들어진 Google의 Gemini 3 Pro Image 모델입니다. 그리기 전에 먼저 사고하므로 응답에 추론 토큰이 보고됩니다. Google의 generateContent 요청 본문에 model 필드를 더해 보내고, 반환된 작업 ID를 보관한 뒤 그 작업을 조회해 완성된 이미지를 받아오세요. 참조 이미지는 contents 안에 fileData URL로 넣습니다.

모델 ID

두 ID는 같은 파라미터를 받습니다. 현재 가격은 모델 페이지에서 확인하세요.

간단한 예제

curl https://api.seedrouter.ai/v1/images/generations \
  -H "Authorization: Bearer $SEEDROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3-pro-image",
    "contents": [{"parts": [{"text": "A ceramic teapot on a linen tablecloth, soft window light"}]}],
    "generationConfig": {
      "responseModalities": ["IMAGE"],
      "imageConfig": {"aspectRatio": "16:9", "imageSize": "2K"}
    }
  }'

엔드포인트

POST https://api.seedrouter.ai/v1/images/generations

요청 본문은 Google의 generateContent 요청에 model 하나만 추가한 형태입니다. 이 엔드포인트는 경로에 모델을 담지 않기 때문입니다. 응답에는 완성된 이미지가 아니라 작업 ID가 들어 있습니다. API 키는 서버 측 코드에만 두세요. /v1beta/models/...:generateContent를 직접 호출하는 방식은 지원되지 않으므로 이 엔드포인트를 사용하세요.

파라미터

안전 카테고리: HARM_CATEGORY_HARASSMENT, HARM_CATEGORY_HATE_SPEECH, HARM_CATEGORY_SEXUALLY_EXPLICIT, HARM_CATEGORY_DANGEROUS_CONTENT. 임계값: BLOCK_NONE, BLOCK_ONLY_HIGH, BLOCK_MEDIUM_AND_ABOVE, BLOCK_LOW_AND_ABOVE, OFF.

알 수 없는 필드는 거부됩니다. 아직 제공되지 않는 기능: Google Search grounding(tools)과 캐시된 콘텐츠. thinkingLevel은 이 모델에 대해 문서화되어 있지 않습니다. inlineData는 받지 않으므로 미디어는 fileData URL로 전달하세요. responseFormat.image.delivery는 INLINE만 받으며, 완성된 이미지는 항상 호스팅된 URL로 반환됩니다.

출력 크기

다른 가로세로 비율도 토큰 수는 같습니다. 예를 들어 1K에서 16:9는 1376×768입니다.

모드

별도의 모드 파라미터나 편집 전용 엔드포인트는 없습니다.

대화를 이어가려면 이전 작업의 output.parts로 model 턴을 순서대로 다시 구성하세요. 텍스트 파트는 {"text": ..., "thoughtSignature": ...}, 이미지 파트는 {"fileData": {"mimeType": "image/<output_format>", "fileUri": <data[image].url>}, "thoughtSignature": ...}가 됩니다. 각 thoughtSignature는 반환된 그대로 유지하세요. 이는 저희가 대신 저장해 둔 서명의 URL이며(4K 이미지의 서명은 수 MB에 달합니다), 요청이 모델에 도달하기 전에 원래 서명으로 복원합니다. 본인의 작업 결과에서 나온 서명만 허용됩니다.

참조 이미지로 편집하기

curl https://api.seedrouter.ai/v1/images/generations \
  -H "Authorization: Bearer $SEEDROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3-pro-image",
    "contents": [{
      "role": "user",
      "parts": [
        {"text": "Turn this photo into a watercolor painting. Keep the composition."},
        {"fileData": {"mimeType": "image/jpeg", "fileUri": "https://example.com/photo.jpg"}}
      ]
    }]
  }'

예시 URL은 접근 가능한 본인의 이미지로 바꾸세요.

미디어 입력

이 API는 URL 참조만 받습니다. Base64 inlineData, data: URL, multipart 업로드는 받지 않습니다. Playground는 선택한 파일을 스토리지에 업로드한 뒤 그 URL을 제출합니다.

참조 이미지는 PNG, JPEG, WebP, HEIC, HEIF 파일을 가리키는 공개 HTTP(S) URL이어야 하며, 파일당 50 MB 미만, 합계 100 MB 미만이어야 합니다. mimeType은 파일과 일치해야 합니다. URL은 처리 중에 가져오며, 접근할 수 없는 이미지가 있으면 작업이 실패하고 실패한 작업은 과금되지 않습니다.

과금에 영향을 주는 요소

현재 요금은 모델 요금 섹션에서 확인하세요. gemini-3-pro-image는 크기나 프롬프트와 상관없이 전달된 이미지 1장마다 고정 가격을 청구합니다. gemini-3-pro-image-official은 사용량으로 과금합니다. 입력 토큰(텍스트와 참조 이미지), 텍스트 및 사고 출력 토큰, 이미지 출력 토큰에 각각 다른 요금이 적용됩니다. 가장 큰 요인은 이미지 크기이며, 위 표를 참고하세요.

최종 청구액은 계정의 사용 내역에서 확인하세요. 실패한 작업은 과금되지 않습니다.

출력 스키마

제출하면 작업 참조가 반환됩니다.

{
  "id": "task_...",
  "model": "gemini-3-pro-image",
  "status": "processing",
  "created_at": 1790310979
}

작업 폴링

curl https://api.seedrouter.ai/v1/tasks/YOUR_TASK_ID \
  -H "Authorization: Bearer $SEEDROUTER_API_KEY"

status가 completed 또는 failed가 될 때까지 몇 초 간격으로 폴링하세요. 폴링 중 네트워크 타임아웃이 났다고 해서 생성이 실패한 것은 아닙니다. 작업 ID를 보관하고 다시 확인을 이어가세요. 진행 상황을 확인하려고 작업을 새로 만들지 마세요.

전체 폴링 예제

위의 Python 제출 예제 다음에 실행하세요.

import time

deadline = time.monotonic() + 600
while time.monotonic() < deadline:
    result = requests.get(
        f"https://api.seedrouter.ai/v1/tasks/{task_id}",
        headers={"Authorization": f"Bearer {os.environ['SEEDROUTER_API_KEY']}"},
        timeout=30,
    )
    result.raise_for_status()
    task = result.json()
    if task["status"] == "completed":
        for image in task["output"]["data"]:
            print(image["url"])
        break
    if task["status"] == "failed":
        raise RuntimeError(task["error"]["message"])
    time.sleep(3)
else:
    raise TimeoutError(f"Still waiting. Resume polling task {task_id}.")

완료된 작업

{
  "id": "task_...",
  "model": "gemini-3-pro-image",
  "status": "completed",
  "created_at": 1790310979,
  "finished_at": 1790311001,
  "output": {
    "created": 1790310999,
    "data": [{"url": "https://static.seedrouter.ai/media/tasks/task_example/0.jpg"}],
    "output_format": "jpeg",
    "usage": {
      "input_tokens": 27,
      "output_tokens": 1366,
      "total_tokens": 1393,
      "output_tokens_details": {"image_tokens": 1120, "text_tokens": 95, "reasoning_tokens": 151}
    }
  }
}

스트리밍(streamGenerateContent)은 지원되지 않으며, 결과는 작업을 통해 전달됩니다.

오류

작업이 생성되기 전에 거부된 요청은 error 객체와 함께 HTTP 오류를 반환합니다. 접수된 뒤 실패한 작업은 조회 시 HTTP 200과 함께 status: "failed"와 error 객체를 반환합니다. 모델의 안전 필터에 막힌 이미지는 content_policy_violation으로, 이미지가 없는 응답은 no_output으로 실패합니다.

오류 코드, HTTP 상태, 재시도 가이드는 공통 오류 목록을 참고하세요.

{
  "id": "task_...",
  "status": "failed",
  "error": {
    "code": 60001,
    "message": "The request was rejected by the content policy. Please revise the prompt or input images."
  }
}

제출 자체가 타임아웃되면 다시 제출하기 전에 작업 내역부터 확인하세요. 첫 요청이 이미 접수되었을 수 있습니다.

팁

• 피사체, 배경, 조명, 스타일을 완전한 문장으로 설명하세요.
• 편집할 때는 무엇을 바꾸고 무엇을 그대로 둘지 명시하세요.
• 2K는 1K와 이미지 토큰이 같습니다. 인쇄용 크기의 결과물에는 4K를 사용하세요.
• 영구 보관이 필요하면 반환된 이미지를 자체 스토리지에 저장하세요.

관련 자료

• Nano Banana Pro Playground 및 요금
• OpenAPI 다운로드
• 복사 가능한 Markdown