소개
Gemini 3.1 Pro Preview의 OpenAI 호환 대화입니다. 1,000,000 토큰 읽기 창, 추론 강도 3단계, tool 정의 128개, JSON 출력이 동기 호출 한 번에 들어갑니다.
Gemini 3.1 Pro Preview는 Google의 롱컨텍스트 대화 모델이고, OpenAI 호환 엔드포인트 하나로 제공됩니다. 최대 1,000,000 토큰을 읽고 최대 32,768 토큰으로 답하니 대략 30 대 1이라, 설정집과 기록 전체를 넣고 아귀가 맞는 한 턴을 받는 쓰임새입니다.
핵심 기능 및 하이라이트
책장 하나를 읽고 한 문단을 씁니다
입력 1,000,000 토큰에 출력 32,768 토큰, 대략 30 대 1이고 이 비율이 곧 사용 설명서입니다. 설정집과 캐릭터 시트, 지금까지 쓴 모든 챕터를 붙여 보내고 장면을 밀고 나갈 응답 하나만 받으세요. 돌아오는 글은 설계상 짧지만 보낸 모든 페이지와 아귀가 맞습니다.
기록을 압축하지 않고 그대로 데려갑니다
장편 롤플레이가 어긋나는 이유는 대개 창에 맞추려고 기록을 요약하기 때문입니다. 1,000,000 토큰 창은 보통 그 단계를 통째로 없앱니다. 매 턴 원문을 다시 보내면 서른 챕터 전에 심어 둔 디테일이 요약문 속이 아니라 모델 눈앞에 그대로 남습니다.
예고 없이 바뀔 수 있습니다
프리뷰 모델의 수명은 Google이 쥐고 있습니다. 동작도 가용성도 가격도 움직일 수 있고 내려갈 수도 있습니다. 운영 스레드를 맡기기 전에 그 스레드가 어느 모델로 물러설지 정해 두세요.
요청 파라미터
| 파라미터 | 필수 | 설명 |
|---|---|---|
messages | 예 | 순서대로 놓인 대화 턴입니다. 내용은 문자열이거나 텍스트와 |
max_tokens | 아니요 | 응답을 32,768에서 자릅니다. 읽기 창의 30분의 1이고, 기본값은 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 메시지에 키를 하나씩 다 적어 두세요. |
요금
입력 $1.90 / 출력 $11.40 100만 토큰당; 200K 토큰 초과 프롬프트: 입력 $3.80 / 출력 $17.10
입력이 20만 토큰을 넘으면 요청 전체에 장문 컨텍스트 요금이 적용됩니다.
활용 사례
수십만 자 앞 이야기 위에서 장면 이어 가기
설정집과 관계표, 지금까지의 모든 챕터를 보내고 한 턴만 요청하세요. 검색하거나 표본을 뽑지 않았으니 1막에서 한 약속이 3막을 쓰는 동안에도 모델 눈앞에 남아 있습니다.
챕터를 가로지르는 정합성 점검
세계관 규칙과 완성된 챕터를 같은 요청에 넣고 어느 대목이 규칙과 어긋나는지 물어보세요. 돌아오는 건 다시 쓴 원고가 아니라 출처가 달린 충돌 목록입니다. 많이 읽고 짧게 답하는, 이 비율의 홈그라운드입니다.
아주 큰 문서 더미에 판단 하나 내리기
명세서 전체, 한 분기 치 티켓, 메일함 하나를 통째로 한 번의 호출에 넣고 실제로 무엇이 바뀌었는지 물어보세요. 32,768 토큰이면 결론과 근거 인용을 담기에 충분합니다.
캐릭터 상태를 JSON으로 앱에 넘기기
response_format을 json_object로, system 메시지에 키를 하나씩 적어, 각 캐릭터의 현재 위치·부상·관계·알고 있는 비밀을 JSON으로 받으세요. 세이브 데이터가 본문과 어긋나지 않고, 구조용 파서도 필요 없습니다.
프롬프트 가이드 및 실전 팁
규칙은 system, 이야기는 user
세계관 규칙, 원하는 문체, 이번 턴의 길이는 system 메시지에 적으세요. 설정집과 관계표, 기록은 오래된 것부터 한 개의 user 메시지에 모으고 마지막에 이번 턴의 지시를 붙이세요.
매 턴 기록 전체를 다시 보내고 요약하지 마세요
창은 1,000,000 토큰이라 웬만한 완성 장편보다 넓습니다. 매 턴 원문을 다시 보내면 입력 토큰이 들지만, 살 수 있는 가장 싼 일관성입니다. 요약 과정에서 사라지는 것이 없기 때문입니다.
미리 감안할 한계
응답 상한은 32,768 토큰으로 읽기 창의 약 30분의 1입니다. 챕터 전체를 요구하는 요청은 끝맺기 전에 천장에 닿고, 이를 넘는 max_tokens는 곧바로 검증에서 걸립니다. 메시지 내용은 텍스트와 이미지이고 비디오와 오디오 파트는 거절됩니다. 프리뷰 모델이라 Google이 동작을 바꾸거나 내릴 수 있으니, 운영 트래픽을 태우기 전에 물러설 모델을 정해 두세요. JSON response_format은 응답 모양을 잡아 주지만 파싱과 검증은 여전히 애플리케이션 몫입니다.
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.1-pro-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 레퍼런스에서 확인하세요.
