Ollama REST API プログラミング接続

Ollama はインストール後、ローカルの11434ポートで一連のREST APIを提供し、テキスト生成、対話、ベクトル埋め込み、モデル管理をカバーし、OpenAI、Anthropicの2つの互換プロトコルを提供します。

本記事では、コアインターフェースを一つずつ詳しく解説します。リクエスト構造、ストリーミング処理、使用量統計、エラーハンドリングをカバーし、あらゆる言語からローカルモデルに接続できるようにします。


2つのベースURLと認証方法

Ollama の API にはローカルとクラウドの2つのエントリがあり、認証ルールが異なります。

Ollama API 全景:调用方、服务端点、本地模型与 Cloud

入口Base URL認証
ローカルサービスhttp://localhost:11434/api認証不要
ローカルサービス(互換プロトコル)http://localhost:11434/v1認証不要、api_key は任意の値を入力
Ollama Cloudhttps://ollama.com/apiAuthorization: Bearer + API Key

ローカルサービスはデフォルトで認証不要で、すぐに使用できます。ollama.com のクラウドAPIに直接接続する場合は、公式サイトの設定ページでAPI Keyを作成し、リクエストヘッダーに設定してください。


テキスト生成:/api/generate

generate は最も基本的なシングルターン生成インターフェースで、モデル名とプロンプトを渡すだけです:

例

curl http://localhost:11434/api/generate -d '{
  "model": "qwen3.5",
"prompt": "サンプル を一言で紹介してください",
  "stream": false
}'

stream を false に設定すると、単一のJSONオブジェクトが返されます:

{
  "model": "qwen3.5",
  "created_at": "2026-08-29T03:20:00.499127Z",
  "response": "サンプル是一个面向编程初学者的免费中文教程网站。",
  "done": true,
  "total_duration": 10706818083,
  "load_duration": 6338219291,
  "prompt_eval_count": 26,
  "prompt_eval_duration": 130079000,
  "eval_count": 42,
  "eval_duration": 4232710000
}

一般的なパラメータは次のとおりです:

パラメータ説明
model必須、モデル名
promptプロンプト;空にするとモデルのプリロードに使用できます
streamデフォルトは true でストリーミング返却;false の場合は一度に完全な結果を返します
systemシステムプロンプトを一時的に指定し、Modelfile の設定を上書きします
options生成パラメータオブジェクト(temperature、num_ctx など。Modelfile パラメータと同じ)
format"json" または完全な JSON Schema、構造化出力を強制
keep_aliveリクエスト後のモデル常駐時間。"10m" など、-1 は常駐、0 は即時アンロード
rawtrue の場合、テンプレートの組み立てをスキップし、提供した完全なプロンプトを直接使用します
suffixモデル出力の後に続けるテキスト。テキスト補完シナリオに使用
imagesbase64 画像配列。マルチモーダルモデルと組み合わせて使用

実用的なヒントが2つあります。空のプロンプトを送信するとモデルをメモリにプリロードでき、最初のリクエストの読み込み待ちを解消できます。keep_alive を 0 に設定し、空のプロンプトと組み合わせると、モデルを即座にアンロードしてビデオメモリを解放できます。

例

# モデルをプリロード(内容を生成しない)
curl http://localhost:11434/api/generate -d '{"model": "qwen3.5"}'

# モデルを即時アンロードし、ビデオメモリを解放
curl http://localhost:11434/api/generate -d '{"model": "qwen3.5", "keep_alive": 0}'

対話生成:/api/chat

chat はマルチターン対話インターフェースで、メッセージ履歴は呼び出し側が自分で管理します。これが generate との本質的な違いです。

例

curl http://localhost:11434/api/chat -d '{
  "model": "qwen3.5",
  "messages": [
{ "role": "user", "content": "Python とは何ですか?" },
{ "role": "assistant", "content": "初心者向けの中国語チュートリアルサイトです。" },
{ "role": "user", "content": "それは無料ですか?一言で答えてください" }
  ],
  "stream": false
}'

メッセージオブジェクトがサポートするフィールド:

フィールド説明
rolesystem / user / assistant / tool の4つのロール
contentメッセージの内容
images任意、base64 画像リスト(マルチモーダルモデル)
thinking任意、思考モデルの推論プロセス(think パラメータと組み合わせて)
tool_calls任意、モデルリクエストが呼び出すツールリスト(ツール呼び出しの章で実践)

マルチターン対話の正しい方法:モデルが毎回返す assistant メッセージを messages 配列に追加し、次の質問と一緒に送信します。これでモデルは完全なコンテキストを「記憶」できます。

messages は完全にあなたが管理するため、履歴をデータベースに永続化したり、要約に圧縮したり、セッションをまたいで復元したりできます——第5編で言及した「コマンドライン終了で記憶喪失」の問題は、ここで工学的な解決策が得られます。


ベクトル埋め込み:/api/embed

embed インターフェースはテキストをベクトルに変換し、RAG とセマンティック検索の原料工場です。

例

# 単一テキスト
curl http://localhost:11434/api/embed -d '{
  "model": "embeddinggemma",
"input": "サンプル はプログラミングチュートリアルサイトです"
}'


# バッチ:input に配列を渡すと、一度に複数のベクトルを返します
curl http://localhost:11434/api/embed -d '{
  "model": "embeddinggemma",
"input": ["1つ目のテキスト", "2つ目のテキスト", "3つ目のテキスト"]
}'

レスポンスの embeddings は2次元配列で、各ベクトルは L2 正規化(単位長)済みのため、コサイン類似度で直接比較できます。

注目すべき2つのパラメータ:dimensions は出力ベクトルの次元を指定できます(モデルが対応していれば次元を減らしてストレージを節約できます)。truncate はデフォルトで true で、長すぎるテキストを自動的に切り詰めます。false に設定すると、長すぎる場合にエラーになります。


