generateContent API

endpoint 하나, 모든 Gemini 상호작용

text 보내든, image 보내든, tool call 보내든, JSON 모드 request 보내든 — 같은 endpoint 야: generateContent. streaming variant 는 streamGenerateContent?alt=sse. 모양 외우면 Gemini 의 나머지가 외울 거 없는 거처럼 느껴져.

Request 구조

request 는 최대 네 개 top-level field 가짐:

contents — 대화. {role, parts} 객체 list. role 은 "user" 와 "model". "system" role 은 없어.
system_instruction — system prompt 용 별도 top-level field. "you are an X" 가 여기 들어감.
generationConfig — temperature, top-p, top-k, max output tokens, response MIME type, seed.
safetySettings — harm category 별 threshold.

Parts 가 원자 단위

content 의 parts 배열 안에서, 각 part 는 다음 중 하나:

Text — {"text": "..."}
Inline data — {"inline_data": {"mime_type": "image/png", "data": "base64..."}}
File data — {"file_data": {"file_uri": "files/abc"}} (File API 로 업로드 후)
Function call — {"function_call": {"name": "...", "args": {...}}} (모델 출력)
Function response — {"function_response": {"name": "...", "response": {...}}} (너의 tool 결과)

한 content 의 parts 배열에 여러 part 들어갈 수 있어 — "이 이미지 설명해" + 이미지 자체를 한 user turn 안에 보낼 때 그렇게 돼.

Response 모양

응답은 모델 출력을 candidates (거의 항상 한 개) 로 wrap 하고 finishReason 으로 왜 끝났는지 알려줘 — STOP (정상 종료), MAX_TOKENS (예산 소진), SAFETY (필터링), RECITATION (학습 데이터 echo), OTHER (이거 보고 싶지 않을 거야).

Code

Endpoint URL·text

# Developer API (AI Studio)
POST https://generativelanguage.googleapis.com/v1beta/models/{MODEL}:generateContent
POST https://generativelanguage.googleapis.com/v1beta/models/{MODEL}:streamGenerateContent?alt=sse

# Vertex AI
POST https://{LOC}-aiplatform.googleapis.com/v1/projects/{PROJECT}/locations/{LOC}/publishers/google/models/{MODEL}:generateContent

Request body — 전체 모양·json

{
  "contents": [
    { "role": "user",  "parts": [{ "text": "Hello" }] },
    { "role": "model", "parts": [{ "text": "Hi! How can I help?" }] },
    { "role": "user",  "parts": [{ "text": "Explain transformers in 3 sentences." }] }
  ],
  "system_instruction": {
    "parts": [{ "text": "You are a precise but warm technical tutor." }]
  },
  "generationConfig": {
    "temperature": 0.7,
    "topP": 0.95,
    "topK": 40,
    "maxOutputTokens": 800,
    "responseMimeType": "text/plain"
  },
  "safetySettings": [
    { "category": "HARM_CATEGORY_HARASSMENT", "threshold": "BLOCK_ONLY_HIGH" }
  ]
}

Response body·json

{
  "candidates": [{
    "content": {
      "role": "model",
      "parts": [{ "text": "Transformers process tokens in parallel using attention..." }]
    },
    "finishReason": "STOP",
    "safetyRatings": [
      { "category": "HARM_CATEGORY_HARASSMENT", "probability": "NEGLIGIBLE" }
    ]
  }],
  "usageMetadata": {
    "promptTokenCount": 45,
    "candidatesTokenCount": 123,
    "totalTokenCount": 168
  }
}

Exercise

4 메시지 대화 (user/model/user/model 번갈아) 의 JSON 직접 작성. system instruction, temperature 0.3, max output 200 토큰 포함. curl 로 generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash:generateContent 에 POST. 응답 읽고 출력: finishReason, totalTokenCount, 모델 답변의 첫 100 자.