Google Gemini 채팅 형식 (Generate Content)¶

공식 문서

📝 소개¶

Google Gemini API는 이미지, 오디오, 코드, 도구 등 다양한 입력을 활용해 콘텐츠를 생성할 수 있습니다. GenerateContentRequest를 전달하면 모델 응답이 생성됩니다. 텍스트 생성, 시각 이해, 오디오 처리, 긴 컨텍스트, 코드 실행, JSON 스키마, 함수 호출 등 다양한 기능을 지원합니다.

🤖 지원 모델¶

현재 지원되는 모델:

모델	설명
gemini-1.5-pro	Gemini 1.5 Pro 채팅 모델
gemini-1.5-flash	Gemini 1.5 Flash 채팅 모델
gemini-1.5-flash-8b	Gemini 1.5 Flash 8B 채팅 모델
gemini-1.5-pro-latest	Gemini 1.5 Pro 채팅 모델 (최신 버전)
gemini-1.5-flash-latest	Gemini 1.5 Flash 채팅 모델 (최신 버전)
gemini-2.0-flash	Gemini 2.0 Flash 채팅 모델
gemini-2.0-flash-lite-preview	Gemini 2.0 Flash Lite 채팅 모델 (프리뷰)
gemini-2.0-flash-exp	Gemini 2.0 Flash 채팅 모델 (실험 버전)
gemini-2.0-pro-exp	Gemini 2.0 Pro 채팅 모델 (실험 버전)
gemini-2.0-flash-thinking-exp	Gemini 2.0 Flash Thinking 채팅 모델 (실험 버전)
gemini-2.5-flash	Gemini 2.5 Flash 채팅 모델
gemini-2.5-pro	Gemini 2.5 Pro 채팅 모델
gemini-3-pro-preview	Gemini 3 Pro 채팅 모델 (프리뷰)
gemini-3-flash-preview	Gemini 3 Flash 채팅 모델 (프리뷰)

💡 요청 예시¶

기본 텍스트 대화 ✅¶

curl "https://ssanai-workspace.atto-lab.cc/v1beta/models/gemini-3-pro-preview:generateContent?key=$API_KEY" \
    -H 'Content-Type: application/json' \
    -X POST \
    -d '{
      "contents": [{
        "parts":[{"text": "Write a story about a magic backpack."}]
        }]
       }'

이미지 분석 대화 ✅¶

# base64 인코딩된 이미지 데이터를 임시 파일에 저장
TEMP_B64=$(mktemp)
trap 'rm -f "$TEMP_B64"' EXIT
base64 $B64FLAGS $IMG_PATH > "$TEMP_B64"

# JSON 페이로드를 임시 파일에 저장
TEMP_JSON=$(mktemp)
trap 'rm -f "$TEMP_JSON"' EXIT

cat > "$TEMP_JSON" << EOF
{
  "contents": [{
    "parts":[
      {"text": "Tell me about this instrument"},
      {
        "inline_data": {
          "mime_type":"image/jpeg",
          "data": "$(cat "$TEMP_B64")"
        }
      }
    ]
  }]
}
EOF

curl "https://ssanai-workspace.atto-lab.cc/v1beta/models/gemini-3-pro-preview:generateContent?key=$API_KEY" \
    -H 'Content-Type: application/json' \
    -X POST \
    -d "@$TEMP_JSON"

함수 호출 ✅¶

cat > tools.json << EOF
{
  "function_declarations": [
    {
      "name": "enable_lights",
      "description": "Turn on the lighting system."
    },
    {
      "name": "set_light_color",
      "description": "Set the light color. Lights must be enabled for this to work.",
      "parameters": {
        "type": "object",
        "properties": {
          "rgb_hex": {
            "type": "string",
            "description": "The light color as a 6-digit hex string, e.g. ff0000 for red."
          }
        },
        "required": [
          "rgb_hex"
        ]
      }
    },
    {
      "name": "stop_lights",
      "description": "Turn off the lighting system."
    }
  ]
} 
EOF

curl "https://ssanai-workspace.atto-lab.cc/v1beta/models/gemini-3-pro-preview:generateContent?key=$API_KEY" \
  -H 'Content-Type: application/json' \
  -d @<(echo '
  {
    "system_instruction": {
      "parts": {
        "text": "You are a helpful lighting system bot. You can turn lights on and off, and you can set the color. Do not perform any other tasks."
      }
    },
    "tools": ['$(cat tools.json)'],

    "tool_config": {
      "function_calling_config": {"mode": "auto"}
    },

    "contents": {
      "role": "user",
      "parts": {
        "text": "Turn on the lights please."
      }
    }
  }
')

JSON 스키마 응답 ✅¶

curl "https://ssanai-workspace.atto-lab.cc/v1beta/models/gemini-3-pro-preview:generateContent?key=$API_KEY" \
-H 'Content-Type: application/json' \
-d '{
    "contents": [{
      "parts":[
        {"text": "List 5 popular cookie recipes"}
        ]
    }],
    "generationConfig": {
        "response_mime_type": "application/json",
        "response_schema": {
          "type": "ARRAY",
          "items": {
            "type": "OBJECT",
            "properties": {
              "recipe_name": {"type":"STRING"},
            }
          }
        }
    }
}'

오디오 처리 🟡¶

파일 업로드 제한

inline_data를 통한 base64 오디오 업로드만 지원하며, file_data.file_uri 또는 File API는 지원하지 않습니다.

