구글 최신 AI 제미나이 2.5 플래시 이미지 API 공짜로 쓰는 법

 

구글 최신 AI 제미나이 2.5 플래시 이미지 API 공짜로 쓰는 법

최근 AI 기술의 발전 속도가 정말 무서울 정도인데요.

특히 텍스트뿐만 아니라 이미지를 이해하고, 심지어 새로운 이미지를 만들어내는 멀티모달 AI의 등장은 개발자들에게 완전히 새로운 가능성의 문을 열어주었습니다.

바로 그 최전선에 있는 구글의 최신 모델, 'Gemini 2.5 Flash'가 최근 개발자들 사이에서 큰 화제거든요.

그런데 더 놀라운 소식은, 이 강력한 이미지 API를 '무료'로 마음껏 테스트해 볼 수 있는 방법이 생겼다는 겁니다.

오늘은 바로 그 비밀의 문, 'OpenRouter'를 통해 Gemini 2.5 Flash 이미지 API를 어떻게 내 프로젝트에 연동하고 활용할 수 있는지, 그 모든 과정을 A부터 Z까지 상세하게 알려드리겠습니다.

OpenRouter 그게 도대체 뭔데

먼저 OpenRouter라는 서비스가 생소한 분들을 위해 간단히 짚고 넘어가야 하는데요.

OpenRouter는 OpenAI, Anthropic, Google, Mistral 등 전 세계 수많은 AI 모델들을 마치 '환승 센터'처럼 한 곳에 모아놓고, 단 하나의 API 키만으로 모든 모델을 동일한 방식으로 호출할 수 있게 해주는 아주 편리한 서비스입니다.

개발자 입장에서는 모델마다 다른 API 문서를 뒤지고 코드를 수정할 필요 없이, 모델 이름만 바꿔주면 되니 정말 편한데요.

가장 큰 매력은 바로 일부 모델에 대해 '무료 티어'를 제공한다는 점입니다.

이번에 풀린 'Nano Banana', 즉 gemini-2.5-flash-image-preview 모델이 바로 여기에 해당되는 겁니다.

 

실전 준비 시작하기

백문이 불여일견이죠.

바로 코드를 실행해 보면서 이 강력한 기능을 직접 체험해 보겠습니다.

아래 깃허브 리포지토리에 모든 준비가 되어 있습니다.

1. 리포지토리 클론하기

먼저 터미널을 열고 아래 명령어를 입력해서 예제 코드가 담긴 리포지토리를 내 컴퓨터로 가져오는데요.

이 글에서는 해당 리포지토리의 gemini2.5_image_generation 폴더를 사용할 예정입니다.

git clone https://github.com/personabb/langchain_asap_sample.git
cd langchain_asap_sample/gemini2.5_image_generation

2. OpenRouter API 키 발급받기

이제 OpenRouter에 접속해서 API 키를 발급받아야 하는데요.

웹사이트에 로그인하고 나면 대시보드에서 아주 간단하게 키를 생성할 수 있습니다.

키를 발급받았다면, 방금 클론한 폴더 안에 있는 .env.example 파일의 이름을 .env로 변경하고, 파일 안의 OPENROUTER_API_KEY 값을 여러분이 발급받은 키로 교체해 주세요.

OPENROUTER_API_KEY="여러분이-발급받은-API-키를-여기에-붙여넣으세요"

3. 개발 환경 설정하기

이제 파이썬 코드를 실행하는 데 필요한 라이브러리들을 설치할 차례인데요.

아래 명령어를 실행하면 requirements.txt 파일에 명시된 모든 패키지가 자동으로 설치됩니다.

pip install -r requirements.txt

만약 uv와 같은 최신 패키지 매니저를 사용하신다면 uv sync 명령어로도 동일한 환경을 구성할 수 있습니다.

이미지 생성 API 실행하기

모든 준비가 끝났습니다.

이제 스크립트를 직접 실행해서 AI가 이미지를 만들어내는 마법을 경험해 볼 시간입니다.

1. 파라미터 수정하기

실행하기 전에, openrouter_image_editing_api_eng.py 파일을 열어 몇 가지 옵션을 입맛에 맞게 수정할 수 있거든요.

어떤 이미지를, 어떻게 바꿀지 직접 정해보는 겁니다.

# openrouter_image_editing_api_eng.py

# ========== 한 번에 생성할 이미지 개수 지정 ==========
generate_images = 5

# ========== 불러올 원본 이미지 경로 ==========
file_path = "inputs/images3.png"

# ========== 이미지 편집 요청 내용 (프롬프트) ==========
query = "Turn it into a 3D figure. However, make the pose a cooler, more stylish girl's pose."

# ===================================================

generate_images는 생성할 결과물 이미지의 개수이고, file_path는 편집의 바탕이 될 원본 이미지 파일의 경로입니다.

