소개
Gemini 3 Flash Preview의 OpenAI 호환 채팅입니다. 256,000 토큰 읽기 창, 추론 강도 세 단계, 도구 스키마 128개, JSON 출력이 동기 호출 한 번에 들어갑니다. 토막으로 받고 싶으면 stream: true를 넣으세요.
Gemini 3 Flash Preview는 Google의 경량 채팅 모델이고, 여기서는 OpenAI 호환 엔드포인트 하나로 제공됩니다. 단가가 낮고 첫 토큰이 빨라서 턴제 롤플레이와 인터랙티브 픽션에서 먼저 집게 되는 모델입니다. 최대 256,000 토큰을 읽고 최대 65,536 토큰으로 답하며, 추론 강도 세 단계와 도구 호출, JSON 출력을 지원합니다.
핵심 기능 및 하이라이트
짧은 턴을 수백 번 도는 칸
한 시간에 수백 턴이 오가는 장면에서 체감을 정하는 건 단가와 첫 토큰까지의 시간이지, 모델의 최고 성능이 아닙니다. 이 모델은 그 일을 맡으라고 있습니다. 플레이어의 모든 대사를 모델에 태워도 괜찮을 만큼 싸고, 대화가 로딩에서 멈추지 않을 만큼 빠릅니다.
턴마다 한 번 더 생각할지 정합니다
low, medium, high 세 단계이고 기본값은 medium입니다. 평범한 주고받기는 low로 두어 첫 토큰을 빠르게 하고, 복선을 회수하는 그 턴만 high로 올립니다. 같은 요청 본문의 문자열 하나라서 전환에 드는 통합 비용이 없습니다.
언제든 바뀔 수 있습니다
프리뷰 모델의 수명은 Google이 쥐고 있고, 동작과 가용성이 예고 없이 움직입니다. 운영에 넣기 전에 이 모델이 내려가는 날 어느 모델로 넘길지 정해 두세요.
요청 파라미터
| 파라미터 | 필수 | 설명 |
|---|---|---|
messages | 예 | 오래된 순서대로 놓은 턴입니다. 내용은 문자열이거나 text, |
max_tokens | 아니요 | 응답을 65,536에서 자릅니다. 기본값은 16,384입니다. |
reasoning_effort | 아니요 | minimal, low, medium, high이고 기본은 medium입니다. 평범한 턴은 low로 충분하고, 결판을 내야 하는 턴만 따로 high로 올리면 됩니다. |
stop | 아니요 | 최대 4개의 정지 시퀀스를 문자열 또는 배열로 지정합니다. 모델이 그중 하나를 쓰는 즉시 응답이 끝나며, 일치한 텍스트 자체는 반환되지 않습니다. 1자 이상 · 1개 이상 · 4개 이하 |
seed | 아니요 | 임의의 정수입니다. 다른 조건이 같은 요청에 같은 seed를 쓰면 응답이 거의 그대로 재현되므로, 한 번에 한 가지만 바꿔 공정하게 비교할 수 있습니다. |
temperature | 아니요 | 0에서 2까지, 기본 1입니다. Google은 Gemini 3 계열을 기본값 1.0 그대로 쓰라고 권하고, 1.0 아래로 내리면 같은 말을 맴돌거나 품질이 떨어질 수 있습니다. |
top_p | 아니요 | 0.01에서 1입니다. 이것과 temperature 중 하나만 움직이고 같은 비교에서 둘 다 건드리지 마세요. |
tools | 아니요 | 요청 하나에 함수 정의 최대 128개입니다. 128개 이하 |
tool_choice | 아니요 | auto, none, required 또는 함수 하나를 지정하는 객체입니다. |
response_format | 아니요 | JSON 객체를 요구하고 키는 전부 system 메시지에서 이름으로 지정하세요. 분기 선택지가 파싱 가능한 형태로 돌아오는 이유입니다. |
요금
입력 $0.45 / 출력 $2.70 100만 토큰당
활용 사례
턴제 롤플레이
캐릭터 시트와 세계관, 말투를 system 메시지 하나에 고정하고 턴마다 새 대사만 보냅니다. 한 시간에 수백 턴이 도는 속도에서는 모델의 상한보다 단가와 첫 토큰까지의 시간이 장면의 체감을 훨씬 크게 좌우합니다.
지문과 분기 선택지 생성
다음 장면을 한 단락 밀고 선택지 세 개를 같이 받습니다. response_format으로 JSON 객체를 요구하고 키를 system 메시지에 적어 두면 선택지의 모양이 흔들리지 않습니다. 텍스트 어드벤처의 화면 하나가 이 호출 한 번입니다.
긴 세션의 계층 분리
평범한 주고받기는 여기에 맡기고, 정체가 드러나는 장면이나 대치, 마흔 턴을 한 문단으로 접는 작업만 더 비싼 모델로 보냅니다. 둘 다 OpenAI 형식이라 바뀌는 건 model 값뿐입니다.
대량 라벨링과 정형화
대화 로그에 태그 붙이기, 요약 다시 쓰기, 자유 서술을 고정 필드로 정리하기. 이런 작업이 돌아갈지는 최고 성능이 아니라 호출당 단가가 결정합니다.
프롬프트 가이드 및 실전 팁
설정은 system, 연기는 user에
캐릭터 시트, 세계관, 서술 규칙은 system 메시지 하나에 모으고, 턴마다 새 user와 assistant만 덧붙입니다. system을 건드리지 않아야 어느 대사가 말투를 바꿨는지 알 수 있습니다.
강도는 통합 단위가 아니라 턴 단위로
평범한 주고받기는 low로 두어 첫 토큰을 앞당기고, 매듭을 짓는 턴만 high로 보냅니다. 엔드포인트도 본문도 같고 문자열 하나만 다릅니다.
미리 감안할 한계
응답 상한은 65,536 토큰이고, 그보다 큰 max_tokens는 검증에서 바로 막힙니다. 메시지 내용은 텍스트, 이미지, 동영상, 오디오입니다. 업로드한 동영상과 오디오는 요청 하나에 합계 14 MB까지 가능합니다. JSON response_format은 응답의 모양을 잡아 주지만 파싱과 검증은 애플리케이션 몫입니다. 프리뷰 모델이라 Google이 동작을 바꾸거나 내릴 수 있으니, 프로덕션 트래픽을 태우기 전에 대체 모델을 정해 두세요.
API 빠른 시작
curl --fail-with-body -sN https://api.spicyapi.ai/v1/chat/completions \
-H "Authorization: Bearer $SPICY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"model": "google/gemini-3-flash-preview/chat",
"messages": [
{
"role": "user",
"content": "Summarise the following release notes into three bullet points."
}
],
"stream": true
}' \
| jq --unbuffered -Rrj 'select(startswith("data: ")) | .[6:] | select(. != "[DONE]") | fromjson | if .error then "\n[error] \(.error.message)\n" else (.choices[0].delta.content? // empty) end'
인증, 전체 스키마, 폴링과 오류 처리는 API 레퍼런스에서 확인하세요.