# File API 업로드는 지원하지 않음
# base64 inline_data를 사용해 API 요청에 오디오 업로드
if [[ "$(base64 --version 2>&1)" = *"FreeBSD"* ]]; then
  B64FLAGS="--input"
else
  B64FLAGS="-w0"
fi
AUDIO_B64=$(base64 $B64FLAGS "$AUDIO_PATH")

curl "https://ssanai-workspace.atto-lab.cc/v1beta/models/gemini-3-pro-preview:generateContent?key=$API_KEY" \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{
    "contents": [{
      "parts": [
        {"text": "Please describe this audio file."},
        {"inline_data": {"mime_type": "audio/mpeg", "data": "'$AUDIO_B64'"}}
      ]
    }]
  }'

비디오 처리 🟡¶

파일 업로드 제한

inline_data를 통한 base64 비디오 업로드만 지원하며, file_data.file_uri 또는 File API는 지원하지 않습니다.

# File API 업로드는 지원하지 않음
# base64 inline_data를 사용해 API 요청에 비디오 업로드
if [[ "$(base64 --version 2>&1)" = *"FreeBSD"* ]]; then
  B64FLAGS="--input"
else
  B64FLAGS="-w0"
fi
VIDEO_B64=$(base64 $B64FLAGS "$VIDEO_PATH")

curl "https://ssanai-workspace.atto-lab.cc/v1beta/models/gemini-3-pro-preview:generateContent?key=$API_KEY" \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{
    "contents": [{
      "parts": [
        {"text": "Transcribe the audio from this video and provide visual descriptions."},
        {"inline_data": {"mime_type": "video/mp4", "data": "'$VIDEO_B64'"}}
      ]
    }]
  }'

PDF 처리 🟡¶

파일 업로드 제한

inline_data를 통한 base64 PDF 업로드만 지원하며, file_data.file_uri 또는 File API는 지원하지 않습니다.

MIME_TYPE=$(file -b --mime-type "${PDF_PATH}")
# base64 inline_data를 사용해 API 요청에 PDF 업로드
if [[ "$(base64 --version 2>&1)" = *"FreeBSD"* ]]; then
  B64FLAGS="--input"
else
  B64FLAGS="-w0"
fi
PDF_B64=$(base64 $B64FLAGS "$PDF_PATH")

echo $MIME_TYPE

curl "https://ssanai-workspace.atto-lab.cc/v1beta/models/gemini-3-pro-preview:generateContent?key=$API_KEY" \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{
    "contents": [{
      "parts": [
        {"text": "Can you add a few more lines to this poem?"},
        {"inline_data": {"mime_type": "application/pdf", "data": "'$PDF_B64'"}}
      ]
    }]
  }'

채팅 대화 ✅¶

curl https://ssanai-workspace.atto-lab.cc/v1beta/models/gemini-3-pro-preview:generateContent?key=$API_KEY \
    -H 'Content-Type: application/json' \
    -X POST \
    -d '{
      "contents": [
        {"role":"user",
         "parts":[{
           "text": "Hello"}]},
        {"role": "model",
         "parts":[{
           "text": "Great to meet you. What would you like to know?"}]},
        {"role":"user",
         "parts":[{
           "text": "I have two dogs in my house. How many paws are in my house?"}]},
      ]
    }'

스트리밍 응답 ✅¶

curl "https://ssanai-workspace.atto-lab.cc/v1beta/models/gemini-3-pro-preview:streamGenerateContent?alt=sse&key=$API_KEY" \
    -H 'Content-Type: application/json' \
    --no-buffer \
    -d '{
      "contents": [{
        "parts": [{"text": "마법의 배낭에 대한 이야기를 써줘"}]
      }]
    }'

코드 실행 ✅¶

curl "https://ssanai-workspace.atto-lab.cc/v1beta/models/gemini-3-pro-preview:generateContent?key=$API_KEY" \
    -H 'Content-Type: application/json' \
    -X POST \
    -d '{
      "contents": [{
        "parts": [{"text": "피보나치 수열의 10번째 항을 계산해줘"}]
      }],
      "tools": [{
        "codeExecution": {}
      }]
    }'

생성 설정 ✅¶

curl https://ssanai-workspace.atto-lab.cc/v1beta/models/gemini-3-pro-preview:generateContent?key=$API_KEY \
    -H 'Content-Type: application/json' \
    -X POST \
    -d '{
        "contents": [{
            "parts":[
                {"text": "Explain how AI works"}
            ]
        }],
        "generationConfig": {
            "stopSequences": [
                "Title"
            ],
            "temperature": 1.0,
            "maxOutputTokens": 800,
            "topP": 0.8,
            "topK": 10
        }
    }'

안전 설정 ✅¶

echo '{
    "safetySettings": [
        {"category": "HARM_CATEGORY_HARASSMENT", "threshold": "BLOCK_ONLY_HIGH"},
        {"category": "HARM_CATEGORY_HATE_SPEECH", "threshold": "BLOCK_MEDIUM_AND_ABOVE"}
    ],
    "contents": [{
        "parts":[{
            "text": "'I support Martians Soccer Club and I think Jupiterians Football Club sucks! Write a ironic phrase about them.'"}]}]}' > request.json

curl "https://ssanai-workspace.atto-lab.cc/v1beta/models/gemini-3-pro-preview:generateContent?key=$API_KEY" \
    -H 'Content-Type: application/json' \
    -X POST \
    -d @request.json

