소개
Gemini 3.7 Flash의 OpenAI 호환 채팅입니다. 1,048,576 토큰 읽기 창, 추론 강도 세 단계, 도구 정의 128개, JSON 출력이 동기 호출 한 번에 들어갑니다. 토막으로 받고 싶으면 stream: true를 넣으세요.
Gemini 3.7 Flash는 Google의 고속 Flash 모델로 일상적인 코딩, agent의 도구 호출, 안정적인 다단계 실행에 맞춰져 있고, 여기서는 OpenAI 호환 채팅 엔드포인트 하나로 공개합니다. 요청 한 번에 최대 1,048,576 토큰을 읽고 최대 65,536 토큰으로 답하며, 추론 강도는 턴마다 low, medium, high 사이에서 바꿉니다. 도구 호출과 JSON 출력은 OpenAI 방식 그대로입니다.
핵심 기능 및 하이라이트
루프 안에 넣을 만큼 빠릅니다
계획하고 도구를 부르고 결과를 읽고 다시 정하는 agent는 실제 시간의 대부분을 모델 기다리기에 씁니다. 이 모델은 바로 그 모양의 일을 위해 만들어졌습니다. 일상적인 코딩, 도구 사용, 다단계 실행입니다. 그래서 루프가 한 바퀴씩 제대로 닫히고 매 구간에서 멈추지 않습니다.
세 단계를 턴마다 고릅니다
low, medium, high이고 기본은 medium입니다. 같은 요청 본문 안의 문자열 하나라서, 평범한 수는 low로 돌리고 꼭 맞아야 하는 수만 high로 올릴 수 있습니다. 이 모델에는 minimal 단계가 없습니다. Google의 API가 먼저 거절하므로 이 엔드포인트도 조용히 다른 값으로 바꾸지 않고 그대로 거절합니다.
요청 하나에 1,048,576 토큰
모듈 하나와 그 테스트 전부, 도구 결과가 그대로 남아 있는 긴 agent 기록, 또는 한 번에 읽히는 문서 묶음이 들어갑니다. 이 상한은 시스템 프롬프트와 기록과 도구 출력을 함께 세므로, 예산은 마지막 메시지가 아니라 스레드 전체의 것입니다.
요청 파라미터
| 파라미터 | 필수 | 설명 |
|---|---|---|
messages | 예 | 오래된 순서대로 놓은 턴입니다. 내용은 문자열이거나 텍스트, |
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.675 / 출력 $3.375 100만 토큰당
활용 사례
일상적인 코딩 작업
diff를 읽고 무엇이 바뀌었는지 말하기, 빠져 있던 테스트 써 주기, 스택 트레이스를 패치로 바꾸기 같은 일입니다. 모두 짧고 잦은 요청이라 첫 토큰까지의 시간이 이 도구를 쓸지 말지를 그대로 정합니다.
Agent 도구 루프
요청 하나에 함수 정의를 최대 128개까지 넘기고, tool_choice로 특정 호출을 강제하거나 아예 부르지 않게 할 수 있습니다. 도구 호출이 OpenAI 형태로 돌아오므로 기존 agent 실행 환경은 model 값만 바꾸면 그대로 붙습니다.
긴 스레드 위의 다단계 실행
이미 도구를 여섯 번 부른 agent는 다음 요청에 그 여섯 건의 결과를 모두 실어 보냅니다. 1,048,576 토큰 창은 중간에 요약 단계를 끼우지 않고 그 스레드를 온전히 유지하기 위한 것입니다.
대량 구조화 추출
response_format으로 JSON 객체를 요구하고 키는 전부 system 메시지에서 이름으로 지정합니다. 로그 줄을 필드로, 티켓을 라벨로, 자유 텍스트를 스키마로 바꿉니다. 호출 한 번의 가격이 이 작업을 돌릴 가치가 있는지를 정합니다.
프롬프트 가이드 및 실전 팁
응답을 자르기 전에 생각할 자리를 먼저 비워 두십시오
기본 medium 강도에서는 쓰기 전에 먼저 생각하고, 그 생각이 응답과 같은 max_tokens 예산에서 빠집니다. 상한을 조이면 예산이 생각으로 사라지고 빈 문자열이 돌아옵니다. max_tokens에 여유를 주십시오. 코딩 답변이라면 몇천 토큰입니다. 짧은 답만 필요하고 굳이 생각시키지 않아도 되는 자리에서는 reasoning_effort를 low로 낮추십시오.
강도는 연동 단위가 아니라 턴 단위로 바꾸십시오
루프의 평범한 단계는 low로 돌려 첫 토큰을 빨리 받고, 꼭 맞아야 하는 단계만 high로 보내십시오. 같은 엔드포인트, 같은 본문, 문자열 하나만 다릅니다.
미리 감안할 한계
reasoning_effort는 low, medium, high만 받습니다. Google의 API가 이 모델에서 minimal을 거절하므로 이 엔드포인트도 조용히 다른 값으로 바꾸지 않고 거절합니다. 응답 상한은 65,536 토큰이고 그보다 큰 max_tokens는 입력 검증에서 바로 막힙니다. 메시지 내용은 텍스트, 이미지, 비디오를 받고 오디오 파트는 거절됩니다. 비디오는 업로드한 파일로 보내며, 요청 한 건에 담는 비디오는 합계 14 MB까지 가능합니다.
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.7-flash/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 레퍼런스에서 확인하세요.
