Gemini 이미지 생성 API 프록시는 애플리케이션과 Gemini 이미지 모델 사이에서 요청을 처리하는 API 게이트웨이입니다. 연결하려면 이미지 출력이 가능한 모델 ID, 프록시의 요청 형식, 실제 이미지의 수신 방법을 확인해야 합니다. 텍스트 클라이언트의 기본 URL을 바꾸는 것만으로 이미지 생성 지원이 확인되지는 않습니다.

OmniaKey 문서의 이미지 처리 흐름은 POST /v1/media/tasks로 작업 생성 → 상태 폴링 → 결과 다운로드입니다. 이 가이드에서는 전체 과정을 설명하고 Google 네이티브 API 및 OpenAI 호환 API와의 차이를 짚습니다.

문서 확인일: 2026년 10월 14일. Google과 OmniaKey의 공개 문서를 바탕으로 작성한 OmniaKey 연동 가이드입니다. 유료 이미지 생성이나 제공업체의 속도·품질 측정은 수행하지 않았습니다. 카탈로그에 모델이 있어도 개별 키의 권한이나 현재 사용 가능한 채널이 보장되지는 않습니다.

어떤 종류의 프록시가 필요한가요?

여기서 프록시는 모델 요청, 인증, 응답을 처리하는 애플리케이션 API 서비스입니다. 네트워크 프록시는 트래픽을 전달하지만 그 자체로 이미지 API 형식을 변환하지는 않습니다. 연결할 서비스가 공개한 명세를 기준으로 선택하세요.

API 유형	요청 형식	이미지가 반환되는 위치
Gemini GenerateContent	`/v1beta/models/MODEL:generateContent`, `contents` 및 지원되는 `generationConfig` 필드	`candidates[].content.parts[].inlineData` 등의 이미지 파트
OpenAI 호환 프록시	제공업체가 명시한 엔드포인트와 이미지 스키마	제공업체별 이미지 데이터 또는 URL
OmniaKey 이미지 작업	`/v1/media/tasks`, `model`, `type`, `operation`, `input`, `parameters`	작업 ID를 먼저 받고 `succeeded` 이후 `assets[]` 확인

현재 Google의 이미지 생성 가이드는 Interactions API 예제를 사용합니다. GenerateContent 참조 문서는 별도 명세입니다. 두 API의 입력 필드나 응답 파서를 섞거나, 프록시가 둘 다 제공한다고 가정하면 안 됩니다.

이미지 이해와 생성도 구분해야 합니다. 사진을 보고 설명하는 모델이 텍스트만 출력할 수 있습니다. 텍스트 호출 성공은 이미지 생성이나 편집의 성공을 입증하지 않습니다. OpenAI 호환이라는 설명만으로 모든 SDK 메서드를 지원한다고 볼 수도 없습니다.

구체적인 이미지 모델 ID를 선택하세요

Google 모델 안내는 다음 모델을 구분합니다.

Nano Banana 2.1: gemini-nano-banana-2.1. Google이 새로운 범용 이미지 작업의 시작점으로 권장하는 모델입니다.
Nano Banana Pro: gemini-3-pro-image. 더 까다로운 시각 작업을 평가할 수 있는 별도 모델입니다.
Nano Banana 2: gemini-3.1-flash-image. 이전 세대이며 2.1의 별칭이 아닙니다.

호출할 서비스에서 정확한 ID를 복사하고 권한, 생성·편집 지원, 크기와 과금 단위를 확인하세요. OmniaKey의 2.1 작업은 parameters.aspect_ratio, parameters.image_size를 사용하며 1K, 2K, 4K 출력 단계를 문서화합니다. Google의 imageConfig나 GPT Image의 size, quality를 그대로 대입할 수는 없습니다.

현재 게이트웨이 정보는 Nano Banana 2.1 모델 페이지에서, 모델 선택 기준은 2.1과 Pro 비교에서 확인할 수 있습니다.

OmniaKey로 이미지 생성하기

Bash, cURL, jq를 준비하고 OmniaKey 키를 로컬 OMNIAKEY_API_KEY 환경 변수에 저장하세요. 백엔드나 개발용 컴퓨터에서 실행하며, 키를 브라우저 코드에 넣지 마세요. 예제의 간단한 영어 프롬프트는 이미지 품질보다 API 흐름을 먼저 확인하기 위한 입력입니다.

1. 작업을 생성하고 저장하기

이미지 작업 하나에 고유한 Idempotency-Key를 부여합니다. 예제 값은 데모용입니다. 새 작업마다 한 번 바꾸고, 그 작업을 재시도할 때는 키와 요청 본문을 그대로 유지하세요. 전송 전에 두 항목을 애플리케이션에 저장합니다.