시스템 지침 ✅¶

curl "https://ssanai-workspace.atto-lab.cc/v1beta/models/gemini-3-pro-preview:generateContent?key=$API_KEY" \
-H 'Content-Type: application/json' \
-d '{ "system_instruction": {
    "parts":
      { "text": "You are a cat. Your name is Neko."}},
    "contents": {
      "parts": {
        "text": "Hello there"}}}'

📮 요청¶

엔드포인트¶

콘텐츠 생성 (Generate Content)¶

POST https://ssanai-workspace.atto-lab.cc/v1beta/{model=models/*}:generateContent

스트림 콘텐츠 생성 (Stream Generate Content)¶

POST https://ssanai-workspace.atto-lab.cc/v1beta/{model=models/*}:streamGenerateContent

인증 방법¶

요청 URL에 API 키를 포함하세요:

?key=$API_KEY

$API_KEY는 발급받은 Google AI API 키입니다.

경로 파라미터¶

`model`¶

유형: string
필수: yes

완성을 생성할 대상 모델 이름입니다.

형식: models/{model} (예: models/gemini-3-pro-preview)

요청 본문 파라미터¶

`contents`¶

유형: array
필수: yes

모델과의 현재 대화 콘텐츠입니다. 단일 요청에서는 하나의 항목만 전달하며, 채팅형 다중 턴 요청에서는 대화 이력과 최신 요청을 포함한 반복 필드로 전달합니다.

Content 객체 속성:

속성	유형	필수	설명
`parts`	array	yes	하나의 메시지를 구성하는 순서화된 콘텐츠 파트
`role`	string	no	대화에서 콘텐츠를 생성한 주체. `user`, `model`, `function`, `tool`

Part 객체 속성:

속성	유형	필수	설명
`text`	string	no	순수 텍스트 콘텐츠
`inlineData`	object	no	인라인 미디어 바이트 데이터
`fileData`	object	no	업로드된 파일의 URI 참조
`functionCall`	object	no	함수 호출 요청
`functionResponse`	object	no	함수 호출 응답
`executableCode`	object	no	실행 가능한 코드
`codeExecutionResult`	object	no	코드 실행 결과

InlineData 객체 속성:

속성	유형	필수	설명
`mimeType`	string	yes	미디어 MIME 타입
`data`	string	yes	Base64 인코딩된 미디어 데이터

FileData 객체 속성:

속성	유형	필수	설명
`mimeType`	string	yes	파일 MIME 타입
`fileUri`	string	yes	파일 URI

`tools`¶

유형: array
필수: no

모델이 다음 응답을 생성할 때 사용할 수 있는 도구 목록입니다. 함수 호출과 코드 실행 도구를 지원합니다.

Tool 객체 속성:

속성	유형	필수	설명
`functionDeclarations`	array	no	함수 선언 목록(선택)
`codeExecution`	object	no	모델 코드 실행 활성화

FunctionDeclaration 객체 속성:

속성	유형	필수	설명
`name`	string	yes	함수 이름
`description`	string	no	함수 설명
`parameters`	object	no	함수 파라미터(JSON Schema 형식)

FunctionCall 객체 속성:

속성	유형	필수	설명
`name`	string	yes	호출할 함수 이름
`args`	object	no	함수 인자의 키-값 쌍

FunctionResponse 객체 속성:

속성	유형	필수	설명
`name`	string	yes	호출된 함수 이름
`response`	object	yes	함수 호출 응답 데이터

ExecutableCode 객체 속성:

속성	유형	필수	설명
`language`	enum	yes	코드의 프로그래밍 언어
`code`	string	yes	실행할 코드

CodeExecutionResult 객체 속성:

속성	유형	필수	설명
`outcome`	enum	yes	코드 실행 결과 상태
`output`	string	no	코드 실행 출력 내용

CodeExecution 객체 속성:

속성	유형	필수	설명
{}	빈 객체	-	코드 실행을 활성화하는 빈 설정 객체

`toolConfig`¶

유형: object
필수: no

요청에 포함된 도구에 대한 설정입니다.

ToolConfig 객체 속성:

속성	유형	필수	설명
`functionCallingConfig`	object	no	함수 호출 설정

FunctionCallingConfig 객체 속성:

속성	유형	필수	설명
`mode`	enum	no	함수 호출 모드 지정
`allowedFunctionNames`	array	no	호출 허용 함수 이름 목록

FunctionCallingMode enum 값:

MODE_UNSPECIFIED: 기본 모드, 함수 호출 여부를 모델이 결정
AUTO: 함수 호출 시점을 모델이 자동 결정
ANY: 모델이 반드시 함수를 호출
NONE: 모델이 함수를 호출하지 않음

`safetySettings`¶

유형: array
필수: no

유해 콘텐츠를 필터링하기 위한 SafetySetting 목록입니다.

SafetySetting 객체 속성:

속성	유형	필수	설명
`category`	enum	yes	안전 카테고리
`threshold`	enum	yes	차단 임계값

HarmCategory enum 값:

HARM_CATEGORY_HARASSMENT: 괴롭힘 콘텐츠
HARM_CATEGORY_HATE_SPEECH: 혐오 발언/콘텐츠
HARM_CATEGORY_SEXUALLY_EXPLICIT: 노골적인 성적 콘텐츠
HARM_CATEGORY_DANGEROUS_CONTENT: 위험 콘텐츠
HARM_CATEGORY_CIVIC_INTEGRITY: 시민적 신뢰를 훼손할 수 있는 콘텐츠

