Gemini 4 Argon API: Python 스트리밍과 대화 기록 관리

Gemini 4 Argon API 대화는 contents, 역할, parts로 구성된 네이티브 Gemini 콘텐츠를 사용합니다. 첫 요청은 간단합니다. 더 어려운 부분은 후속 질문을 보내기 전에 응답을 올바르게 보존하는 것입니다. 화면에 표시된 텍스트만으로 모델 턴을 재구성하면 서명된 콘텐츠가 사라질 수 있습니다. 빈 로딩 메시지를 기록에 추가하면 다음 요청이 유효하지 않게 될 수도 있습니다.

이 튜토리얼은 Python 표준 라이브러리와 SeedRouter의 네이티브 엔드포인트를 사용하며, 텍스트 채팅과 스트리밍을 다룹니다. 전체 매개변수 규격은 API 참조 문서에서 확인할 수 있습니다. 여기서는 하나의 요청을 실제로 사용할 수 있는 대화로 확장하는 과정을 설명합니다.

첫 요청을 보내기 전에

Python 3, SeedRouter API 키, 충분한 계정 잔액이 필요합니다. 키는 SEEDROUTER_API_KEY라는 환경 변수에 보관하고, 소스 코드나 브라우저에 전달되는 번들에 넣지 마세요. 제출하는 메시지마다 요금이 발생할 수 있습니다. 이 예제는 요청을 자동으로 재시도하거나 이어서 생성 요청을 호출하지 않습니다.

모델 ID는 gemini-4-argon이며 엔드포인트 경로에 지정합니다. Google의 네이티브 생성 가이드에서 이 형식을 설명합니다. SeedRouter는 아래와 같이 Bearer 인증을 사용합니다.

Gemini 4 Argon API 요청 하나 보내기

curl --no-buffer --fail-with-body \
  'https://api.seedrouter.ai/v1beta/models/gemini-4-argon:streamGenerateContent?alt=sse' \
  -H "Authorization: Bearer $SEEDROUTER_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"contents":[{"role":"user","parts":[{"text":"Explain a mutex in one sentence."}]}],"generationConfig":{"maxOutputTokens":1024,"thinkingConfig":{"thinkingLevel":"low"}}}'

응답은 하나의 JSON 문서가 아니라 서버 전송 이벤트의 연속입니다. 각 data: 이벤트에는 네이티브 Gemini JSON이 들어 있습니다. 표시할 텍스트는 candidates[].content.parts[].text에 있으며, 일부 파트에는 텍스트 대신 사고 내용이나 서명이 들어 있습니다. usageMetadata는 텍스트와 별도로 도착할 수 있으므로, 답변이 완료되었다고 판단하기 전에 마지막 이벤트까지 읽어야 합니다.

여기서는 기본 동작 확인을 위해 출력 예산을 의도적으로 작게 설정했습니다. 사고도 예산을 사용하므로 응답이 미완성일 수 있습니다. 더 어려운 작업에서는 필요에 따라 예산을 늘리세요. 미완성 답변을 사용자가 알 수 없는 재시도 루프로 연결하지 마세요.

Python으로 두 턴의 대화 실행하기

전체 Python 예제를 내려받아 로컬에 저장한 후 실행합니다.

python3 gemini-4-argon-chat.py

먼저 “Explain a mutex in one sentence”라고 묻고, 다음으로 “Give a Python example of that idea”라고 물어보세요. 스크립트는 각 요청 전에 입력을 기다립니다. 빈 줄을 입력하면 종료됩니다. 핵심 기록 규칙은 다음과 같습니다.

user = {"role": "user", "parts": [{"text": text}]}
body = {"contents": [*history, user]}
history = [*history, user, {"role": "model", "parts": parts}]

다운로드할 수 있는 스크립트에는 생성 설정도 포함되어 있습니다. SSE 프레임을 파싱하고 사고가 아닌 텍스트만 출력하며, 종료 사유가 STOP이고 parts가 비어 있지 않을 때만 기록을 확정합니다. API 오류, 스트림 중단, 빈 답변이 발생하면 이전 기록이 그대로 유지됩니다. 메시지를 알리지 않고 다시 제출하지도 않습니다.

