Ollama API - 채팅 메시지 생성

Ollama API - 채팅 메시지 생성 (Chat)

/api/chat는 사용자와 어시스턴트 사이의 대화에서 다음 채팅 메시지를 생성하는 엔드포인트예요. messages 배열로 대화 이력을 넘겨 멀티턴 대화를 이어갈 수 있습니다.

출처: 공식문서 - Generate a chat message

엔드포인트

POST /api/chat

기본 요청

curl http://localhost:11434/api/chat -d '{
  "model": "gemma4",
  "messages": [
    {
      "role": "user",
      "content": "why is the sky blue?"
    }
  ]
}'

비스트리밍

curl http://localhost:11434/api/chat -d '{
  "model": "gemma4",
  "messages": [
    {
      "role": "user",
      "content": "why is the sky blue?"
    }
  ],
  "stream": false
}'

구조화된 출력 (Structured outputs)

채팅에서도 format으로 JSON 스키마를 줄 수 있어요.

curl -X POST http://localhost:11434/api/chat -H "Content-Type: application/json" -d '{
  "model": "gemma4",
  "messages": [
    {
      "role": "user",
      "content": "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"]
  }
}'

도구 호출 (Tool calling)

tools에 함수 정의를 넘기면 모델이 도구 호출을 요청할 수 있어요.

curl http://localhost:11434/api/chat -d '{
  "model": "qwen3",
  "messages": [
    {
      "role": "user",
      "content": "What is the weather today in Paris?"
    }
  ],
  "stream": false,
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "get_current_weather",
        "description": "Get the current weather for a location",
        "parameters": {
          "type": "object",
          "properties": {
            "location": {
              "type": "string",
              "description": "The location to get the weather for, e.g. San Francisco, CA"
            },
            "format": {
              "type": "string",
              "description": "The format to return the weather in, e.g. 'celsius' or 'fahrenheit'",
              "enum": ["celsius", "fahrenheit"]
            }
          },
          "required": ["location", "format"]
        }
      }
    }
  ]
}'

사고 (Thinking) 제어

thinking을 지원하는 모델에서는 think로 사고 수준을 조절할 수 있어요.

curl http://localhost:11434/api/chat -d '{
  "model": "gpt-oss",
  "messages": [
    {
      "role": "user",
      "content": "What is 1+1?"
    }
  ],
  "think": "low"
}'

이미지 포함

멀티모달 모델이라면 메시지 content 옆에 base64로 인코딩된 이미지를 images 배열로 넣어요.

curl http://localhost:11434/api/chat -d '{
  "model": "gemma4",
  "messages": [
    {
      "role": "user",
      "content": "What is in this image?",
      "images": ["<base64-encoded-image-data>"]
    }
  ]
}'

주요 요청 필드

필드 설명
model 모델 이름 (필수)
messages 대화 이력. 각각 role과 content를 가진 메시지 객체 배열 (필수)
tools 대화 중 모델이 호출할 수 있는 함수 도구 목록
format 응답 형식. json 또는 JSON 스키마
options 생성 제어 런타임 옵션
stream true면 부분 응답 스트림 (기본 true)
think true면 콘텐츠와 별도로 사고 출력 반환. boolean 또는 "high"/"medium"/"low"/"max"
keep_alive 모델 유지 시간 (예: 5m, 즉시 언로드는 0)
logprobs 출력 토큰의 로그 확률 반환 여부
top_logprobs 각 토큰 위치에서 반환할 최상위 후보 토큰 수

messages의 각 메시지에서 role은 system, user, assistant, tool 중 하나이고, content는 메시지 본문이에요. 활성 도구 호출이 있으면 tool_calls도 담길 수 있어요.

주요 응답 필드

필드 설명
model 이 메시지를 생성한 모델 이름
created_at 응답 생성 시각 (ISO 8601)
message 어시스턴트 메시지. role, content, thinking, tool_calls, images 포함
done 채팅 응답 완료 여부
done_reason 응답이 끝난 이유
total_duration 생성에 걸린 총 시간 (나노초)
load_duration 모델 로딩 시간 (나노초)
prompt_eval_count 프롬프트 토큰 수
prompt_eval_cached_count 캐시에서 읽은 프롬프트 토큰 수
prompt_eval_duration 비캐시 프롬프트 토큰 평가 시간 (나노초)
eval_count 응답에서 생성된 토큰 수
eval_duration 토큰 생성 시간 (나노초)
logprobs logprobs 활성 시 로그 확률 정보

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

더 알아보기