Ollama API 사용법 | stream 옵션과 curl 테스트 예시

Ollama를 터미널에서만 쓰다가 어느 순간 이런 생각이 들었습니다.

“이걸 내가 만든 작은 프로그램이나 테스트 코드에서도 부를 수 있는 건가?”

처음에는 API라고 하니 뭔가 복잡하게 느껴졌는데요. 막상 확인해 보니 기본 흐름은 생각보다 단순했습니다.

내 Mac에서 Ollama가 실행 중이면, localhost:11434 주소로 요청을 보내고 모델 응답을 받는 구조입니다.

오늘은 Ollama API 사용법을 초보자 기준으로 정리해 보겠습니다. 특히 curl로 /api/generate를 호출하는 방법, stream 옵션이 왜 중요한지, 그리고 응답이 여러 줄로 나오는 이유까지 같이 보겠습니다.

Ollama 설치와 첫 모델 선택이 아직이라면 아래 글부터 먼저 보셔도 좋습니다.

→ Ollama 설치 후 첫 모델 고르는 법 | Mac 초보자를 위한 로컬 AI 입문

모델 속도나 메모리가 먼저 궁금하다면 아래 글도 이어서 참고하시면 좋습니다.

→ Ollama 느릴 때 확인할 7가지 | Mac 모델 속도와 메모리 점검 방법

VS Code 안에서 Ollama 모델을 쓰는 방법은 아래 글에 따로 정리했습니다.

→ VS Code Continue에 Ollama 연결하는 법 | Mac 로컬 AI 코딩 도우미 만들기

Ollama API 사용법, 먼저 구조부터 보면 쉽습니다

Ollama를 설치하면 내 Mac 안에서 로컬 서버가 실행됩니다.

기본 주소는 보통 아래와 같습니다.

http://localhost:11434

여기서 localhost는 “내 컴퓨터 자신”을 뜻합니다. 그러니까 인터넷 어딘가의 서버로 보내는 것이 아니라, 내 Mac에서 실행 중인 Ollama에게 요청을 보내는 구조라고 이해하면 됩니다.

기본적인 생성 요청은 /api/generate로 보냅니다. 공식 문서에서도 이 엔드포인트는 prompt를 받아 모델 응답을 생성하는 API로 안내하고 있습니다.

1단계: Ollama가 실행 중인지 확인하기

먼저 Ollama가 켜져 있는지 확인해 보겠습니다.

curl http://localhost:11434

정상이라면 Ollama가 실행 중이라는 식의 응답이 나옵니다.

만약 연결이 안 된다면 Ollama 앱이 꺼져 있거나, 서버가 아직 실행되지 않은 상태일 수 있습니다. 이럴 때는 Ollama 앱을 실행한 뒤 다시 확인해 보세요.

설치된 모델 이름도 먼저 확인하는 것이 좋습니다.

ollama list

여기서 보이는 모델 이름을 API 요청의 model 값에 그대로 넣어야 합니다. 예를 들어 qwen3:8b, qwen3.5:9b-mlx, gemma4:hermes-64k처럼 태그까지 정확히 맞춰야 합니다.

2단계: curl로 /api/generate 호출하기

이제 실제로 모델에게 질문을 보내보겠습니다.

아래 예시는 qwen3:8b 모델을 기준으로 작성했습니다. 본인 Mac에 설치된 모델 이름이 다르면 그 부분만 바꿔 주세요.

curl http://localhost:11434/api/generate -d '{
  "model": "qwen3:8b",
  "prompt": "Ollama API를 초보자에게 한 문단으로 설명해줘"
}'

처음 실행하면 응답이 한 번에 예쁘게 나오지 않을 수 있습니다.

여러 줄의 JSON이 계속 이어서 출력될 수 있는데요. 이건 이상한 오류라기보다, Ollama API가 기본적으로 streaming 응답을 사용하기 때문입니다.

stream 옵션이 중요한 이유

Ollama의 /api/generate는 기본적으로 stream이 켜진 상태로 동작합니다.