bash

curl --fail-with-body --silent --show-error \
  https://api.omniakey.com/v1/media/tasks \
  -H "Authorization: Bearer $OMNIAKEY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: gemini-image-demo-20261014-001" \
  -d '{
    "model": "gemini-nano-banana-2.1",
    "type": "image",
    "operation": "generate",
    "input": {"prompt": "A blue ceramic cup on a white studio table, no text"},
    "parameters": {"aspect_ratio": "1:1", "image_size": "1K"}
  }' -o task.json

cURL이 성공하고 task.json에 id가 있어야 다음 단계로 진행합니다. 새 작업은 202 Accepted를 반환하며, 같은 키와 본문을 다시 보내면 기존 작업을 200으로 반환합니다. 접수는 이미지 생성 완료를 의미하지 않습니다. 작업 수명 주기 문서(영문)에서 상세 내용을 확인하세요.

2. 저장한 ID로 상태 조회하기

아래 Bash 예제는 조회 횟수를 제한합니다. 한도에 도달해도 저장된 ID로 나중에 조회할 수 있습니다. 작업을 취소하거나 새로 만들지 않습니다.

bash

TASK_ID="$(jq -er '.id' task.json)" || exit 1
for attempt in {1..60}; do
  curl --fail-with-body --silent --show-error \
    "https://api.omniakey.com/v1/media/tasks/$TASK_ID" \
    -H "Authorization: Bearer $OMNIAKEY_API_KEY" \
    -o result.json || exit 1
  STATUS="$(jq -er '.status' result.json)" || exit 1
  case "$STATUS" in
    succeeded) break ;;
    failed|canceled) jq '.error' result.json; exit 1 ;;
    queued|processing) sleep 3 ;;
    *) exit 1 ;;
  esac
done

생성 요청이 시간 초과되어 ID를 받지 못했다면 동일한 본문과 멱등성 키로 다시 요청합니다. ID가 있다면 해당 작업을 조회하세요. 새 키를 사용하면 과금 대상 작업이 추가로 생성될 수 있습니다. 복구에는 보관 기간이 적용됩니다. 문서상 작업 기록은 생성 후 24시간 유지됩니다.

3. 성공한 결과만 다운로드하기

bash

jq -e '.status == "succeeded"' result.json >/dev/null || exit 1
ASSET_URL="$(jq -er '.assets[0].url' result.json)" || exit 1
curl --fail --location --silent --show-error \
  "$ASSET_URL" -o generated-image

자산의 mime_type을 보고 올바른 확장자를 지정한 뒤 파일이 열리는지, 크기가 맞는지 확인합니다. 서명된 URL에는 만료 시간이 있습니다. 작업과 자산이 유효한 동안 다시 조회하면 새 URL을 받을 수 있습니다. 보관할 이미지는 다운로드하세요. 서명된 링크는 영구 저장소가 아닙니다.

참조 이미지로 편집하기

operation: "edit"를 설정하고 input.image에 인라인 Base64 이미지를 넣습니다. 여러 참조 이미지를 지원하는 작업에서는 input.images를 사용합니다. 편집 지시는 input.prompt에 넣습니다. 전체 형식은 이미지 API 문서(영문)에 나와 있습니다.

작업 API는 Base64를 포함한 전체 요청 본문을 1 MiB로 제한합니다. 필요하면 참조 이미지를 압축하거나 축소하세요. Google 직접 호출의 업로드 제한을 프록시의 제한으로 간주하면 안 됩니다. 작은 참조 이미지 한 장으로 명확한 변경을 먼저 시험하고, 유지해야 할 세부 사항을 검토하세요.

프롬프트, 이미지, 모델 또는 매개변수가 달라지면 새 요청입니다. 새 멱등성 키를 사용하세요. 같은 키로 다른 본문을 보내면 409 idempotency_key_reused가 반환됩니다.

실패한 계층부터 확인하세요

증상	확인 항목	다음 조치
`401` / `403`	키, 호스트, 인증 형식, 모델 권한	인증 정보나 권한을 먼저 수정
`400` / `404`	엔드포인트, 모델 ID, 필드, 작업 소유권	명세를 확인하고 별칭을 추측하지 않기
`413`	Base64를 포함한 본문 크기	입력 이미지 축소
`409 idempotency_key_reused`	같은 키에 다른 본문을 보냈는지	복구는 원래 본문, 새 작업은 새 키 사용
`429`	할당량, 요청 속도, 동시 실행 수	오류를 읽고 부하를 낮춘 뒤 필요 시 제한된 백오프 적용
`503`	설정 문제인지 일시적인 처리 용량 문제인지	`worker_disabled`, `no_available_channel`은 설정과 채널 확인 필요
텍스트만 반환되거나 빈 출력	이미지 출력 지원, 안전성 피드백, 파서	GenerateContent의 `promptFeedback`, `finishReason`, 모든 파트 확인
폴링 시간 초과	작업이 실행 중인지	같은 ID로 재개하고 대기 종료만으로 다시 생성하지 않기

