Ollama API - 응답 생성

Ollama API - 응답 생성 (Generate)

/api/generate는 프롬프트 하나를 받아 모델의 응답 텍스트를 생성하는 가장 기본적인 엔드포인트예요. 대화 맥락이 필요 없는 단발성 생성 작업에 알맞습니다.

출처: 공식문서 - Generate a response

엔드포인트

POST /api/generate

기본 요청

curl http://localhost:11434/api/generate -d '{
  "model": "gemma4",
  "prompt": "Why is the sky blue?"
}'

비스트리밍

curl http://localhost:11434/api/generate -d '{
  "model": "gemma4",
  "prompt": "Why is the sky blue?",
  "stream": false
}'

옵션 지정

options로 temperature, top_p, seed 같은 생성 제어 파라미터를 넘길 수 있어요.

curl http://localhost:11434/api/generate -d '{
  "model": "gemma4",
  "prompt": "Why is the sky blue?",
  "options": {
    "temperature": 0.8,
    "top_p": 0.9,
    "seed": 42
  }
}'

구조화된 출력 (Structured outputs)

format에 JSON 스키마를 주면 모델이 그 구조에 맞는 출력을 내놓아요. "json" 문자열을 줄 수도 있고, 아래처럼 객체 스키마를 줄 수도 있어요.

curl http://localhost:11434/api/generate -d '{
  "model": "gemma4",
  "prompt": "What are the populations of the United States and Canada?",
  "stream": false,
  "format": {
    "type": "object",
    "properties": {
      "countries": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "country": {"type": "string"},
            "population": {"type": "integer"}
          },
          "required": ["country", "population"]
        }
      }
    },
    "required": ["countries"]
  }
}'

이미지 포함

이미지 입력을 지원하는 모델이라면 images 필드에 base64로 인코딩된 이미지를 배열로 넣어요.

curl http://localhost:11434/api/generate -d '{
  "model": "gemma4",
  "prompt": "What is in this picture?",
  "images": ["<base64-encoded-image-data>"]
}'

모델 로드 / 언로드

모델 이름만 보내면 모델을 메모리에 로드하는 용도로 쓸 수 있어요.

curl http://localhost:11434/api/generate -d '{
  "model": "gemma4"
}'

keep_alive: 0을 주면 모델을 즉시 언로드해요.

curl http://localhost:11434/api/generate -d '{
  "model": "gemma4",
  "keep_alive": 0
}'

주요 요청 필드

필드 설명
model 모델 이름 (필수)
prompt 모델이 응답을 생성할 기준이 되는 텍스트
suffix fill-in-the-middle 모델용. 사용자 프롬프트 뒤, 모델 응답 앞에 올 텍스트
images 이미지 입력을 지원하는 모델용 base64 인코딩 이미지 배열
format 구조화된 출력 형식. 문자열 "json" 또는 JSON 스키마 객체
system 시스템 프롬프트
stream true면 부분 응답 스트림 반환 (기본 true)
think true면 콘텐츠와 별도로 사고(thinking) 출력 반환. boolean 또는 "high"/"medium"/"low"/"max" 문자열 (지원 모델)
raw true면 프롬프트 템플릿 없이 모델의 raw 응답 반환
keep_alive 모델 유지 시간 (예: 5m, 즉시 언로드는 0)
options 생성 제어 런타임 옵션 (temperature, top_k, top_p, seed, num_ctx, num_predict, stop 등)
logprobs 출력 토큰의 로그 확률 반환 여부
top_logprobs logprobs 활성 시 각 토큰 위치에서 반환할 최상위 후보 토큰 수

주요 응답 필드

필드 설명
model 모델 이름
created_at 응답 생성 시각 (ISO 8601)
response 모델이 생성한 텍스트 응답
thinking 모델이 생성한 사고 출력
done 생성 완료 여부
done_reason 생성이 중단된 이유
total_duration 응답 생성에 걸린 시간 (나노초)
load_duration 모델 로딩에 걸린 시간 (나노초)
prompt_eval_count 프롬프트의 입력 토큰 수
prompt_eval_cached_count 캐시에서 읽은 프롬프트 토큰 수
prompt_eval_duration 비캐시 프롬프트 토큰 평가 시간 (나노초)
eval_count 응답에서 생성된 출력 토큰 수
eval_duration 토큰 생성에 걸린 시간 (나노초)
logprobs logprobs 활성 시 생성 토큰의 로그 확률 정보

참고: 이 엔드포인트는 기본적으로 스트리밍 방식(newline-delimited JSON)으로 응답해요. 전체 스키마는 공식 OpenAPI 명세(/openapi.yaml)에서 확인할 수 있어요.

더 알아보기