HarmBlockThreshold enum 값:

BLOCK_LOW_AND_ABOVE: NEGLIGIBLE 점수만 허용
BLOCK_MEDIUM_AND_ABOVE: NEGLIGIBLE, LOW 점수 허용
BLOCK_ONLY_HIGH: NEGLIGIBLE, LOW, MEDIUM 위험 수준 허용
BLOCK_NONE: 모든 콘텐츠 허용
OFF: 안전 필터 비활성화

전체 HarmBlockThreshold enum 값:

HARM_BLOCK_THRESHOLD_UNSPECIFIED: 임계값 미지정
BLOCK_LOW_AND_ABOVE: 중간 이상 확률의 유해 콘텐츠를 차단, NEGLIGIBLE만 허용
BLOCK_MEDIUM_AND_ABOVE: 중간 이상 확률의 유해 콘텐츠를 차단, NEGLIGIBLE/LOW 허용
BLOCK_ONLY_HIGH: 높은 확률 유해 콘텐츠만 차단, NEGLIGIBLE/LOW/MEDIUM 허용
BLOCK_NONE: 콘텐츠 차단 없음
OFF: 안전 필터 완전 비활성화

`systemInstruction`¶

유형: object (Content)
필수: no

개발자가 지정하는 시스템 지침입니다. 현재 텍스트만 지원합니다.

`generationConfig`¶

유형: object
필수: no

모델 생성 및 출력 관련 설정 옵션입니다.

GenerationConfig 객체 속성:

속성	유형	필수	설명
`stopSequences`	array	no	생성을 중지할 문자열 시퀀스 집합(최대 5개)
`responseMimeType`	string	no	생성 후보 텍스트의 MIME 타입
`responseSchema`	object	no	생성 후보 텍스트의 출력 스키마
`responseModalities`	array	no	요청한 응답 모달리티
`candidateCount`	integer	no	반환할 생성 답변 수
`maxOutputTokens`	integer	no	생성 답변의 최대 토큰 수
`temperature`	number	no	출력 무작위성 제어, 범위 [0.0, 2.0]
`topP`	number	no	샘플링 시 고려할 토큰 누적 확률 상한
`topK`	integer	no	샘플링 시 고려할 최대 토큰 수
`seed`	integer	no	디코딩에 사용할 시드
`presencePenalty`	number	no	존재 페널티
`frequencyPenalty`	number	no	빈도 페널티
`responseLogprobs`	boolean	no	응답에 logprobs 결과 포함 여부
`logprobs`	integer	no	반환할 상위 logprobs 개수
`enableEnhancedCivicAnswers`	boolean	no	강화된 공공 정보 답변 기능 활성화
`speechConfig`	object	no	음성 생성 설정
`thinkingConfig`	object	no	추론 기능 설정
`mediaResolution`	enum	no	미디어 해상도 지정

지원 MIME 타입:

text/plain: (기본값) 텍스트 출력
application/json: JSON 응답
text/x.enum: ENUM 문자열 응답

Modality enum 값:

TEXT: 모델이 텍스트를 반환
IMAGE: 모델이 이미지를 반환
AUDIO: 모델이 오디오를 반환

Schema 객체 속성:

속성	유형	필수	설명
`type`	enum	yes	데이터 타입
`description`	string	no	필드 설명
`enum`	array	no	enum 값 목록(type이 string일 때)
`example`	any	no	예시 값
`nullable`	boolean	no	null 허용 여부
`format`	string	no	문자열 형식(예: date, date-time)
`items`	object	no	배열 아이템 스키마(type이 array일 때)
`properties`	object	no	객체 속성 스키마(type이 object일 때)
`required`	array	no	필수 속성 이름 목록
`minimum`	number	no	숫자 최소값
`maximum`	number	no	숫자 최대값
`minItems`	integer	no	배열 최소 길이
`maxItems`	integer	no	배열 최대 길이
`minLength`	integer	no	문자열 최소 길이
`maxLength`	integer	no	문자열 최대 길이

Type enum 값:

TYPE_UNSPECIFIED: 타입 미지정
STRING: 문자열 타입
NUMBER: 숫자 타입
INTEGER: 정수 타입
BOOLEAN: 불리언 타입
ARRAY: 배열 타입
OBJECT: 객체 타입

지원 프로그래밍 언어 (ExecutableCode):

LANGUAGE_UNSPECIFIED: 언어 미지정
PYTHON: Python 프로그래밍 언어

코드 실행 결과 enum (Outcome):

OUTCOME_UNSPECIFIED: 결과 미지정
OUTCOME_OK: 코드 실행 성공
OUTCOME_FAILED: 코드 실행 실패
OUTCOME_DEADLINE_EXCEEDED: 코드 실행 시간 초과

`cachedContent`¶

유형: string
필수: no

예측 제공 시 컨텍스트로 사용할 캐시 콘텐츠 이름입니다. 형식: cachedContents/{cachedContent}

📥 응답¶

GenerateContentResponse¶

여러 후보 답변을 지원하는 모델의 응답 객체입니다. 시스템은 프롬프트 및 각 후보에 대한 안전 등급과 콘텐츠 필터링 정보를 함께 반환합니다.

`candidates`¶

유형: array
설명: 모델이 생성한 후보 답변 목록

Candidate 객체 속성:

속성	유형	설명
`content`	object	모델이 반환한 생성 콘텐츠
`finishReason`	enum	모델이 토큰 생성을 중단한 이유
`safetyRatings`	array	후보 답변의 안전 등급 목록
`citationMetadata`	object	생성 후보의 참조 정보
`tokenCount`	integer	해당 후보의 토큰 수
`groundingAttributions`	array	근거 기반 답변 생성에 기여한 출처 정보
`groundingMetadata`	object	후보 객체의 참조 메타데이터
`avgLogprobs`	number	후보의 평균 로그 확률 점수
`logprobsResult`	object	답변 토큰 및 선행 토큰의 로그 확률 점수
`urlRetrievalMetadata`	object	URL 컨텍스트 조회 도구 관련 메타데이터
`urlContextMetadata`	object	URL 컨텍스트 조회 도구 관련 메타데이터
`index`	integer	응답 후보 목록 내 후보 인덱스

FinishReason enum 값:

STOP: 자연스러운 종료 지점 또는 지정된 중지 시퀀스 도달
MAX_TOKENS: 요청에서 지정한 최대 토큰 한도 도달
SAFETY: 안전 정책으로 후보 답변 콘텐츠가 차단됨
RECITATION: 반복/인용 관련 사유로 후보 답변 콘텐츠가 표시됨
LANGUAGE: 지원되지 않는 언어 사용으로 후보 답변 콘텐츠가 표시됨
OTHER: 기타(알 수 없는 이유)
BLOCKLIST: 금지어 포함으로 토큰 생성 중단
PROHIBITED_CONTENT: 금지 콘텐츠 가능성으로 토큰 생성 중단
SPII: 민감한 개인정보 포함 가능성으로 토큰 생성 중단
MALFORMED_FUNCTION_CALL: 모델이 생성한 함수 호출 형식이 잘못됨
IMAGE_SAFETY: 생성 이미지가 안전 규칙을 위반하여 중단됨

`promptFeedback`¶

유형: object
설명: 콘텐츠 필터링과 관련된 프롬프트 피드백

PromptFeedback 객체 속성:

속성	유형	설명
`blockReason`	enum	프롬프트 차단 이유
`safetyRatings`	array	프롬프트의 안전 등급

BlockReason enum 값:

BLOCK_REASON_UNSPECIFIED: 기본값(사용되지 않음)
SAFETY: 안전 사유로 시스템이 프롬프트를 차단
OTHER: 알 수 없는 이유로 프롬프트 차단
BLOCKLIST: 블록리스트 용어 포함으로 프롬프트 차단
PROHIBITED_CONTENT: 금지 콘텐츠 포함으로 프롬프트 차단
IMAGE_SAFETY: 생성 이미지가 안전하지 않아 후보 이미지 차단

`usageMetadata`¶

유형: object
설명: 생성 요청의 토큰 사용량 메타데이터

UsageMetadata 객체 속성:

속성	유형	설명
`promptTokenCount`	integer	프롬프트 토큰 수
`cachedContentTokenCount`	integer	프롬프트 캐시 영역 토큰 수
`candidatesTokenCount`	integer	생성된 모든 후보 답변의 총 토큰 수
`totalTokenCount`	integer	생성 요청의 총 토큰 수
`toolUsePromptTokenCount`	integer	도구 사용 프롬프트 토큰 수
`thoughtsTokenCount`	integer	추론 모델의 thoughts 토큰 수
`promptTokensDetails`	array	요청 입력에서 처리된 모달리티 목록
`candidatesTokensDetails`	array	응답에서 반환된 모달리티 목록
`cacheTokensDetails`	array	요청 입력의 캐시 콘텐츠 모달리티 목록
`toolUsePromptTokensDetails`	array	도구 사용 입력에서 처리된 모달리티 목록

`modelVersion`¶

유형: string
설명: 응답 생성에 사용된 모델 버전

`responseId`¶

유형: string
설명: 각 응답의 ID

전체 응답 예시¶

{
  "candidates": [
    {
      "content": {
        "parts": [
          {
            "text": "안녕하세요! 저는 Gemini입니다. Google에서 개발한 AI 어시스턴트로, 질의응답, 정보 제공, 글쓰기, 코드 작성 등 다양한 작업을 도와드릴 수 있습니다."
          }
        ],
        "role": "model"
      },
      "finishReason": "STOP",
      "index": 0,
      "safetyRatings": [
        {
          "category": "HARM_CATEGORY_SEXUALLY_EXPLICIT",
          "probability": "NEGLIGIBLE",
          "blocked": false
        },
        {
          "category": "HARM_CATEGORY_HATE_SPEECH", 
          "probability": "NEGLIGIBLE",
          "blocked": false
        },
        {
          "category": "HARM_CATEGORY_HARASSMENT",
          "probability": "NEGLIGIBLE",
          "blocked": false
        },
        {
          "category": "HARM_CATEGORY_DANGEROUS_CONTENT",
          "probability": "NEGLIGIBLE",
          "blocked": false
        }
      ],
      "tokenCount": 47
    }
  ],
  "promptFeedback": {
    "safetyRatings": [
      {
        "category": "HARM_CATEGORY_SEXUALLY_EXPLICIT",
        "probability": "NEGLIGIBLE"
      },
      {
        "category": "HARM_CATEGORY_HATE_SPEECH",
        "probability": "NEGLIGIBLE"
      }
    ]
  },
  "usageMetadata": {
    "promptTokenCount": 4,
    "candidatesTokenCount": 47,
    "totalTokenCount": 51,
    "promptTokensDetails": [
      {
        "modality": "TEXT",
        "tokenCount": 4
      }
    ],
    "candidatesTokensDetails": [
      {
        "modality": "TEXT", 
        "tokenCount": 47
      }
    ]
  },
  "modelVersion": "gemini-3-pro-preview",
  "responseId": "response-12345"
}

