generateContent API

엔드포인트 하나로 모든 Gemini 상호작용 다루기

텍스트와 이미지, 도구 호출, JSON 모드 요청은 모두 같은 generateContent 엔드포인트로 보내. 스트리밍 버전은 streamGenerateContent?alt=sse야. 이 구조만 익히면 Gemini의 나머지도 훨씬 단순하게 보여.

요청 구조

요청에는 최상위 필드가 최대 네 개 있어:

contents — 대화 내용이야. {role, parts} 객체의 목록이며, role은 "user"와 "model"을 써. "system" 역할은 없어.
system_instruction — 시스템 프롬프트를 넣는 별도 최상위 필드야. "you are an X" 같은 지시가 여기 들어가.
generationConfig — temperature, top-p, top-k, 최대 출력 토큰, 응답 MIME 형식, seed를 정해.
safetySettings — 위해 범주마다 차단 기준을 정해.

Parts가 원자 단위야

콘텐츠의 parts 배열에서 각 part는 다음 중 하나야:

텍스트 — {"text": "..."}
인라인 데이터 — {"inline_data": {"mime_type": "image/png", "data": "base64..."}}
파일 데이터 — {"file_data": {"file_uri": "files/abc"}}(File API에 업로드한 뒤 사용)
함수 호출 — {"function_call": {"name": "...", "args": {...}}}(모델 출력)
함수 응답 — {"function_response": {"name": "...", "response": {...}}}(도구 실행 결과)

하나의 콘텐츠에 든 parts 배열에는 여러 part를 넣을 수 있어. "이 이미지를 설명해"라는 텍스트와 이미지 자체를 한 사용자 차례에 함께 보내는 식이야.

응답 구조

응답은 모델 출력을 candidates로 감싸. 후보는 거의 항상 하나야. finishReason은 생성이 끝난 이유를 알려 줘. STOP은 정상 종료, MAX_TOKENS는 예산 소진, SAFETY는 필터링, RECITATION은 학습 데이터 반복, OTHER는 보고 싶지 않은 기타 종료야.

Code

엔드포인트 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

요청 본문 — 전체 구조·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" }
  ]
}

응답 본문·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개의 JSON을 직접 작성해. 시스템 지시문, temperature 0.3, 최대 출력 200토큰을 포함하고, curl로 generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash:generateContent에 POST해. 응답에서 finishReason, totalTokenCount, 모델 답변의 첫 100자를 출력해 봐.