stream이 켜져 있으면 모델이 답변을 완성할 때까지 기다렸다가 한 번에 보여주는 것이 아니라, 생성되는 조각을 순서대로 보내줍니다.

그래서 터미널에서는 이런 느낌으로 보일 수 있습니다.

{"model":"qwen3:8b","response":"Ollama","done":false}
{"model":"qwen3:8b","response":" API","done":false}
{"model":"qwen3:8b","response":"는","done":false}
{"model":"qwen3:8b","response":"","done":true}

이 방식은 긴 답변을 받을 때 체감 속도가 좋습니다. 답변이 만들어지는 대로 바로 보이기 때문입니다.

다만 초보자 입장에서는 JSON이 여러 줄로 나와서 조금 당황스러울 수 있습니다. 간단히 테스트하거나 프로그램에서 한 번에 처리하려면 stream을 꺼두는 편이 더 편할 때가 있습니다.

stream false로 한 번에 응답 받기

한 번에 완성된 응답을 받고 싶다면 "stream": false를 넣으면 됩니다.

curl http://localhost:11434/api/generate -d '{
  "model": "qwen3:8b",
  "prompt": "Ollama API를 초보자에게 한 문단으로 설명해줘",
  "stream": false
}'

이렇게 하면 여러 줄로 쪼개진 응답이 아니라, 하나의 JSON 응답으로 받을 수 있습니다.

간단한 테스트에서는 이 방식이 더 보기 편했습니다. 특히 응답 안의 response 값만 확인하고 싶을 때 좋습니다.

Mac에 jq가 설치되어 있다면 아래처럼 응답 문장만 뽑아볼 수도 있습니다.

curl -s http://localhost:11434/api/generate -d '{
  "model": "qwen3:8b",
  "prompt": "Ollama API를 초보자에게 한 문단으로 설명해줘",
  "stream": false
}' | jq -r '.response'

jq가 없다면 이 명령은 안 될 수 있습니다. 그럴 때는 앞의 기본 curl 명령만 사용하셔도 됩니다.

stream true와 false는 언제 쓰면 좋을까요?

구분	stream true	stream false
응답 방식	생성되는 조각을 순서대로 받음	완성된 응답을 한 번에 받음
체감 속도	빠르게 느껴질 수 있음	끝날 때까지 기다려야 함
터미널 가독성	JSON 여러 줄이라 낯설 수 있음	테스트하기 편함
추천 용도	긴 답변, 채팅 UI, 실시간 출력	짧은 테스트, 결과 저장, 간단한 스크립트

처음에는 stream false로 테스트하는 것을 추천합니다.

응답 구조를 이해하기 쉽고, 나중에 Python이나 JavaScript로 연결할 때도 먼저 결과를 확인하기 좋기 때문입니다.

그다음 채팅 화면처럼 답변이 실시간으로 나오는 구조를 만들고 싶다면 stream을 켜고 처리하면 됩니다.

context를 API에서 조절할 수도 있습니다

Ollama API에서는 options 안에 실행 옵션을 넣을 수 있습니다.

예를 들어 context 길이를 줄여서 가볍게 테스트하고 싶다면 num_ctx를 넣어볼 수 있습니다.

curl http://localhost:11434/api/generate -d '{
  "model": "qwen3:8b",
  "prompt": "Mac에서 Ollama가 느릴 때 확인할 것을 5개만 알려줘",
  "stream": false,
  "options": {
    "num_ctx": 4096
  }
}'

context는 모델이 한 번에 참고할 수 있는 문맥 길이에 가깝습니다. 크게 잡으면 긴 문서를 다룰 때 도움이 될 수 있지만, 메모리 부담도 같이 커질 수 있습니다.

그래서 짧은 API 테스트라면 처음부터 큰 context를 잡기보다 작게 시작하는 편이 안전합니다.

Ollama API가 느릴 때 확인할 것

API 호출이 느리다고 해서 항상 API 자체가 문제인 것은 아닙니다.

대부분은 모델 크기, context, 메모리 사용량, 처음 모델을 불러오는 시간과 관련이 있을 수 있습니다.

