Google의 Gemini 제품군은 대용량 워크로드에 적합한 최신 모델 라인업입니다. Gemini 2.5 Pro는 백만 토큰당 $1.25 / $10 수준이고, Flash 계열은 더 저렴합니다. 하지만 무료 공개 앱, 사이드 프로젝트, 해커톤 프로젝트처럼 사용자가 많아지면 비용은 빠르게 누적됩니다. Puter.js는 이 과금 구조를 다르게 처리합니다. 개발자가 Google API 키를 관리하지 않고도 Gemini 2.5 Pro, 2.5 Flash, 2.0 Flash, 3 Flash Preview, Gemma 2/3/4 계열을 사용할 수 있으며, 사용량은 최종 사용자의 Puter 계정에 귀속됩니다.
요약
- Puter.js를 사용하면 Google API 키, Google Cloud 프로젝트, 서버 없이 Gemini 및 Gemma 모델을 브라우저에서 호출할 수 있습니다.
- 지원 Gemini 모델: 2.5 Pro, 2.5 Flash, 2.5 Flash Lite, 2.0 Flash, 2.0 Flash Lite, 3 Flash Preview 및 일부 이전 프리뷰 버전.
- 지원 Gemma 모델: 여러 크기의 Gemma 2, 3, 4 계열.
- 설치는
<script>태그 하나로 끝납니다. - 채팅, 스트리밍, 이미지 입력, 온도 조절을 브라우저에서 처리할 수 있습니다.
- 사용량은 최종 사용자의 Puter 계정에 연결되므로 개발자는 Google API 비용을 직접 부담하지 않습니다.
- Puter 기반 프로토타입과 공식 Gemini API를 비교하거나 마이그레이션 계획을 세울 때는 Apidog를 사용할 수 있습니다.
“무료 무제한”이 작동하는 방식
Puter.js는 개발자가 Google AI Studio 키를 발급받고 모든 토큰 비용을 부담하는 방식이 아닙니다. 대신 사용자가 Puter에 로그인하고, 해당 사용자의 Puter 계정 잔액에서 호출 비용이 처리됩니다. 새 Puter 계정에는 초기 크레딧이 제공되며, 사용자는 필요하면 추가로 충전할 수 있습니다.
개발자 입장에서 얻는 이점은 다음과 같습니다.
- Google Cloud 프로젝트가 필요 없습니다.
- Google AI Studio 키를 저장하거나 노출할 필요가 없습니다.
- 서버 없이 정적 웹앱에서도 Gemini를 호출할 수 있습니다.
- 개발자 계정 기준의 토큰 비용 부담이 없습니다.
주의할 점도 있습니다. Puter.js는 브라우저 우선 방식입니다. 로그인한 사용자 세션을 전제로 하므로, 백엔드 cron 작업, 배치 처리, 서버 간 호출에는 적합하지 않습니다.
1단계: 설치
정적 HTML에서는 CDN 스크립트 하나만 추가하면 됩니다.
<script src="https://js.puter.com/v2/"></script>
번들러 기반 앱에서는 패키지로 설치할 수 있습니다.
npm install @heyputer/puter.js
import { puter } from '@heyputer/puter.js';
2단계: 모델 선택
Puter에서 사용할 수 있는 주요 Gemini 및 Gemma 모델은 다음과 같습니다.
| 모델 ID | 사용 시점 |
|---|---|
google/gemini-2.5-pro |
복잡한 추론, 긴 컨텍스트 분석, 고품질 응답이 필요한 작업 |
google/gemini-2.5-flash |
대부분의 일반 채팅, Q&A, 콘텐츠 생성 |
google/gemini-2.5-flash-lite |
대량 분류, 태깅, 짧은 응답 중심 작업 |
google/gemini-2.0-flash |
안정적인 기준선이 필요한 경우 |
google/gemini-3-flash-preview |
최신 Flash 프리뷰 모델을 테스트할 때 |
google/gemma-3-27b-it |
오픈 Gemma 기반 지시 튜닝 모델이 필요한 경우 |
google/gemma-4-31b-it |
더 큰 오픈 Gemma 계열을 테스트할 때 |
대부분의 앱에서는 google/gemini-2.5-flash를 기본값으로 두는 것이 좋습니다. 복잡한 추론 작업만 google/gemini-2.5-pro로 올리고, 대량 분류나 단순 태깅은 google/gemini-2.5-flash-lite로 낮추면 됩니다.
3단계: Gemini 호출하기
가장 작은 예제는 다음과 같습니다.
<!DOCTYPE html>
<html>
<body>
<script src="https://js.puter.com/v2/"></script>
<script>
puter.ai.chat(
"머신러닝을 세 문장으로 설명해 주세요.",
{ model: 'google/gemini-2.5-flash' }
).then(response => {
puter.print(response);
});
</script>
</body>
</html>
실행 흐름은 간단합니다.
- 브라우저에서 HTML 파일을 엽니다.
- 사용자가 Puter에 로그인합니다.
-
puter.ai.chat()이 Gemini 모델을 호출합니다. - 응답이 페이지에 출력됩니다.
API 키, 환경 변수, 백엔드 서버가 필요 없습니다.
4단계: 응답 스트리밍하기
채팅 UI나 긴 답변을 다룰 때는 스트리밍을 사용하는 편이 좋습니다.
const response = await puter.ai.chat(
"광합성에 대해 자세히 설명해 주세요.",
{
model: 'google/gemini-2.5-flash',
stream: true,
}
);
for await (const part of response) {
if (part?.text) {
outputDiv.innerHTML += part.text;
}
}
part.text는 응답의 일부 청크입니다. 이를 UI에 순차적으로 추가하면 사용자는 답변이 실시간으로 생성되는 것처럼 볼 수 있습니다.
간단한 UI 예시는 다음과 같이 구성할 수 있습니다.
<div id="output"></div>
<script src="https://js.puter.com/v2/"></script>
<script>
const outputDiv = document.getElementById('output');
async function run() {
const response = await puter.ai.chat(
"Next.js API Route와 Server Action의 차이를 설명해 주세요.",
{
model: 'google/gemini-2.5-flash',
stream: true,
}
);
for await (const part of response) {
if (part?.text) {
outputDiv.innerHTML += part.text;
}
}
}
run();
</script>
5단계: 이미지 입력 사용하기
Gemini는 텍스트뿐 아니라 이미지 입력도 처리할 수 있습니다. Puter에서는 두 번째 인수로 이미지 URL을 전달합니다.
puter.ai.chat(
"이 이미지에서 무엇을 보시나요? 색상, 사물, 분위기를 설명해 주세요.",
"https://assets.puter.site/doge.jpeg",
{ model: 'google/gemini-2.5-flash' }
).then(response => {
puter.print(response);
});
적용 가능한 사용 사례는 다음과 같습니다.
- 이미지 대체 텍스트 생성
- 제품 이미지 태그 지정
- 스크린샷 분석
- 시각적 Q&A
- OCR 보조 작업
- 접근성 도구
자연 이미지와 다이어그램에는 잘 맞지만, 텍스트가 매우 많은 스크린샷에서는 다른 모델이 더 나은 결과를 줄 수도 있습니다.
6단계: 온도 조절하기
temperature는 응답의 다양성과 창의성을 조절합니다.
const response = await puter.ai.chat(
'로봇 요리사에 대한 창의적인 단편 소설을 써 주세요.',
{
model: 'google/gemini-2.5-flash',
temperature: 0.2,
}
);
실무에서는 다음 기준으로 시작하면 됩니다.
| 목적 | 권장 temperature |
|---|---|
| 사실 기반 Q&A |
0.0 ~ 0.3
|
| JSON, 분류, 태깅 |
0.0 ~ 0.2
|
| 일반 채팅 |
0.5 ~ 0.7
|
| 창의적 글쓰기 |
0.7 ~ 1.0
|
구조화된 출력이 필요하면 낮게 설정하고, 아이디어 생성이나 스토리 작성에는 높게 설정하세요.
7단계: 다중 턴 대화 만들기
이전 대화 맥락을 유지하려면 메시지 배열을 전달합니다.
const messages = [
{ role: 'user', content: '저는 Postgres와 함께 Next.js 앱을 만들고 있습니다.' },
{ role: 'assistant', content: '알겠습니다. 무엇을 도와드릴까요?' },
{ role: 'user', content: '마이그레이션 구조를 어떻게 잡아야 할까요?' },
];
const response = await puter.ai.chat(messages, {
model: 'google/gemini-2.5-pro',
});
console.log(response);
채팅 앱에서는 새 메시지가 생길 때마다 배열에 추가하면 됩니다.
const messages = [];
async function sendMessage(userInput) {
messages.push({
role: 'user',
content: userInput,
});
const response = await puter.ai.chat(messages, {
model: 'google/gemini-2.5-flash',
});
messages.push({
role: 'assistant',
content: response,
});
return response;
}
중요한 점은 다음 호출 전에 이전 사용자 메시지와 어시스턴트 응답을 모두 배열에 보존하는 것입니다.
동일한 프롬프트로 Gemini와 다른 모델 비교하기
Puter는 하나의 인터페이스로 여러 LLM을 호출할 수 있습니다. 같은 프롬프트를 여러 모델에 보내면 지연 시간과 응답 품질을 비교할 수 있습니다.
const models = [
'google/gemini-2.5-flash',
'claude-sonnet-4-6',
'gpt-5.5',
'x-ai/grok-4.3',
];
const prompt = "이 React 컴포넌트를 훅을 사용하도록 리팩토링하세요: ...";
for (const model of models) {
const start = performance.now();
const response = await puter.ai.chat(prompt, { model });
const elapsed = performance.now() - start;
console.log(`${model}: ${elapsed.toFixed(0)}ms`);
console.log(response);
console.log('---');
}
비교할 때는 최소한 다음 항목을 기록하세요.
- 첫 토큰까지의 체감 지연 시간
- 전체 응답 시간
- 코드 정확도
- 포맷 준수 여부
- 재시도 필요 여부
- 사용자가 실제로 선호하는 응답
한 번의 실행 결과만으로 결정하지 말고, 실제 앱에서 자주 쓰는 프롬프트 세트를 기준으로 반복 테스트하는 것이 좋습니다.
얻는 것과 얻지 못하는 것
얻는 것
- Gemini 2.5 / 2.0 / 3 Flash 계열 및 2.5 Pro
- Gemma 2 / 3 / 4 계열
- 다중 턴 대화
- 스트리밍 응답
- 이미지 URL 기반 비전 입력
-
temperature,max_tokens, 시스템 프롬프트 등 기본 옵션 - 브라우저 기반 앱에서 사용할 수 있는 간단한 통합 방식
얻지 못할 수 있는 것
Puter 버전과 모델 지원 상태에 따라 다음 기능은 제한될 수 있습니다.
- Gemini의 네이티브 함수 호출
- 코드 실행 도구
- Google 검색 기반 기능
- Gemini의 전체 2M 토큰 컨텍스트 상한
- 브라우저 세션 없는 서버 측 사용
- Google API의 직접적인 비율 제한 정보
코드 실행, 검색 기반 에이전트, 매우 긴 컨텍스트, 서버 측 자동화가 핵심이면 공식 Google AI Studio API가 더 적합합니다. 일반적인 채팅, Q&A, 콘텐츠 생성, 이미지 설명 작업이라면 Puter로 충분한 경우가 많습니다.
Puter와 공식 Gemini API 선택 기준
Puter를 선택할 때
- 무료 공개 앱을 출시하지만 API 비용 노출을 피하고 싶을 때
- 해커톤이나 프로토타입을 빠르게 만들 때
- Google Cloud 프로젝트를 만들고 싶지 않을 때
- 정적 사이트나 브라우저 확장 프로그램에서 Gemini를 쓰고 싶을 때
- 사용자가 Puter 로그인 단계를 받아들일 수 있을 때
공식 Gemini API를 선택할 때
- 서버 측 호출이 필요할 때
- cron, 배치, 웹훅에서 모델을 호출해야 할 때
- 코드 실행이나 검색 기반 기능이 필요할 때
- 전체 2M 컨텍스트 상한이 필요한 워크로드일 때
- Google과의 직접 계약 관계가 필요한 규정 준수 환경일 때
- 사용자가 Puter 로그인을 허용하지 않을 때
Gemini 3 Flash를 직접 사용하는 방법은 Gemini 3 Flash Preview API 사용 방법을 참고하세요.
Apidog에서 통합 테스트하기
Puter 호출은 브라우저에서 발생하므로 일반적인 백엔드 테스트 러너에서 그대로 실행하기 어렵습니다. 대신 다음 구조로 테스트 환경을 나누는 것이 좋습니다.
- Puter 스크립트를 포함한 작은 정적 테스트 페이지를 만듭니다.
- 프롬프트를 쿼리 파라미터나 입력 폼으로 전달합니다.
- 공식 Gemini API로 마이그레이션할 가능성이 있다면 Apidog에서 별도 컬렉션을 구성합니다.
- Puter 프로토타입 환경과 Gemini API 환경을 분리해 둡니다.
예시 환경 구성:
| 환경 | 용도 |
|---|---|
puter-prototype |
Puter 페이지를 호스팅하는 localhost 또는 정적 URL |
gemini-prod |
https://generativelanguage.googleapis.com/v1 기반 공식 API |
Apidog를 다운로드한 뒤 두 환경을 만들어 두면, Puter 기반 프로토타입에서 공식 Gemini API로 전환할 때 요청 구조를 더 쉽게 비교할 수 있습니다.
API 테스트 패턴은 QA 엔지니어를 위한 API 테스트 도구도 참고할 수 있습니다.
Puter를 통한 기타 무료 LLM 경로
같은 사용자 지불 모델은 다른 주요 LLM에도 적용됩니다.
Puter에서는 model 문자열을 바꾸는 방식으로 공급자를 전환할 수 있습니다.
const response = await puter.ai.chat("API 설계를 리뷰해 주세요.", {
model: 'google/gemini-2.5-flash',
});
다른 모델을 테스트하려면 model 값만 변경합니다.
const response = await puter.ai.chat("API 설계를 리뷰해 주세요.", {
model: 'claude-sonnet-4-6',
});
FAQ
정말 무제한인가요?
개발자 계정 기준으로는 사용량을 직접 부담하지 않습니다. 최종 사용자의 Puter 계정 잔액에서 호출이 처리됩니다. 새 계정에는 초기 크레딧이 제공되며, 사용자가 더 필요하면 충전할 수 있습니다.
Google 계정이나 Google Cloud 프로젝트가 필요한가요?
아니요. Puter가 Google API 호출을 처리하므로 개발자는 Google API 키를 직접 관리하지 않아도 됩니다.
프로덕션에서 사용할 수 있나요?
브라우저 기반 앱이라면 사용할 수 있습니다. 다만 사용자에게 Puter 로그인 단계가 필요하다는 점을 제품 흐름에서 고려해야 합니다.
Puter를 통한 Gemini가 공식 API와 동일하게 동작하나요?
Puter는 사용자를 대신해 모델 호출을 처리합니다. 모델 출력은 같은 모델을 기준으로 하지만, Puter 계층이 추가되므로 지연 시간이 달라질 수 있습니다.
Gemini의 2M 토큰 컨텍스트도 사용할 수 있나요?
Puter가 모든 모델 변형에서 전체 2M 토큰 상한을 노출한다고 가정하면 안 됩니다. 극단적으로 긴 컨텍스트가 필요하면 공식 Google AI Studio API를 사용하는 편이 안전합니다.
Discord 봇이나 백엔드 서비스에서 Puter Gemini를 사용할 수 있나요?
권장되지 않습니다. Puter는 브라우저 우선이며 사용자 세션을 전제로 합니다. Discord 봇, cron, 백엔드 서비스는 공식 Gemini API를 직접 사용하는 것이 적합합니다.
기본 모델은 무엇을 쓰면 되나요?
google/gemini-2.5-flash를 기본값으로 시작하세요. 대부분의 프롬프트에서 속도와 품질의 균형이 좋습니다. 복잡한 추론은 google/gemini-2.5-pro, 대량 분류는 google/gemini-2.5-flash-lite로 분기하면 됩니다.
이미지 생성도 지원되나요?
Puter는 현재 OpenAI의 gpt-image-2 및 DALL-E 변형을 통해 이미지 생성을 노출하며, Imagen은 아닙니다. 이미지 생성 경로는 무료 무제한 GPT-5.5 API 얻기를 참고하세요.
마무리
Puter.js를 사용하면 Google Cloud 설정 없이 브라우저 기반 앱에서 Gemini를 빠르게 통합할 수 있습니다. 스크립트를 추가하고, google/gemini-2.5-flash를 기본 모델로 선택한 뒤, 필요한 프롬프트를 호출하면 됩니다.
서버 측 Gemini 호출, 미세 조정, 코드 실행 도구, 전체 2M 토큰 컨텍스트가 필요하다면 공식 Google AI Studio API가 더 적합합니다. 반대로 프로토타입, 해커톤, 무료 공개 앱, 정적 사이트라면 Puter가 훨씬 빠른 시작점이 될 수 있습니다.
Apidog에서 요청을 구성하고, Puter 기반 프로토타입과 공식 Gemini API를 비교해 보세요. 실제 프롬프트, 응답 품질, 지연 시간 기준으로 앱에 맞는 경로를 선택하는 것이 가장 안전합니다.
Top comments (0)