Gemini API 프록시

모델 설명

이 API 서비스는 OpenAI의 /v1/images/generations API를 미러링하는 프록시 엔드포인트를 제공합니다. 이를 통해 기존 OpenAI 호환 애플리케이션과의 원활한 통합을 지원하며, gemini-2.5-flash-image 모델을 활용한 빠르고 효율적인 이미지 생성 기능을 제공합니다.

이 프록시는 OpenAI API 사양과의 호환성을 유지하면서, 종횡비 설정 및 이미지 편집과 같은 기능을 지원합니다.

기능

• ✅ OpenAI API 호환성: client.images.generate 메서드와 호환
• ✅ 유연한 제어: 종횡비(Aspect Ratio) 설정 지원
• ✅ 이미지 편집: Base64 이미지를 입력으로 한 편집 지원

API 엔드포인트

이 프록시 서비스는 두 가지 API 엔드포인트를 제공합니다:

OpenAI 호환 엔드포인트

POST /v1/images/generations

OpenAI의 client.images.generate() 메서드와 호환되는 엔드포인트

Google GenAI 호환 엔드포인트

POST /v1beta/models/google/gemini-2.5-flash-image:generateContent

Google의 client.models.generate_content() 메서드와 호환되는 엔드포인트

인증

프록시는 인증을 위해 Google API 키를 사용합니다. API 키를 얻으려면 Google AI Studio를 방문하세요.

사용법

방법 1: OpenAI 클라이언트 사용

설치

pip install openai pydantic

기본 설정

from openai import OpenAI

# 사용자 정의 기본 URL 및 API 키로 클라이언트 초기화
client = OpenAI(
    base_url="https://your-proxy-domain.com/v1",
    api_key="your-google-api-key-here"
)

예제

기본 이미지 생성

from openai import OpenAI

client = OpenAI(
    base_url="https://your-proxy-domain.com/v1",
    api_key="your-google-api-key-here"
)

response = client.images.generate(
    model="google/gemini-2.5-flash-image",
    prompt="미래 도시의 네온사인 거리를 걷는 사이버펑크 고양이",
    n=1,
    size="1024x1024"
)

print(response.data[0].url)

고급 옵션 사용 (종횡비)

표준 OpenAI 파라미터 외에 extra_body를 사용하여 aspect_ratio 같은 추가 기능을 활용할 수 있습니다.

response = client.images.generate(
    model="google/gemini-2.5-flash-image",
    prompt="광활한 알프스 산맥의 풍경, 초현실적인 스타일",
    extra_body={
        "aspect_ratio": "16:9"  # 16:9, 4:3, 1:1 등 지원
    }
)

print(response.data[0].url)

이미지 편집

Base64로 인코딩된 이미지를 함께 전달하여 이미지 편집을 수행할 수 있습니다.

이미지 편집

Base64로 인코딩된 이미지를 함께 전달하여 이미지 편집을 수행할 수 있습니다.

import base64

# 이미지를 Base64로 인코딩
with open("path/to/your/image.png", "rb") as image_file:
    encoded_image = base64.b64encode(image_file.read()).decode('utf-8')

response = client.images.generate(
    model="google/gemini-2.5-flash-image",
    prompt="이 이미지를 파란색 톤으로 변환해주세요",
    extra_body={
        "image": encoded_image
    }
)

print(response.data[0].url)

비동기 사용

import asyncio
from openai import AsyncOpenAI

async def main():
    client = AsyncOpenAI(
        base_url="https://your-proxy-domain.com/v1",
        api_key="your-google-api-key-here"
    )

    response = await client.images.generate(
        model="google/gemini-2.5-flash-image",
        prompt="수채화 스타일의 봄꽃 정원"
    )

    print(response.data[0].url)

asyncio.run(main())

방법 2: Google GenAI 클라이언트 사용

설치

pip install google-generativeai pillow

기본 설정

from google import genai

# 프록시 서버를 가리키도록 클라이언트 초기화
client = genai.Client(
    api_key="your-google-api-key-here",
    http_options={"base_url": "https://your-proxy-domain.com"}
)

예제

텍스트 프롬프트로 이미지 생성

from google import genai

client = genai.Client(
    api_key="your-google-api-key-here",
    http_options={"base_url": "https://your-proxy-domain.com"}
)

response = client.models.generate_content(
    model="google/gemini-2.5-flash-image",
    contents="미래 도시의 네온사인 거리를 걷는 사이버펑크 고양이"
)