위의 짧은 코드는 데이터 형태를 설명하기 위한 것입니다. 완전한 요청 처리를 사용하려면 전체 파일을 실행하세요. 비스트리밍 응답에 해당하는 작업은 generateContent이며, 참조 예제에는 cURL, Python, Node.js, Go 사용법이 나와 있습니다.

로딩 표시가 아니라 네이티브 parts 보존하기

두 번째 요청에는 실제 턴 세 개가 들어가야 합니다. 첫 사용자 메시지, 완료된 모델 응답, 두 번째 사용자 메시지입니다. UI의 “생각 중…” 자리표시자는 또 다른 모델 턴이 아닙니다.

contents.3.parts: Too small: expected array to have >=1 items와 같은 오류는 네 번째 콘텐츠 항목의 parts 배열이 비어 있다는 뜻입니다. 인덱스는 0부터 시작합니다. 프롬프트나 모델을 바꾸기 전에 기록을 어떻게 구성하는지 확인하세요. 로딩 표시는 화면 상태에 속하며, 요청에서 { "role": "model", "parts": [] }가 되어서는 안 됩니다.

반환된 모든 파트를 순서대로 보존하세요. thoughtSignature와 사고로 표시된 파트도 포함하며, 화면에서 숨기더라도 마찬가지입니다. Google의 사고 서명 가이드는 이러한 불투명 필드를 이후 턴에도 유지해야 하는 이유를 설명합니다. 서명을 수정하거나 만들어 내거나 재구성하지 마세요. 네이티브 기록은 인터페이스에 표시하는 텍스트와 별도로 저장해야 합니다.

도구를 사용하는 대화에도 같은 보존 원칙이 적용됩니다. 다만 도구를 실행하고 결과를 반환하려면 더 큰 애플리케이션 루프가 필요합니다. 이 텍스트 예제는 해당 루프를 구현하지 않으며, 완전한 코딩 에이전트로 소개해서는 안 됩니다.

사용량 읽기와 중단 처리

원시 요청에서는 스트림이 마지막으로 보고한 사용량 값을 보존하세요. 같은 요청 내에서 반복되는 누적 스냅샷을 합산하지 마세요. 일반 입력은 promptTokenCount에서 cachedContentTokenCount를 뺀 값입니다. 과금되는 출력에는 candidatesTokenCount와 thoughtsTokenCount가 모두 포함됩니다. 요금 가이드는 이 수치를 예산으로 환산하는 방법을 설명합니다.

Ctrl+C는 예제를 중단하고 추가 요청을 보내지 않습니다. 로컬에서 읽기를 중단했다고 해서 원격 생성이 토큰을 사용하지 않았다는 뜻은 아닙니다. 사용량이 도착하기 전에 스트림이 끝나면 계정의 사용량 기록을 확인하세요. 예제는 보수적으로 미완성 턴을 이후 기록에서 제외합니다. 부분 답변을 보존할지는 별도의 애플리케이션 설계 판단입니다.

긴 출력의 이어서 생성은 또 다른 경우입니다. 종료 사유 CONTINUATION은 이어서 생성 토큰을 사용해 원래 생성을 재개하며, 새 사용자 메시지가 아닙니다. Google은 원래 요청과 최신 토큰을 사용하고, 부분 출력을 contents에 덧붙이지 않도록 요구합니다. 긴 출력의 이어서 생성 가이드를 참고하세요. 이 입문용 스크립트는 자동으로 이어서 생성하지 않고 중단합니다.

Gemini 4 Argon API: Python으로 네이티브 스트리밍 대화 구현하기

첫 요청을 보내기 전에

Gemini 4 Argon API 요청 하나 보내기

Python으로 두 턴의 대화 실행하기

로딩 표시가 아니라 네이티브 parts 보존하기

사용량 읽기와 중단 처리

무엇이 검증되었나요?

API 관련 질문

OpenAI 모델 이름만 `gemini-4-argon`으로 바꾸면 되나요?

토큰을 사용했는데도 답변이 비어 있는 이유는 무엇인가요?

100만 토큰 컨텍스트는 100만 출력 토큰을 뜻하나요?

대화가 작동한 뒤 기능 추가하기

관련 가이드

Kling 4.0 API 사용 방법: 모드, 키프레임, 레퍼런스, 편집 및 연장

DeepSeek Search API: 가격과 Python 검색 후 Fetch 호출 예제

Whisper-1 API: 첫 오디오 전사