ストリーミングと非ストリーミング:レスポンスの処理方法

生成系インターフェースはデフォルトでストリーミング返却され、形式は NDJSON です。各行が独立した JSON オブジェクトになります。

{"model":"qwen3.5","created_at":"...","response":"サンプル","done":false}
{"model":"qwen3.5","created_at":"...","response":"(サンプル)","done":false}
{"model":"qwen3.5","created_at":"...","response":"是编程初学者的入门网站。","done":false}
{"model":"qwen3.5","created_at":"...","response":"","done":true,"done_reason":"stop"}

クライアントは行ごとに読み取り、response フィールドを連結することで完全な回答になります。連結処理はリアルタイムでUIに描画できます。

2つのモードの使い分け:

モード利点適用シナリオ
ストリーミング(デフォルト)最初の文字の遅延が低く、リアルタイム表示が可能チャットインターフェース、長文生成
非ストリーミング stream:false一度に完全な結果を取得でき、処理が簡単バッチ処理、構造化出力、スクリプト呼び出し

ストリーミングモードでは、出力の途中でエラーが発生する可能性があります。この場合、HTTPステータスコードは変更できないため、エラーはデータストリームの末尾に {"error": "..."} という1行として現れます。クライアントは解析時にこの行を確認する必要があります。


使用量統計とエラーハンドリング

各生成レスポンスの末尾にはパフォーマンス統計フィールドがあり、推論コストを評価するための一次データです。

フィールド意味
total_durationリクエスト総所要時間(ナノ秒)
load_durationモデル読み込み所要時間(最初のリクエストで顕著)
prompt_eval_count入力で消費されたトークン数
prompt_eval_duration入力処理所要時間
eval_count出力で生成されたトークン数
eval_duration出力生成所要時間

生成速度(token/s)の計算式:eval_count / eval_duration * 10^9。各フィールドの時間単位はナノ秒です。

エラーハンドリングについては、APIは標準のHTTPステータスコードで結果を表します:

ステータスコード意味
200成功
400リクエストエラー(パラメータ不足、JSON不正など)
404モデルが存在しない(最初に ollama pull を実行するか、名前を確認してください)
429リクエストが頻繁すぎてレート制限
500サーバー内部エラー
502ゲートウェイエラー(例:クラウドモデルに到達できない)

エラーレスポンスボディは {"error": "エラー説明"} という構造に固定されており、クライアントは error フィールドを統一的に取得するだけで済みます。


モデル管理API概要

コマンドラインでできるモデル管理には、すべてAPIが対応しており、管理バックエンドや自動化スクリプトに適しています。

エンドポイントメソッド用途
/api/tagsGETローカルモデルの一覧表示(パラメータ数、量子化レベルを含む)
/api/showPOSTモデルの詳細、能力、テンプレートの表示
/api/pullPOSTモデルのプル、ダウンロード進捗をストリーミング返却
/api/pushPOSTモデルをモデルライブラリにプッシュ
/api/copyPOSTモデルのコピー(source / destination)
/api/deleteDELETEモデルの削除
/api/createPOSTモデルの作成(量子化を含む、Modelfile の能力に対応)
/api/psGET現在ロードされているモデルとビデオメモリ使用量の表示
/api/versionGETOllama バージョンの確認

/api/tags を例にとると、レスポンスには各モデルの仕様詳細が含まれます:

{
  "models": [
    {
      "name": "qwen3.5:latest",
      "size": 6600000000,
      "details": {
        "family": "qwen3.5",
        "parameter_size": "9B",
        "quantization_level": "Q4_K_M"
      }
    }
  ]
}

quantization_level、parameter_size などのフィールドは、モデルセレクターインターフェースの作成に直接使用できます。


OpenAI互換インターフェース

既存の OpenAI アプリケーションをローカルモデルに切り替える場合、通常は base_url を変更するだけで済みます。

例

curl http://localhost:11434/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen3.5",
"messages": [{ "role": "user", "content": "サンプル を一言で紹介してください" }]
  }'

互換範囲は5つのエンドポイントをカバーします:

エンドポイント説明
/v1/chat/completionsチャット補完。ストリーミング、ビジョン、ツール、JSON モードに対応
/v1/completionsテキスト補完
/v1/responsesResponses API(ステートレスモード)
/v1/embeddingsベクトル埋め込み
/v1/modelsモデル一覧

頻出する2つの相違点に注意してください:

1つ目:OpenAI プロトコルには num_ctx の概念がありません。コンテキストを変更する必要がある場合は、まず PARAMETER num_ctx を持つモデルを作成し、新しい名前で呼び出します(第7回の Modelfile または cp による名前の借用のいずれでも構いません)。

2つ目:一部のフィールドは現在サポートされていません:tool_choice、logit_bias、n、logprobs など。移行前にマニュアルのサポート一覧を確認することをお勧めします。


Anthropic互換インターフェース

Ollama も Anthropic Messages API 互換レイヤーを提供しているため、Claude Code などのツールはローカルモデルを直接使用できます。

例

curl http://localhost:11434/v1/messages \
  -H "Content-Type: application/json" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "qwen3.5",
    "max_tokens": 1024,
"messages": [{ "role": "user", "content": "サンプル を一言で紹介してください" }]
  }'

Claude Code のようなツールを接続する場合、2つの環境変数を設定するだけで済みます:

例

export ANTHROPIC_AUTH_TOKEN=ollama
export ANTHROPIC_BASE_URL=http://localhost:11434
claude --model qwen3.5

注意すべき機能の制限:tool_choice の強制指定、プロンプトキャッシュ、バッチAPI、PDF入力などの Anthropic 機能は現在サポートされていません。トークン数は近似値です。

その他の拡張