# 생성된 이미지 처리
for candidate in response.candidates:
    for part in candidate.content.parts:
        if part.inline_data and part.inline_data.data:
            # part.inline_data.data는 이미지의 base64 인코딩된 바이트입니다
            image_data = part.inline_data.data
            print(f"Generated image: {len(image_data)} bytes")

이미지와 함께 프롬프트 사용 (이미지 편집)

from google import genai
from PIL import Image

client = genai.Client(
    api_key="your-google-api-key-here",
    http_options={"base_url": "https://your-proxy-domain.com"}
)

# 편집할 이미지 로드
source_image = Image.open("path/to/your/image.png")

response = client.models.generate_content(
    model="google/gemini-2.5-flash-image",
    contents=[
        "이 이미지를 파란색 톤으로 변환해주세요",
        source_image
    ]
)

# 생성된 이미지 처리
for candidate in response.candidates:
    for part in candidate.content.parts:
        if part.inline_data and part.inline_data.data:
            image_data = part.inline_data.data
            print(f"Edited image: {len(image_data)} bytes")

사용량 메타데이터 확인

response = client.models.generate_content(
    model="google/gemini-2.5-flash-image",
    contents="환상적인 풍경"
)

if hasattr(response, 'usage_metadata'):
    print(f"Prompt tokens: {response.usage_metadata.prompt_token_count}")
    print(f"Total tokens: {response.usage_metadata.total_token_count}")
    print(f"Completion tokens: {response.usage_metadata.total_token_count - response.usage_metadata.prompt_token_count}")

지원되는 매개변수

OpenAI 엔드포인트 (/v1/images/generations)

Google GenAI 엔드포인트 (/v1beta/models/gemini-2.5-flash-image:generateContent)

오류 처리

OpenAI 클라이언트 사용 시

from openai import OpenAI, APIError, RateLimitError, AuthenticationError

client = OpenAI(
    base_url="https://your-proxy-domain.com/v1",
    api_key="your-google-api-key-here"
)

try:
    response = client.images.generate(
        model="google/gemini-2.5-flash-image",
        prompt="테스트 이미지"
    )
    print(response.data[0].url)

except AuthenticationError:
    print("인증 실패: API 키를 확인하세요.")
except RateLimitError:
    print("속도 제한 초과: 잠시 후 다시 시도하세요.")
except APIError as e:
    print(f"API 오류: {e}")

Google GenAI 클라이언트 사용 시

from google import genai

client = genai.Client(
    api_key="your-google-api-key-here",
    http_options={"base_url": "https://your-proxy-domain.com"}
)

try:
    response = client.models.generate_content(
        model="google/gemini-2.5-flash-image",
        contents="테스트 이미지"
    )

    for candidate in response.candidates:
        for part in candidate.content.parts:
            if part.inline_data:
                print(f"Success: {len(part.inline_data.data)} bytes")

except Exception as e:
    print(f"오류 발생: {str(e)}")

속도 제한

프록시는 Google Gemini API의 속도 제한을 따릅니다. 구체적인 제한 사항은 Google AI Studio에서 확인하세요. 일반적인 패턴은 다음과 같습니다:

• 분당 요청 수
• 분당 토큰 수
• 동시 요청 수

지원되는 모델

프록시는 현재 gemini-2.5-flash-image 모델만 지원합니다. 모든 요청은 API 호출에서 "model": "gemini-2.5-flash-image"를 지정해야 합니다.

환경 변수 설정

프로덕션 사용을 위해 자격 증명을 환경 변수로 설정하세요:

export GOOGLE_API_KEY="your-google-api-key-here"
export OPENAI_BASE_URL="https://your-proxy-domain.com/v1"

그런 다음 Python에서 사용:

import os
from openai import OpenAI

client = OpenAI(
    base_url=os.getenv("OPENAI_BASE_URL"),
    api_key=os.getenv("GOOGLE_API_KEY")
)

또는 Google GenAI 클라이언트로:

import os
from google import genai

client = genai.Client(
    api_key=os.getenv("GOOGLE_API_KEY"),
    http_options={"base_url": os.getenv("OPENAI_BASE_URL").replace("/v1", "")}
)

OpenAI에서 마이그레이션

공식 OpenAI API에서 이 프록시로 마이그레이션하려면:

1. base_url 매개변수를 프록시 URL로 변경
2. API 키를 Google API 키로 업데이트
3. 다른 모든 코드는 동일하게 유지

# 이전 (OpenAI 공식)
client = OpenAI(api_key="sk-...")

# 이후 (프록시)
client = OpenAI(
    base_url="https://your-proxy-domain.com/v1",
    api_key="your-google-api-key"
)