Google 문제 해결 가이드는 Google 자체 동작을 설명합니다. 프록시는 별도 계층이므로 HTTP 상태, 오류 코드, 작업 ID와 시간을 민감 정보 없이 기록하세요. 키나 비공개 참조 이미지는 로그에 남기지 않습니다. 200 JSON만으로 사용 가능한 이미지를 얻었다고 판단할 수 없습니다.

비용과 연동 결과 검증하기

Google 직접 과금과 프록시 요금은 서로 다릅니다. 대량 호출 전에 OmniaKey 현재 요금과 해당 모델의 과금 단위를 확인하세요. 텍스트 토큰 가격을 이미지 출력에 적용하거나, 개인용 Gemini 구독이 프록시 호출 비용을 충당한다고 가정하지 마세요.

비교 기준은 실제 과금 총액 ÷ 검수를 통과한 이미지 수입니다. 과금된 재시도와 생성 후 검수에서 제외한 결과도 포함합니다. 이는 계획용 공식이며 실측 벤치마크나 최저가 보장이 아닙니다.

사용량을 늘리기 전에 다음 다섯 가지를 소규모로 확인하세요.

텍스트 요청이 열리는 이미지 파일을 반환하며 형식과 크기가 맞는지 확인합니다.
참조 이미지 편집이 변경 지시를 따르면서 필요한 세부 사항을 보존하는지 확인합니다.
같은 키와 본문을 재전송했을 때 같은 작업 ID를 받는지 확인합니다.
로컬 폴링 시간 초과 후에도 같은 ID로 조회를 이어갈 수 있는지 확인합니다.
잘못된 매개변수나 사용할 수 없는 모델이 명확한 오류를 반환하는지 확인합니다.

모델 ID, 매개변수, 경과 시간, 최종 상태, 과금과 검수 결과를 기록합니다. 실제 업무 자료를 전송하기 전에는 프롬프트와 참조 이미지의 데이터 처리 조건도 확인하세요.

자주 묻는 질문

기존 SDK의 기본 URL만 바꾸면 되나요?

프록시가 해당 SDK의 엔드포인트, 필드, 이미지 응답 형식을 명시적으로 지원할 때만 가능합니다. 텍스트 호출뿐 아니라 이미지 작업을 직접 검증해야 합니다.

프록시를 사용하면 Gemini 제한이 없어지나요?

아닙니다. 공급자, 모델, 프록시와 계정의 제한이 모두 적용될 수 있습니다. 게이트웨이가 무제한 이미지 출력이나 특정 지역의 이용 가능성을 보장하지는 않습니다.

어떤 모델부터 시작해야 하나요?

현재 카탈로그를 확인한 후 지원되는 이미지 모델을 작은 작업으로 평가하세요. 모델 변경 사항은 Nano Banana 2.1 가이드에서 다룹니다. 이 글은 연결과 검증에 집중합니다.

출처와 다음 단계

주요 자료는 Google의 이미지 가이드, GenerateContent 참조, 문제 해결 문서와 본문의 OmniaKey 문서입니다. 해당 문서 링크는 영문입니다. 명세는 2026년 10월 14일에 확인했으며, 예제 실행 전 현재 모델 권한을 확인하세요.

OmniaKey API 키 만들기 이미지 API 문서 보기(영문)

Gemini 이미지 생성 API 프록시 연결 가이드

GEMINI 이미지 API

어떤 종류의 프록시가 필요한가요?

구체적인 이미지 모델 ID를 선택하세요

OmniaKey로 이미지 생성하기

1. 작업을 생성하고 저장하기

2. 저장한 ID로 상태 조회하기

3. 성공한 결과만 다운로드하기

참조 이미지로 편집하기

실패한 계층부터 확인하세요

비용과 연동 결과 검증하기

자주 묻는 질문

기존 SDK의 기본 URL만 바꾸면 되나요?

프록시를 사용하면 Gemini 제한이 없어지나요?

어떤 모델부터 시작해야 하나요?

출처와 다음 단계

모든 제공업체

OpenAI11

Anthropic12

Google14

xAI7

Alibaba Cloud12

DeepSeek4

Z.ai3

Moonshot AI3

MiniMax4

Xiaomi MiMo2

Tencent Hunyuan2

TypeSafe AI1

ByteDance6

Kling1

Suno1