그리고 가장 중요한 query가 바로 AI에게 내리는 구체적인 지시사항, 즉 '프롬프트'입니다.

2. 실행 명령어

이제 터미널에서 아래 명령어를 입력하면 드디어 코드가 실행되는데요.

잠시 기다리면 outputs 폴더 안에 AI가 새로 생성한 이미지들이 저장될 겁니다.

python openrouter_image_editing_api_eng.py

API 호출 코드 심층 분석

단순히 코드를 실행하는 것을 넘어, 그 안에서 어떤 일이 일어나는지 이해하는 것이 진짜 실력이 되거든요.

핵심 로직이 담긴 call_openrouter_api 함수를 함께 뜯어보겠습니다.

def call_openrouter_api(system_prompt, user_query, image_base64, api_key, endpoint, temperature=0.7):
    headers = {
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json",
    }

    payload = {
        "model": "google/gemini-2.5-flash-image-preview:free",
        "messages": [
            { "role": "system", "content": system_prompt },
            {
                "role": "user",
                "content": [
                    { "type": "text", "text": user_query },
                    {
                        "type": "image_url",
                        "image_url": { "url": f"data:image/png;base64,{image_base64}" }
                    }
                ]
            }
        ],
        "temperature": temperature,
        # 이미지 생성을 활성화하는 OpenRouter 전용 파라미터
        "modalities": ["image", "text"]
    }

    response = requests.post(f"{endpoint}/chat/completions", headers=headers, json=payload)
    return response.json()

여기서 가장 중요한 부분은 바로 payload 객체인데요.

이것이 바로 우리가 OpenRouter 서버로 보내는 요청의 본문입니다.

• model: 어떤 AI 모델을 사용할지 지정하는 부분인데요. 여기서 :free라는 꼬리표가 붙어있는 것이 바로 무료 티어 모델을 사용하겠다는 의미입니다.
• messages: AI와 어떤 대화를 나눌지 정의하는 배열입니다. role: "system"은 AI에게 기본적인 역할이나 지침을 부여하고, role: "user"가 우리가 실제로 AI에게 던지는 질문이나 명령을 담습니다.
• content: 이 부분이 바로 멀티모달 AI의 핵심인데요. type: "text"와 type: "image_url" 두 가지 요소를 배열에 함께 담아 보냄으로써, "이 텍스트와 이 이미지를 함께 보고 이해해서 답해줘"라는 복합적인 요청을 보낼 수 있습니다.
• modalities: 이건 OpenRouter만의 특별한 파라미터인데요. AI의 응답으로 '이미지'를 기대하고 있다는 것을 명시적으로 알려주는 역할을 합니다. 이 옵션을 빼먹으면 텍스트 응답만 돌아올 수 있으니 아주 중요합니다.

참고로, 원래는 LangChain 라이브러리를 통해 더 추상화된 방식으로 호출하고 싶었지만, 현재 LangChain의 ChatOpenAI 클래스가 OpenRouter의 이미지 출력 형식을 완벽하게 지원하지 않아 직접 requests 라이브러리를 사용해 API를 호출하는 방식을 선택했습니다.

전문가의 꿀팁 몇 가지

마지막으로, 이 API를 사용하면서 겪을 수 있는 몇 가지 문제와 팁을 알려드리려고 하는데요.

이것만 알아두셔도 훨씬 수월하게 원하는 결과를 얻으실 수 있을 겁니다.

가장 중요한 팁은 바로 '프롬프트는 영어로 작성하라'는 것입니다.

아직 대부분의 AI 모델이 영어 데이터로 주로 학습되었기 때문에, 한글로 프롬프트를 입력하면 이미지가 생성되지 않고 텍스트 설명만 툭 뱉어내는 경우가 종종 발생하거든요.

원하는 이미지를 얻고 싶다면, 조금 번거롭더라도 프롬프트는 꼭 영어로 작성하는 것을 추천합니다.

마무리하며

어떠셨나요.

단 몇 줄의 코드로 최신 AI 이미지 생성 기술을 내 손으로 직접 다룰 수 있다는 사실이 정말 흥미롭지 않나요.

비록 지금은 무료 티어로 제공되지만, 언제 유료로 전환될지 모르니 마음껏 실험해보며 아이디어를 구체화해볼 절호의 기회입니다.

OpenRouter 덕분에 우리는 더 이상 비싼 API 사용료나 복잡한 설정에 발목 잡히지 않고, 오직 창의적인 아이디어를 구현하는 데에만 집중할 수 있게 되었습니다.

이 강력한 도구를 이용해 여러분은 어떤 놀라운 것을 만들어내실 건가요.

이제 여러분의 상상력을 마음껏 펼쳐볼 시간입니다.

---