• 처음 호출만 느린지 확인하기
• 모델 이름이 너무 큰 모델은 아닌지 확인하기
• ollama ps로 GPU 사용 여부 확인하기
• stream false와 stream true를 나눠 테스트하기
• 짧은 prompt로 먼저 테스트하기
• 필요하면 options.num_ctx를 낮춰보기

특히 처음 호출은 모델을 메모리에 올리는 시간이 포함될 수 있습니다. 그래서 첫 호출만 유난히 느리고, 두 번째부터 빨라지는 경우도 있습니다.

ollama ps

ollama ps에서 PROCESSOR가 어떻게 표시되는지도 확인해 보세요. 모델이 GPU에 잘 올라갔는지, 일부가 CPU로 내려갔는지에 따라 체감 속도가 달라질 수 있습니다.

보안상 조심할 부분

Ollama API는 로컬에서 쓰면 편합니다. 하지만 이걸 외부에 열어두는 것은 전혀 다른 이야기입니다.

초보자라면 localhost 또는 127.0.0.1에서만 테스트하는 것을 권합니다.

• 공유기 포트포워딩으로 Ollama 포트를 외부 공개하지 않기
• 회사·공용 네트워크에서 무심코 서버를 열어두지 않기
• API 요청에 비밀번호, 쿠키, 토큰을 넣지 않기
• 터미널 캡처를 올릴 때 사용자 이름과 경로 가리기
• 테스트 prompt에 개인정보를 넣지 않기

로컬 AI라고 해서 무조건 안전한 것은 아닙니다. 내 컴퓨터에서 돌아간다는 장점은 있지만, 어떤 파일과 정보를 prompt에 넣는지는 결국 사람이 조심해야 합니다.

처음 테스트 추천 순서

처음 API 테스트를 한다면 저는 아래 순서가 제일 덜 헷갈린다고 봅니다.

1. ollama list로 모델 이름 확인
2. curl http://localhost:11434로 서버 응답 확인
3. stream false로 짧은 질문 테스트
4. jq가 있으면 response만 뽑아보기
5. 그다음 stream 기본값으로 여러 줄 응답 확인
6. 필요하면 options.num_ctx 테스트

이렇게 하면 “Ollama가 API로도 응답하는구나”라는 감을 잡기 좋습니다.

처음부터 앱을 만들려고 하면 변수도 많고 오류도 많습니다. 먼저 curl로 되는지 확인하고, 그다음 Python이나 JavaScript로 옮기는 편이 더 안전합니다.

정리하면

Ollama API 사용법은 처음 볼 때는 낯설지만, 기본 구조는 단순합니다.

내 Mac에서 Ollama가 실행 중이면 localhost:11434로 요청을 보내고, /api/generate에 모델 이름과 prompt를 넣어 응답을 받습니다.

처음에는 stream false로 한 번에 응답을 받아보는 것이 좋습니다. 그다음 기본 streaming 응답을 확인하면 왜 터미널에 JSON이 여러 줄로 나오는지도 이해하기 쉬워집니다.

그리고 중요한 것 하나요.

API로 호출할 수 있다는 것과, 아무 정보나 넣어도 된다는 것은 전혀 다른 이야기입니다.

처음에는 짧은 테스트 prompt로 시작하시고, 개인정보나 계정 정보는 넣지 않는 쪽으로 연습해 보시면 좋겠습니다.

참고한 공식 자료

• Ollama API 문서 – Generate a response
• Ollama Streaming 문서
• Ollama context length 문서
• Ollama FAQ

함께 보면 좋은 글

아래 글은 이어서 같이 보시면 좋습니다.

• Ollama 설치 후 첫 모델 고르는 법 | Mac 초보자를 위한 로컬 AI 입문
• Ollama 느릴 때 확인할 7가지 | Mac 모델 속도와 메모리 점검 방법
• VS Code Continue에 Ollama 연결하는 법 | Mac 로컬 AI 코딩 도우미 만들기
• qwen3 8B 14B 차이 직접 테스트 | Mac M3 Pro 18GB 속도와 메모리 비교

자주 묻는 질문