OpenAI 호환(OpenAI compatibility)

이미 OpenAI API를 쓰는 애플리케이션이 있다면, Ollama가 OpenAI API의 일부 부분과 호환되어 기존 코드를 그대로 연결할 수 있어요. Django 같은 프레임워크에서 쓰던 base_url만 Ollama 주소로 바꾸면 되는 거죠.

출처: 공식문서

사용법

간단한 `/v1/chat/completions` 예시

base_url을 http://localhost:11434/v1/로, api_key는 아무 값이나 넣으면 됩니다(필수지만 무시됩니다).

Python:

from openai import OpenAI

client = OpenAI(
    base_url='http://localhost:11434/v1/',
    api_key='ollama',  # required but ignored
)

chat_completion = client.chat.completions.create(
    messages=[
        {
            'role': 'user',
            'content': 'Say this is a test',
        }
    ],
    model='gpt-oss:20b',
)
print(chat_completion.choices[0].message.content)

JavaScript:

import OpenAI from "openai";

const openai = new OpenAI({
  baseURL: "http://localhost:11434/v1/",
  apiKey: "ollama" // required but ignored
});

const chatCompletion = await openai.chat.completions.create({
  messages: [{ role: "user", content: "Say this is a test" }],
  model: "gpt-oss:20b",
});

console.log(chatCompletion.choices[0].message.content);

cURL:

curl -X POST http://localhost:11434/v1/chat/completions \
-H "Content-Type: application/json" \
-d '{
  "model": "gpt-oss:20b",
  "messages": [{ "role": "user", "content": "Say this is a test" }]
}'

간단한 `/v1/responses` 예시

Python:

from openai import OpenAI

client = OpenAI(
    base_url='http://localhost:11434/v1/',
    api_key='ollama',  # required but ignored
)

responses_result = client.responses.create(
  model='qwen3:8b',
  input='Write a short poem about the color blue',
)
print(responses_result.output_text)

JavaScript:

import OpenAI from "openai";

const openai = new OpenAI({
  baseURL: "http://localhost:11434/v1/",
  apiKey: "ollama" // required but ignored
});

const responsesResult = await openai.responses.create({
  model: "qwen3:8b",
  input: "Write a short poem about the color blue",
});

console.log(responsesResult.output_text);

cURL:

curl -X POST http://localhost:11434/v1/responses \
-H "Content-Type: application/json" \
-d '{
  "model": "qwen3:8b",
  "input": "Write a short poem about the color blue"
}'

`/v1/chat/completions`와 비전 예시

OpenAI 호환 API로도 비전 모델을 쓸 수 있어요. content를 배열로 넘기고, 텍스트 부분과 image_url 부분을 함께 담습니다. 이미지는 base64로 인코딩된 데이터 URI로 전달합니다(아래 예시의 base64 문자열은 간결성을 위해 축약했어요).

Python:

from openai import OpenAI

client = OpenAI(
    base_url='http://localhost:11434/v1/',
    api_key='ollama',  # required but ignored
)

response = client.chat.completions.create(
    model='qwen3-vl:8b',
    messages=[
        {
            'role': 'user',
            'content': [
                {'type': 'text', 'text': "What's in this image?"},
                {
                    'type': 'image_url',
                    'image_url': 'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAG0AAABmCAYAAADBPx+V...',  # truncated base64 sample
                },
            ],
        }
    ],
    max_tokens=300,
)
print(response.choices[0].message.content)

JavaScript:

import OpenAI from "openai";

const openai = new OpenAI({
  baseURL: "http://localhost:11434/v1/",
  apiKey: "ollama" // required but ignored
});

const response = await openai.chat.completions.create({
  model: "qwen3-vl:8b",
  messages: [
    {
      role: "user",
      content: [
        { type: "text", text: "What's in this image?" },
        {
          type: "image_url",
          image_url: "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAG0AAABmCAYAAADBPx+V...", // truncated base64 sample
        },
      ],
    },
  ],
});
console.log(response.choices[0].message.content);

cURL:

curl -X POST http://localhost:11434/v1/chat/completions \
-H "Content-Type: application/json" \
-d '{
  "model": "qwen3-vl:8b",
  "messages": [{ "role": "user", "content": [{"type": "text", "text": "What is this an image of?"}, {"type": "image_url", "image_url": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAG0AAABmCAYAAADBPx+V..."}] }]
}'

엔드포인트

`/v1/chat/completions`

지원 기능:

채팅 완성(chat completions)
스트리밍
JSON 모드
재현 가능한 출력(reproducible outputs)
비전
도구(Tools)
추론/씽킹 제어 (씽킹 모델용)
Logprobs

지원 요청 필드:

model
messages
- 텍스트 content
- 이미지 content
  - base64 인코딩 이미지
  - 이미지 URL
- content 파트 배열
frequency_penalty
presence_penalty
response_format
seed
stop
stream
stream_options
- include_usage
temperature
top_p
max_tokens
tools
reasoning_effort ("high", "medium", "low", "max", "none")
reasoning
- effort ("high", "medium", "low", "max", "none")
tool_choice
logit_bias
user
n

`/v1/completions`

지원 기능:

완성(completions)
스트리밍
JSON 모드
재현 가능한 출력
Logprobs

지원 요청 필드:

model
prompt
frequency_penalty
presence_penalty
seed
stop
stream
stream_options
- include_usage
temperature
top_p
max_tokens
suffix
best_of
echo
logit_bias
user
n

참고:

prompt는 현재 문자열만 받습니다.

`/v1/models`

참고:

created는 모델이 마지막으로 수정된 시각에 해당합니다.
owned_by는 ollama 사용자 이름에 해당하며 기본값은 "library"입니다.

`/v1/models/{model}`

참고:

created는 모델이 마지막으로 수정된 시각에 해당합니다.
owned_by는 ollama 사용자 이름에 해당하며 기본값은 "library"입니다.

`/v1/embeddings`

지원 요청 필드:

model
input
- string
- string 배열
- token 배열
- token 배열의 배열
encoding format
dimensions
user

`/v1/responses`

참고: Ollama v0.13.3에서 추가됨

Ollama는 OpenAI Responses API를 지원합니다. 상태를 유지하지 않는(non-stateful) 형태만 지원합니다(즉 previous_response_id나 conversation은 지원하지 않아요).

지원 기능:

스트리밍
도구(함수 호출)
추론 요약 (씽킹 모델용)
상태 유지 요청

지원 요청 필드:

model
input
instructions
tools
stream
temperature
top_p
max_output_tokens
previous_response_id (stateful v1/responses 미지원)
conversation (stateful v1/responses 미지원)
truncation

모델

모델을 쓰기 전에 로컬로 받아두세요. ollama pull:

ollama pull llama3.2

기본 모델 이름

gpt-3.5-turbo 같은 기본 OpenAI 모델 이름에 의존하는 도구가 있다면, ollama cp로 기존 모델 이름을 임시 이름으로 복사하면 돼요.

ollama cp llama3.2 gpt-3.5-turbo

이후 model 필드에 이 새 모델 이름을 지정할 수 있습니다.

curl http://localhost:11434/v1/chat/completions \
    -H "Content-Type: application/json" \
    -d '{
        "model": "gpt-3.5-turbo",
        "messages": [
            {
                "role": "user",
                "content": "Hello!"
            }
        ]
    }'

컨텍스트 크기 설정

OpenAI API에는 모델의 컨텍스트 크기를 설정하는 방법이 없어요. 컨텍스트 크기를 바꿔야 한다면 다음과 같은 Modelfile을 만들고:

FROM <some model>
PARAMETER num_ctx <context size>

ollama create mymodel 명령으로 새 모델을 만든 뒤, API를 업데이트된 모델 이름으로 호출합니다:

curl http://localhost:11434/v1/chat/completions \
    -H "Content-Type: application/json" \
    -d '{
        "model": "mymodel",
        "messages": [
            {
                "role": "user",
                "content": "Hello!"
            }
        ]
    }'

더 알아보기 (Learn more)

Anthropic compatibility — Anthropic Messages API 호환
Structured outputs — response_format으로 구조화 출력

OpenAI 호환(OpenAI compatibility)