성인 로맨스 시리즈 한 시즌 분량인 30만 토큰짜리 대본 바이블이 있고, 질문이 하나 있다고 해 보겠습니다. 어느 장면이 캐릭터 시트와 모순되는가? SpicyAPI의 Gemini 3.1 Pro Preview는 이를 한 번의 호출로 전부 읽을 수 있지만, 입력 요금은 20만 토큰을 넘으면 두 배가 되고 출력 요금은 50% 오릅니다. 큰 요청은 스트리밍으로 보내서 비스트리밍 타임아웃에 걸리지 않게 하세요.
Gemini 3.1 Pro Preview(google/gemini-3.1-pro-preview/chat)는 최대 입력 1,000,000 토큰을 받고, 텍스트와 image_url 파트를 지원하며(PDF, 영상, 오디오 파트는 안 됩니다), 도구와 JSON 출력을 지원하고, 최대 32,768 토큰으로 응답합니다. 장문 컨텍스트 요금은 입력 합계가 200,000 토큰을 넘는 순간부터 시작되며 요청 전체에 적용됩니다.
한도와 요금
| 설정 | 값 |
|---|---|
| 입력 한도 | 1,000,000 토큰 |
| 출력 | max_tokens 최대 32,768, 기본값 16,384 |
| 추론 강도 | minimal, low, medium(기본값), high |
| 구조화된 출력 | response_format(JSON 객체 모드 포함) |
| 도구 | 함수 정의 최대 128개, 실행은 애플리케이션이 담당, tool_choice는 auto, none, required 또는 이름을 지정한 함수 하나를 받음 |
| 기타 제어 | 온도(기본값 1), top-p, 시드, 정지 시퀀스 최대 4개, parallel_tool_calls는 지원하지 않음 |
요금은 입력 토큰 합계에 따라 달라집니다. 표준 과금 구간과 장문 컨텍스트 과금 구간을 비교해 보세요.
| 입력 토큰 합계 | 캐시되지 않은 입력 / 100만 | 캐시된 입력 / 100만 | 출력 / 100만 |
|---|---|---|---|
| 200,000 이하 | $1.80 | $0.18 | $10.80 |
| 200,000 초과 | $3.60 | $0.36 | $16.20 |
온도는 기본값으로 두세요. Google이 Gemini 3 모델에 권장하는 값이고, 낮추면 모델이 같은 내용을 반복할 수 있습니다. 출력의 형태는 response_format과 시스템 메시지로 잡으세요.
호출 한 번의 실제 비용
비용 = 입력 토큰 × 입력 단가 + 출력 토큰 × 출력 단가이며, 구간은 입력 합계로 정해집니다(캐시된 토큰도 포함). 예시는 캐시되지 않은 입력과 출력 합계 4,000 토큰을 기준으로 합니다.
| 입력 | 계산 | 합계 |
|---|---|---|
| 150,000 | 0.15 x $1.80 + 0.004 x $10.80 | $0.3132 |
| 200,000 | 0.20 x $1.80 + 0.004 x $10.80 | $0.4032 |
| 200,001 | 0.200001 x $3.60 + 0.004 x $16.20 | $0.7848 |
| 250,000 | 0.25 x $3.60 + 0.004 x $16.20 | $0.9648 |
| 600,000 | 0.60 x $3.60 + 0.004 x $16.20 | $2.2248 |
| 1,000,000 | 1.00 x $3.60 + 0.004 x $16.20 | $3.6648 |
추론 토큰은 출력으로 과금되며 max_tokens 예산을 함께 씁니다. 추론 강도를 높일 때는 필요한 눈에 보이는 답변보다 여유를 더 두세요. 4,000 토큰 예산이 4,000 토큰의 보이는 텍스트를 보장하지는 않습니다.
200,000을 1 토큰만 넘어도 호출 비용이 거의 두 배가 되므로, 203,000 토큰 패킷에서 오래된 주고받은 내용 5,000 토큰을 덜어내면 약 50%를 아낄 수 있습니다.
이 금액을 키우는 요인은 세 가지입니다.
- 도구를 쓸 때마다 패킷이 다시 전송됩니다. 250,000 토큰 패킷에서 3라운드 도구 루프를 돌리면 라운드당 입력만 약 $0.90, 합계 $2.70이 들고, 출력은 별도입니다.
- 캐시된 토큰은 더 싸지만 여기서는 제어할 수 없습니다. 캐시 단가(임계값 초과 시 $0.36)는 캐시에서 제공된 입력에 적용됩니다. 예를 들어 캐시 300,000 토큰에 새 토큰 5,000개와 출력 4,000 토큰을 더하면 약 $0.19이고, 캐시가 없으면 $1.16입니다. Gemini 형식의
cachedContent필드는 이 경로에서 거부되므로, 캐시 없이 예산을 잡고 첫 실행 뒤에 확정된 비용을 확인하세요. - 잔액 홀드는
max_tokens전체를 사용합니다. 텍스트 요청이 실행되기 전에, 플랫폼은 입력에max_tokens전체를 더한 금액을 모델 가격으로 홀드합니다. 입력 1,000,000 토큰과 출력 32,768 토큰이면 약 $4.13입니다. 오류 코드를 확인하세요.40201은 홀드에 필요한 잔액이 부족하다는 뜻이고,40202는 지출 한도입니다. 전자는 과도한 출력 예산을 낮추고, 후자는 키와 워크스페이스 한도를 점검하세요. 공개 이미지 URL을 쓰면 홀드가 입력 한도 전체를 덮습니다. 업로드했거나 인라인으로 넣은 이미지는 대신 고정된 이미지 몫을 사용합니다.
첫 호출 뒤에는 X-Spicy-Task-Id 응답 헤더를 읽고 태스크를 조회하세요. settled가 true가 되면 비용이 확정됩니다. 이 값과 스트리밍으로 받은 usage로 이후의 모든 추정치를 보정하세요.
패킷 전체를 넣어야 할까
답이 자료 전체에 걸친 관계에 달려 있다면 패킷 전체를 보내세요. 시즌 전체의 연속성 점검, 전체 사양서를 대상으로 한 "무엇이 바뀌었나" 질문, 대본과 캐릭터 시트 사이의 충돌 탐색이 그런 경우입니다. 질문이 한 장면이나 한 캐릭터에만 해당하면 일부만 보내세요. 18번 장면에서 Mara의 소품에 관한 질문에는 시즌 전체가 아니라 캐릭터 시트와 12번, 18번 장면이 필요합니다.
채팅 앱의 장기 기억 동작은 이 엔드포인트와 다를 수 있습니다. 앱은 선택한 구절을 검색하거나 오래된 대화를 요약할 수 있지만, API는 요청과 함께 보낸 메시지만 봅니다.
입력 창이 크다고 해서 모든 세부 사항을 꺼내 준다는 보장은 없습니다. 흩어진 여러 사실을 찾는 일은 하나를 찾는 것보다 어렵고, 오래된 초안이 현재 버전과 충돌하기도 합니다. 가격 임계값은 정확도의 경계가 아닙니다. 범위를 좁힌 점검에서는 다음을 따르세요.
- 시즌을 최대 150,000 토큰의 아크로 나누고, 각 아크를 같은 캐릭터 시트로 점검하세요.
- Google이 긴 프롬프트에 권장하는 대로, 질문과 출력 규칙은 모든 자료 뒤에 마지막으로 두세요.
- 모든 청크에 라벨(
SCRIPT_V3 / scene 12)을 붙이고, 답변이 제공된 라벨만 인용하도록 요구하세요. 그런 다음 인용된 라벨이 패킷에 실제로 있는지 확인하세요. - 다시 쓰기가 아니라 충돌과 위치를 요청하세요. 32,768 토큰짜리 응답에는 어차피 다시 쓴 시즌 전체가 들어가지 않습니다.
- 대체된 이전 초안은 빼세요. 한 패킷에 12번 장면의 두 버전이 있으면 옛 소품이 현행으로 인용됩니다.
같은 예산 논리를 다른 요금으로 풀어 낸 글이 Claude Sonnet 4.6 비용 가이드와 Claude Opus 장문 문서 가이드입니다.
텍스트 패킷 준비하기
이 경로는 텍스트와 image_url 파트를 받습니다. 스캔한 대본으로 연속성을 점검한다면 OCR로 검색 가능한 텍스트와 안정적인 장면 라벨을 얻을 수 있습니다. 패킷을 만들기 전에 손상된 이름과 장면 번호를 바로잡으세요. 텍스트 메시지에 붙여 넣은 PDF URL은 문서로 읽히지 않습니다. 대본, 캐릭터 노트, 샷 리스트를 안정적인 라벨이 붙은 텍스트로 내보내세요.
CHARACTERS_V2
Mara: 32, photographer. Keeps a copper thermos with a blue band.
Jon: 35, composer. Owns the red leather case.
SCRIPT_V3 / scene 12
Mara puts the thermos on the railway bench. Jon carries the case.
SCRIPT_V3 / scene 18
Jon offers Mara the thermos.토큰당 영문 4글자는 대략적인 사전 선별용 추정치일 뿐, 경계선에서 요청 가격을 계산하는 방법이 아닙니다. 코드, 이름, 영어가 아닌 텍스트는 토큰화되는 방식이 다릅니다. 200,000 아래로 넉넉한 여유를 남기고, 시스템 프롬프트와 도구 정의도 추정에 포함하며, 반환된 usage로 실제 개수를 대조하세요.
발견한 내용을 장면 수정으로 바꾸기
이 패킷에서 12번 장면은 보온병이 마지막으로 Mara에게 있다고 하는데, 18번 장면에서는 전달 과정 없이 Jon의 손에 들어가 있습니다. 쓸 만한 답변은 이 공백을 짚고 선택지를 제시합니다.
- 18번 장면 전에 Jon이 직접 챙기는 모습을 보여 준다. 그 비트에서 세심함을 보여 주려는 경우입니다.
- Mara가 직접 챙기게 한다. 두 사람 사이의 거리를 유지하려는 경우입니다.
관계의 비트를 고른 다음, 그것을 구현하는 대사를 한 줄 요청하세요. 모델의 보고는 공백을 찾는 데 도움이 되지만, 그 행동이 무엇을 뜻하는지는 여전히 작가가 정합니다. 점검 과정에서 중간 장면을 지어내 원본 자료처럼 인용해서는 안 됩니다. 시리즈 바이블이라면 같은 방식으로, 대본이 보여 주기도 전에 화해를 전제로 한 장면을 찾아낼 수 있습니다. 마지막으로 확립된 관계 상태, 처음으로 모순되는 장면, 빠진 전환을 물어보세요.
먼저 Playground에서 시도하기
- Gemini 3.1 Pro Preview를 열고 Playground로 전환합니다.
- CHARACTERSV2와 SCRIPTV3의 두 장면을 붙여 넣습니다. 전달 장면이 나오지 않은 채 보온병의 주인이 바뀌는 곳이 어디인지 물어보세요.
- Jon과 Mara 중 누가 챙길지 고른 다음, 그 비트를 만들어 주는 대사를 한 줄 요청하세요.
스트리밍으로 보내기
SPICY_API_KEY를 설정하고 같은 장면 패킷을 앱에서 보내세요. 스트리밍을 쓰면 비스트리밍 요청이 엣지에서 약 100초 만에 끊기는 문제를 피할 수 있습니다. 구현 세부 사항은 채팅 가이드에 있습니다.
INTENT_KEY=$(uuidgen)
curl --fail-with-body -sN --max-time 600 https://api.spicyapi.ai/v1/chat/completions \
-H "Authorization: Bearer $SPICY_API_KEY" \
-H 'Content-Type: application/json' \
-H "Idempotency-Key: $INTENT_KEY" \
-D reply.headers -o reply.sse \
-d '{
"model": "google/gemini-3.1-pro-preview/chat",
"stream": true,
"stream_options": {"include_usage": true},
"reasoning_effort": "low",
"max_tokens": 4000,
"response_format": {"type": "json_object"},
"messages": [
{"role": "system", "content": "Return JSON with conflicts and suggested_fixes arrays. Cite only supplied scene labels. Do not invent missing scenes."},
{"role": "user", "content": "Fictional adults: Mara, 32, and Jon, 35. SCRIPT_V3 / scene 12: Mara leaves her blue-banded copper thermos on the railway bench. Jon carries his red case. SCRIPT_V3 / scene 18: Jon hands Mara the thermos. Identify any missing prop handoff."}
]
}'패킷 밖의 정보일 때만 도구를 추가하기
기준이 되는 레코드가 자주 바뀐다면 캐릭터 조회는 프롬프트 밖에 두세요. get_character 같은 읽기 전용의 좁은 함수를 모델에 주고, 애플리케이션이 그 레코드를 반환하게 하세요. 턴 수에는 상한을 두세요. 같은 큰 패킷으로 4라운드를 돌리면 입력을 네 번 읽는 비용이 들 수 있습니다. 두 장면을 고정해 점검하는 경우라면, 사실을 프롬프트에 넣는 쪽이 더 간단하고 저렴합니다.
Google의 네이티브 Search 및 Maps 그라운딩은 별도의 통합입니다. 이 채팅 경로는 애플리케이션이 실행하는 함수를 사용합니다. 도구 루프 전체는 채팅 레시피에서 볼 수 있습니다.
Agent에게 호출 준비를 맡기기
연속성 점검을 반복한다면 코딩 Agent에게 SpicyAPI Skill을 쓰라고 요청하세요. "google/gemini-3.1-pro-preview/chat을 읽고, 예제를 내 입력에 맞게 고쳐 줘. 실행하기 전에 요청을 보여 줘." CLI로 조회하려면 spicyapi models get google/gemini-3.1-pro-preview/chat --json을, MCP로 조회하려면 model: "google/gemini-3.1-pro-preview/chat"을 지정한 spicyapi_model_get을 쓰면 됩니다. 채팅 호출에는 호환 클라이언트나 채팅 API를 사용합니다. 미디어 태스크 명령은 채팅 응답을 생성하지 않습니다.
성인 콘텐츠 프로젝트
대본 색인, 연속성 점검, 제작 노트에는 잘 맞습니다. 노골적인 글쓰기는 덜 안정적입니다. SpicyAPI는 이 경로에 콘텐츠 필터를 추가하지 않지만, 모델이 요청을 거절하거나 표현을 누그러뜨릴 수 있습니다. 2026년 9월 테스트에서 글로 쓴 L3 수준 묘사가 끝까지 완성된 것은 3건 중 1건이었고, 친밀한 장면 작성은 9건 중 4건이었습니다. 친밀한 장면 테스트에서는 요청 안에 허구라는 틀을 둔 경우 3건 중 3건이 완성되었고, 시스템 프롬프트만으로는 3건 중 1건, 직접 요청은 3건 중 0건이었습니다. 허구 요청은 시스템 메시지에만 기대는 것보다 이 워크플로의 출발점으로 더 낫지만, 믿을 수 있는 노골적인 글쓰기가 핵심 결과물이라면 다른 모델을 고르세요. 자세한 내용은 Gemini 3.1 Pro 리뷰에 있습니다.
자주 생기는 문제
| 증상 | 해결 방법 |
|---|---|
| PDF, 영상, 오디오 파트가 거부됨 | 이 경로는 텍스트와 image_url 파트만 받습니다. 텍스트 패킷 워크플로에서는 PDF 텍스트를 추출하거나 스캔한 페이지를 OCR로 처리하세요 |
| 큰 호출에서 524 오류나 연결 끊김 | 스트리밍을 사용하세요. 다시 시도하기 전에 원래 태스크와 정산 상태를 확인하세요 |
| 잔액이 충분한데 402 | 40201: 과도한 출력 예산을 낮추거나 홀드 금액을 충전하세요. 40202: 키와 워크스페이스의 지출 한도를 점검하세요 |
| 도구 결과가 무시됨 | 어시스턴트의 도구 호출 메시지를 유지하고 tool_call_id를 맞추세요 |
| 지어낸 장면 참조 | 제공된 라벨을 요구한 뒤, 인용된 각 라벨을 검증하세요 |
| JSON이 잘림 | 추론에 쓸 여유를 두고 max_tokens를 올리거나, 추론 강도를 낮추거나, 요청하는 충돌 수를 줄이세요 |
| 청구액이 예상보다 높음 | 입력 합계가 200,000을 넘었거나, 도구 라운드에서 패킷이 다시 전송되었습니다 |
| 옛 소품이 현행으로 인용됨 | 대체된 초안을 패킷에서 빼세요 |
현재 요금과 Playground에서의 경로 시험은 모델 페이지에서 할 수 있습니다. 프리뷰 모델이므로, 프로덕션 트래픽을 맡기기 전에 변경될 경우 어떤 모델이 대신할지 정해 두세요.