🔧 고급 기능¶

안전 등급¶

SafetyRating 객체 속성:

속성	유형	설명
`category`	enum	해당 등급의 카테고리
`probability`	enum	해당 콘텐츠의 유해 확률
`blocked`	boolean	해당 등급으로 인해 차단되었는지 여부

HarmProbability enum 값:

NEGLIGIBLE: 유해 확률이 매우 낮음
LOW: 유해 확률이 낮음
MEDIUM: 유해 확률이 중간
HIGH: 유해 확률이 높음

인용 메타데이터¶

CitationMetadata 객체 속성:

속성	유형	설명
`citationSources`	array	특정 응답의 출처 참조 목록

CitationSource 객체 속성:

속성	유형	설명
`startIndex`	integer	해당 출처가 기여한 응답 구간의 시작 인덱스
`endIndex`	integer	해당 출처 기여 구간의 종료 인덱스(exclusive)
`uri`	string	해당 출처로 귀속된 텍스트 구간의 URI
`license`	string	출처 조각에 귀속된 GitHub 프로젝트 라이선스

코드 실행¶

코드 실행 도구를 활성화하면 모델이 문제 해결을 위해 코드를 생성하고 실행할 수 있습니다.

코드 실행 응답 예시:

{
  "candidates": [
    {
      "content": {
        "parts": [
          {
            "text": "피보나치 수열의 10번째 항을 계산하겠습니다:"
          },
          {
            "executableCode": {
              "language": "PYTHON",
              "code": "def fibonacci(n):\n    if n <= 1:\n        return n\n    else:\n        return fibonacci(n-1) + fibonacci(n-2)\n\nresult = fibonacci(10)\nprint(f'The 10th Fibonacci number is: {result}')"
            }
          },
          {
            "codeExecutionResult": {
              "outcome": "OK",
              "output": "The 10th Fibonacci number is: 55"
            }
          },
          {
            "text": "따라서 피보나치 수열의 10번째 항은 55입니다."
          }
        ],
        "role": "model"
      },
      "finishReason": "STOP"
    }
  ]
}

그라운딩¶

GroundingMetadata 객체 속성:

속성	유형	설명
`groundingChunks`	array	지정된 그라운딩 소스에서 조회된 근거 문서 목록
`groundingSupports`	array	그라운딩 지원 목록
`webSearchQueries`	array	후속 웹 검색에 사용된 쿼리 목록
`searchEntryPoint`	object	후속 웹 검색을 위한 Google 검색 진입점
`retrievalMetadata`	object	조회 과정 관련 메타데이터

GroundingAttribution 객체 속성:

속성	유형	설명
`sourceId`	object	해당 귀속에 기여한 소스의 식별자
`content`	object	해당 귀속에 기여한 소스 콘텐츠

AttributionSourceId 객체 속성:

속성	유형	설명
`groundingPassage`	object	임베딩된 문단의 식별자
`semanticRetrieverChunk`	object	Semantic Retriever가 추출한 청크 식별자

GroundingPassageId 객체 속성:

속성	유형	설명
`passageId`	string	`GenerateAnswerRequest`의 `GroundingPassage.id`와 매칭되는 문단 ID
`partIndex`	integer	`GroundingPassage.content` 내 파트 인덱스

SemanticRetrieverChunk 객체 속성:

속성	유형	설명
`source`	string	요청의 `SemanticRetrieverConfig.source`와 일치하는 소스 이름
`chunk`	string	귀속 텍스트가 포함된 청크 이름

SearchEntryPoint 객체 속성:

속성	유형	설명
`renderedContent`	string	웹페이지 또는 앱 WebView에 임베드 가능한 웹 콘텐츠 코드 조각
`sdkBlob`	string	검색어와 URL 튜플 배열을 나타내는 Base64 인코딩 JSON

Segment 객체 속성:

속성	유형	설명
`partIndex`	integer	상위 Content 객체 내 Part 객체 인덱스
`startIndex`	integer	해당 파트의 시작 바이트 인덱스
`endIndex`	integer	해당 청크의 종료 바이트 인덱스
`text`	string	응답 내 해당 조각에 해당하는 텍스트

RetrievalMetadata 객체 속성:

속성	유형	설명
`googleSearchDynamicRetrievalScore`	number	Google 검색 정보가 답변에 기여할 확률 점수, 범위 [0,1]

GroundingChunk 객체 속성:

속성	유형	설명
`web`	object	웹에서 가져온 그라운딩 청크

Web 객체 속성:

속성	유형	설명
`uri`	string	청크의 URI 참조
`title`	string	데이터 블록 제목

GroundingSupport 객체 속성:

속성	유형	설명
`groundingChunkIndices`	array	저작권 관련 인용 지정에 사용되는 인덱스 목록
`confidenceScores`	array	근거 문서 신뢰도 점수, 범위 0-1
`segment`	object	해당 지원 요청이 속한 콘텐츠 세그먼트

멀티모달 처리¶

Gemini API는 입력과 출력의 다양한 모달리티 처리를 지원합니다:

지원 입력 모달리티:

TEXT: 순수 텍스트
IMAGE: 이미지 (JPEG, PNG, WebP, HEIC, HEIF)
AUDIO: 오디오 (WAV, MP3, AIFF, AAC, OGG, FLAC)
VIDEO: 비디오 (MP4, MPEG, MOV, AVI, FLV, MPG, WEBM, WMV, 3GPP)
DOCUMENT: 문서 (PDF)

ModalityTokenCount 객체 속성:

속성	유형	설명
`modality`	enum	해당 토큰 수와 연결된 모달리티
`tokenCount`	integer	토큰 수

MediaResolution enum 값:

MEDIA_RESOLUTION_LOW: 저해상도 (64 토큰)
MEDIA_RESOLUTION_MEDIUM: 중해상도 (256 토큰)
MEDIA_RESOLUTION_HIGH: 고해상도 (스케일링/리프레이밍에 256 토큰 사용)

추론(Thinking) 기능¶

ThinkingConfig 객체 속성:

속성	유형	설명
`includeThoughts`	boolean	응답에 추론 콘텐츠를 포함할지 여부
`thinkingBudget`	integer	모델이 생성할 아이디어 토큰 수

음성 생성¶

SpeechConfig 객체 속성:

속성	유형	설명
`voiceConfig`	object	단일 화자 음성 출력 설정
`multiSpeakerVoiceConfig`	object	다중 화자 설정
`languageCode`	string	음성 합성 언어 코드

VoiceConfig 객체 속성:

속성	유형	설명
`prebuiltVoiceConfig`	object	사용할 사전 정의 음성 설정

PrebuiltVoiceConfig 객체 속성:

속성	유형	설명
`voiceName`	string	사용할 사전 정의 음성 이름

MultiSpeakerVoiceConfig 객체 속성:

속성	유형	설명
`speakerVoiceConfigs`	array	활성화된 화자 음성 설정 목록

SpeakerVoiceConfig 객체 속성:

속성	유형	설명
`speaker`	string	사용할 화자 이름
`voiceConfig`	object	사용할 음성 설정

지원 언어 코드:

zh-CN: 중국어 (간체)
en-US: 영어 (미국)
ja-JP: 일본어
ko-KR: 한국어
fr-FR: 프랑스어
de-DE: 독일어
es-ES: 스페인어
pt-BR: 포르투갈어 (브라질)
hi-IN: 힌디어
ar-XA: 아랍어
it-IT: 이탈리아어
tr-TR: 터키어
vi-VN: 베트남어
th-TH: 태국어
ru-RU: 러시아어
pl-PL: 폴란드어
nl-NL: 네덜란드어

Logprobs 결과¶

LogprobsResult 객체 속성:

속성	유형	설명
`topCandidates`	array	로그 확률 내림차순으로 정렬된 후보 배열
`chosenCandidates`	array	선택된 후보 배열(반드시 topCandidates에 포함되지 않을 수 있으며 길이는 전체 디코딩 단계 수와 동일)

TopCandidates 객체 속성:

속성	유형	설명
`candidates`	array	로그 확률 내림차순으로 정렬된 후보

Candidate (Logprobs) 객체 속성:

속성	유형	설명
`token`	string	후보의 토큰 문자열 값
`tokenId`	integer	후보의 토큰 ID 값
`logProbability`	number	후보의 로그 확률

URL 조회 기능¶

UrlRetrievalMetadata 객체 속성:

속성	유형	설명
`urlRetrievalContexts`	array	URL 조회 컨텍스트 목록

UrlRetrievalContext 객체 속성:

속성	유형	설명
`retrievedUrl`	string	도구가 조회한 URL

UrlContextMetadata 객체 속성:

속성	유형	설명
`urlMetadata`	array	URL 컨텍스트 목록

UrlMetadata 객체 속성:

속성	유형	설명
`retrievedUrl`	string	도구가 조회한 URL
`urlRetrievalStatus`	enum	URL 조회 상태

UrlRetrievalStatus enum 값:

URL_RETRIEVAL_STATUS_SUCCESS: URL 조회 성공
URL_RETRIEVAL_STATUS_ERROR: 오류로 URL 조회 실패

전체 유해성 카테고리¶

HarmCategory enum 값:

HARM_CATEGORY_UNSPECIFIED: 카테고리 미지정
HARM_CATEGORY_DEROGATORY: PaLM - 정체성/보호 속성을 겨냥한 부정적·유해한 발언
HARM_CATEGORY_TOXICITY: PaLM - 무례하거나 비속한 콘텐츠
HARM_CATEGORY_VIOLENCE: PaLM - 개인/집단 대상 폭력 묘사
HARM_CATEGORY_SEXUAL: PaLM - 성적 행위 또는 노골적 콘텐츠 언급
HARM_CATEGORY_MEDICAL: PaLM - 검증되지 않은 의료 조언 조장
HARM_CATEGORY_DANGEROUS: PaLM - 유해 행위를 촉진/권장/조장하는 콘텐츠
HARM_CATEGORY_HARASSMENT: Gemini - 괴롭힘 콘텐츠
HARM_CATEGORY_HATE_SPEECH: Gemini - 혐오 발언/콘텐츠
HARM_CATEGORY_SEXUALLY_EXPLICIT: Gemini - 노골적인 성적 콘텐츠
HARM_CATEGORY_DANGEROUS_CONTENT: Gemini - 위험 콘텐츠
HARM_CATEGORY_CIVIC_INTEGRITY: Gemini - 시민적 신뢰를 훼손할 수 있는 콘텐츠

HarmProbability enum 값:

HARM_PROBABILITY_UNSPECIFIED: 확률 미지정
NEGLIGIBLE: 유해 확률이 매우 낮음
LOW: 유해 확률이 낮음
MEDIUM: 유해 확률이 중간
HIGH: 유해 확률이 높음

Modality enum 값:

MODALITY_UNSPECIFIED: 모달리티 미지정
TEXT: 순수 텍스트
IMAGE: 이미지
VIDEO: 비디오
AUDIO: 오디오
DOCUMENT: 문서(예: PDF)

MediaResolution enum 값:

MEDIA_RESOLUTION_UNSPECIFIED: 미디어 해상도 미설정
MEDIA_RESOLUTION_LOW: 저해상도 설정 (64 토큰)
MEDIA_RESOLUTION_MEDIUM: 중해상도 설정 (256 토큰)
MEDIA_RESOLUTION_HIGH: 고해상도 설정 (스케일링/리프레이밍에 256 토큰 사용)

UrlRetrievalStatus enum 값:

URL_RETRIEVAL_STATUS_UNSPECIFIED: 기본값(사용되지 않음)
URL_RETRIEVAL_STATUS_SUCCESS: URL 조회 성공
URL_RETRIEVAL_STATUS_ERROR: 오류로 URL 조회 실패

🔍 오류 처리¶

주요 오류 코드¶

오류 코드	설명
`400`	요청 형식 오류 또는 잘못된 파라미터
`401`	API 키가 유효하지 않거나 누락됨
`403`	권한 부족 또는 할당량 제한
`429`	요청 빈도가 너무 높음
`500`	서버 내부 오류

상세 오류 코드 설명¶

오류 코드	상태	설명	해결 방법
`400`	`INVALID_ARGUMENT`	요청 파라미터가 잘못되었거나 형식 오류	요청 파라미터 형식과 필수 필드 확인
`400`	`FAILED_PRECONDITION`	요청 사전 조건 미충족	API 호출 전제 조건 충족 여부 확인
`401`	`UNAUTHENTICATED`	API 키가 유효하지 않거나 누락/만료됨	API 키 유효성과 형식 확인
`403`	`PERMISSION_DENIED`	권한 부족 또는 할당량 소진	API 키 권한 확인 또는 할당량 상향
`404`	`NOT_FOUND`	지정한 모델 또는 리소스가 없음	모델 이름 및 리소스 경로 확인
`413`	`PAYLOAD_TOO_LARGE`	요청 본문이 너무 큼	입력 크기 축소 또는 배치 처리
`429`	`RESOURCE_EXHAUSTED`	요청 빈도 초과 또는 할당량 부족	요청 빈도 조절 또는 할당량 초기화 대기
`500`	`INTERNAL`	서버 내부 오류	요청 재시도, 지속 시 지원팀 문의
`503`	`UNAVAILABLE`	서비스 일시 사용 불가	잠시 후 재시도
`504`	`DEADLINE_EXCEEDED`	요청 시간 초과	입력 크기 축소 또는 재시도

오류 응답 예시¶

{
  "error": {
    "code": 400,
    "message": "Invalid argument: contents",
    "status": "INVALID_ARGUMENT",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.BadRequest",
        "fieldViolations": [
          {
            "field": "contents",
            "description": "contents is required"
          }
        ]
      }
    ]
  }
}

Google Gemini 채팅 형식 (Generate Content)¶

📝 소개¶

🤖 지원 모델¶

💡 요청 예시¶

기본 텍스트 대화 ✅¶

이미지 분석 대화 ✅¶

함수 호출 ✅¶

JSON 스키마 응답 ✅¶

오디오 처리 🟡¶

비디오 처리 🟡¶

PDF 처리 🟡¶

채팅 대화 ✅¶

스트리밍 응답 ✅¶

코드 실행 ✅¶

생성 설정 ✅¶

안전 설정 ✅¶

시스템 지침 ✅¶

📮 요청¶

엔드포인트¶

콘텐츠 생성 (Generate Content)¶

스트림 콘텐츠 생성 (Stream Generate Content)¶

인증 방법¶

경로 파라미터¶

model¶

요청 본문 파라미터¶

contents¶

tools¶

toolConfig¶

safetySettings¶

systemInstruction¶

generationConfig¶

cachedContent¶

📥 응답¶

GenerateContentResponse¶

candidates¶

promptFeedback¶

usageMetadata¶

modelVersion¶

responseId¶

전체 응답 예시¶

🔧 고급 기능¶

안전 등급¶

인용 메타데이터¶

코드 실행¶

그라운딩¶

멀티모달 처리¶

추론(Thinking) 기능¶

음성 생성¶

Logprobs 결과¶

URL 조회 기능¶

전체 유해성 카테고리¶

🔍 오류 처리¶

주요 오류 코드¶

상세 오류 코드 설명¶

오류 응답 예시¶

`model`¶

`contents`¶

`tools`¶

`toolConfig`¶

`safetySettings`¶

`systemInstruction`¶

`generationConfig`¶

`cachedContent`¶

`candidates`¶

`promptFeedback`¶

`usageMetadata`¶

`modelVersion`¶

`responseId`¶