OpenWebUI APIの使い方｜自分のモデルでウェブページと会話

OpenWebUI を運用しているなら、いちばん手間のかかる部分はもう終わっています。モデルはセットアップ済みで、APIキーも1か所にまとまっているはずです。自宅サーバーでOllamaを動かし、クラウドプロバイダーを1つか2つつなぎ、自分で調整したカスタムのワークスペースモデルもいくつかある、という方も多いでしょう。

ただ、OpenWebUIは閲覧中のページの中では使えません。読んでいる記事やPDF、ドキュメントについてモデルに質問したいときは、結局その内容をコピーして別のタブに貼り付けることになります。

そこで役立つのがSurfMindです。OpenWebUIは単なるチャット画面ではありません。OpenWebUI API を通じてAPIサーバーとしても動作するので、SurfMindのバックエンドとして使えます。モデルの管理はこれまでどおりOpenWebUIで行い、SurfMindがそのモデルをブラウザから使うためのフロントエンドになります。

このガイドでは、OpenWebUI APIとは何か、SurfMindとどう関わるのか、貼り付けるべき正確なURL、そして実際によく起きるエラーの直し方を解説します。

OpenWebUIとSurfMind：見た目は似ていても役割は別

一見すると、この2つは競合のように見えます。どちらもAIのインターフェースで、多くのLLMプロバイダーに接続でき、モデルとチャットできます。ただし、得意とする用途は異なります。

OpenWebUIはセルフホスト型のAIワークスペース。SurfMindは、いつものブラウザの中で使えるAIです。 特に重要なのは太字の行です。OpenWebUIはAPI経由でモデルを提供できるため、2つを組み合わせて使えるのです。

なぜOpenWebUIをSurfMindに接続するのか？

よくある構成を思い浮かべてみてください。自宅サーバーや小さなVPSでOpenWebUIを動かしていて、その裏側には次のようなものがあります。

• Ollama経由でローカル実行しているLlama、Qwen、Gemma
• クラウドのAPIキー経由で使うGPTやClaudeのモデル
• 自前のGPU上でvLLMが提供しているモデル
• OpenWebUIで作った、それぞれ独自のシステムプロンプトと設定を持つ ワークスペースモデル がいくつか

これらはすべてOpenWebUIのチャット画面から使えます。そこにさらに、ブラウザアシスタントが得意なことも加えたくなるはずです。今見ているページについて質問する、長いスレッドを要約する、複数のタブの情報を比較する、サイトを離れずに返信の下書きを作る、といったことです。

もちろん、すべてのプロバイダーをSurfMindに1つずつ登録し直すことも できます。Ollama、次にOpenAIのキー、次にvLLMのエンドポイント…。でもそれは手間がかかりますし、キーが二重管理になり、せっかく作ったワークスペースモデルも引き継げません。

代わりに、接続を 1つ だけ追加する方法があります。SurfMind → OpenWebUI です。OpenWebUIから見えるすべてのモデルが、SurfMindのモデル選択メニューに表示されます。モデル、ユーザー、権限の管理はこれまでどおりOpenWebUIで行い、SurfMindを使えば、それらをブラウザから直接利用できます。

同じ環境をチームで使う場合にも便利です。チームで1つのOpenWebUIインスタンスを運用していれば、メンバーはそれぞれ自分のAPIキーを作成して、ブラウザからチームのモデルを使えます。権限はOpenWebUIでのものと同じで、プロバイダーのキーそのものを誰かに渡す必要もありません。

ステップ1：OpenWebUIのAPIキーを作成する

APIキーはデフォルトで無効になっているため、初回だけ少し手順があります。

管理者の場合は、APIキーを有効にします。

1. 管理者としてOpenWebUIにログインします。
2. Settings → Admin → Authentication を開きます。
3. API Keys をオンにして、Save をクリックします。

管理者でない場合 は、管理者に API Keys の機能権限を付与してもらってください。管理者は Admin Panel → Users → Groups で、全員向けの Default Permissions か特定のグループに対して設定できます。

続いて、キーを生成します。

1. 左下の プロフィールアイコン をクリックします。
2. Settings → Account を開きます。
3. API keys セクションで、Secrets の横にある Show をクリックします。このセクションはデフォルトで折りたたまれているので、何もないように見えても問題ありません。
4. Create new secret key をクリックし、キーをコピーします。キーは sk- で始まります。

OpenWebUIのAPIキーに関するドキュメント から、知っておきたいポイントをいくつか挙げます。

• キーは1アカウントにつき1つ。 新しいキーを作ると古いキーは置き換えられ、その時点ですぐに使えなくなります。すでに別のツールでキーを使っている場合、SurfMind用に新しく作るとそのツールが動かなくなります。SurfMind専用の非管理者アカウントを用意すれば、この問題は避けられます。
• キーにはあなたのアカウントと同じ権限があります。 キーを作成したアカウントと同じモデルが見え、同じ権限を持ちます。
• JWTトークンは使わないでください。 同じパネルで管理者に表示されるものですが、これはブラウザのセッショントークンで、有効期限があります。

ステップ2：OpenWebUIをSurfMindに追加する

SurfMindでパネル下部のモデル名をクリックし、Show all → Custom → Add Custom Models と進みます。汎用の OpenAI-compatible プリセットを選び、次のように入力します。

OpenWebUIがブラウザと同じコンピューターで動いている場合、ホストは通常 http://localhost:3000（Dockerでよく使われるポート割り当て）か http://localhost:8080（pipやベアメタルでのインストール）です。

• API URL: http://localhost:3000/api/chat/completions
• Models URL: http://localhost:3000/api/models

保存したら、一覧からOpenWebUIのモデルを1つ選び、適当な記事を開いて、SurfMindに要約を頼んでみてください。

パスでよくある2つのミス。 /api/chat/completions で終わる 完全な エンドポイントを貼り付けてください。ホストだけや /api までではいけません。SurfMindのAPI URL欄はパスを自動で補いません。また、/v1 はどこにも付けないでください。/api/v1/chat/completions も /v1/chat/completions も、OpenWebUIのチャットエンドポイントではありません。

トラブルシューティング：「モデルは読み込めるのにチャットが失敗する」

OpenWebUIで最も多く寄せられる報告なので、独立したセクションにしました。モデルのドロップダウンに一覧が表示されているなら、ホスト、キー、ネットワーク経路はすべて正常です。失敗しているのは、チャットのリクエストに固有の何かです。次の順に確認してください。

まずはSurfMindの外でテストします。 ターミナルから curl を1回実行すれば、問題がOpenWebUI側にあるのか、SurfMindの設定にあるのかを切り分けられます。ホスト、キー、モデルidは自分のものに置き換えてください。

curl -X POST https://openwebui.example.com/api/chat/completions \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "llama3.2:latest", "messages": [{"role": "user", "content": "Say hi"}]}'

モデルidは、SurfMindのモデル一覧（または GET /api/models）に表示されているとおり正確に使ってください。これが成功するなら、SurfMindの入力内容を見直しましょう。こちらも失敗する場合は、返ってくるエラーが以下のどの原因に当たるかを示してくれます。

1. チャットのパスが間違っている。 Models URLとAPI URLは別々の欄なので、片方は正しくてもう片方が間違っている、ということが起こります。API URLが正確に /api/chat/completions で終わっていて、/v1 も末尾のスラッシュもタイプミスもないことを確認してください。

2. エンドポイントの制限でチャットがブロックされている。 管理者は API Key Endpoint Restrictions（APIキーで呼び出せるルートの許可リスト）を有効にできます。ここに /api/models は含まれていても /api/chat/completions が含まれていないと、この問題が起き、たいていは 403 が返ります。管理者に /api/chat/completions を追加してもらってください。

3. モデルの設定でストリーミングモードが強制されている。 OpenWebUIには Stream Chat Response という設定があり、モデルごとの詳細パラメーター、または Settings → Admin → Models の管理者デフォルトで指定します。OpenWebUIのドキュメントによると、この設定は クライアントが何を要求したかに関係なく 応答をストリーミングするかどうかを決めます。クライアントが想定していないモードがモデルに強制されていると、クライアントが読み取れない形式で応答が返ってくることがあります。特定のモデルでだけチャットが失敗する場合は、そのモデルのこの設定を確認し、Default に戻してください。

4. リバースプロキシが Authorization ヘッダーを横取りしている。 OpenWebUIの前段に、自前のログインに Authorization を使うゲートウェイ（Basic認証、SSO、APIゲートウェイなど）がある場合、キーはOpenWebUIまで届きません。OpenWebUIはカスタムヘッダー（デフォルトは x-api-key）でもキーを受け付けます。この場合は、SurfMindの API Key Header で x-api-key を選んでください。管理者が CUSTOM_API_KEY_HEADER でヘッダー名を変更している場合は、そのヘッダーをプロキシが通過させる必要があります。

5. モデルidが一致していない。 手入力せずにドロップダウンから選んでください。OpenWebUIでのOllamaモデルのidにはタグが含まれ（llama3.2:latest）、ワークスペースモデルは表示名ではなく、自分で付けたidを使います。

6. OpenWebUIの裏側のプロバイダーが失敗している。 上流のプロバイダーがリクエストを拒否すると、OpenWebUIはそのステータスコードをそのまま返します。429 はプロバイダーのレート制限によるもので、OpenWebUIやSurfMindが原因ではありません。同じモデルをOpenWebUI自身のチャットで試してみてください。そこでも失敗するなら、問題は上流にあります。

その他のエラー早見表

ポート、http と https、ベースURLと完全なエンドポイントなど、あらゆるカスタムエンドポイントに共通する基本ルールは、カスタムAI接続ガイド をご覧ください。

OpenWebUI、SurfMind、それとも両方？

どちらか一方を選ぶものではありません。

• OpenWebUIだけ が向いているのは、AIを使う場面の大半が専用タブでの長い会話である場合です。ナレッジベースのドキュメントとのチャット、パイプラインの実行、チームのモデル管理などです。
• SurfMindだけ が向いているのは、AIを使う場面の大半が画面に表示されている内容から始まり、プロバイダーや Ollama のようなローカルランナーに直接つなぐので十分な場合です。
• 両方 を使うのが理にかなっているのは、OpenWebUIの環境づくりに手間をかけてきて、同じ設定を二度せずにすべてのページで使いたい場合です。

役割分担はシンプルです。OpenWebUIがモデルを管理し、SurfMindがそれをブラウザで活かします。

よくある質問

OpenWebUIにAPIはありますか？ あります。OpenWebUI APIは、Bearerトークンで認証するREST APIです。多くのツールで必要になるエンドポイントは2つで、モデル一覧を取得する GET /api/models と、OpenAI形式のリクエストを受け付けるチャット用の POST /api/chat/completions です。

OpenWebUI APIはOpenAI互換ですか？ リクエストとレスポンスの形式は互換です。ただしパスは標準のものではなく、OpenWebUIは /v1/chat/completions ではなく /api/chat/completions を使います。SurfMindのように完全なエンドポイントURLを指定できるクライアントであれば利用できます。

OpenWebUIのAPIキーはどこにありますか？ Settings → Account → API keys を開き、Show をクリックしてから Create new secret key をクリックします。このセクションが見当たらない場合は、管理者が Settings → Admin → Authentication で API Keys を有効にし、あなたのアカウントにAPI Keysの権限を付与する必要があります。

OpenWebUIのワークスペースモデルをSurfMindで使えますか？ 使えます。ワークスペースモデルは、ほかのモデルと同じように /api/models で一覧に表示されます。呼び出すと、OpenWebUIが保存済みの設定を適用します。

OpenWebUIを接続すると、データがSurfMindのサーバーに送られますか？ カスタムエンドポイントの場合、SurfMindは設定したURL、つまりここではOpenWebUIのサーバーにリクエストを送ります。その後、OpenWebUIのサーバーが選択したモデルに転送します。そのモデルがローカルで動いていれば、ページの内容は自分が管理するハードウェアの外に出ません。

無料ですか？ はい。SurfMindのカスタムエンドポイントは無料で、こちらで利用回数の上限を設けることもありません。かかるのは利用しているプロバイダーの料金だけで、ローカルモデルなら0円です。

それでも解決しない場合

curl のテストは成功するのに、SurfMindでOpenWebUIのモデルとチャットできない場合は、wave@surfmind.ai までメールでお問い合わせください。その際、API URL（キーは除く）、HTTPステータスコード、そして失敗するのが一部のモデルかすべてのモデルかを添えてください。セルフホスト環境は構成がさまざまなので、こうした報告がSurfMindをよりスムーズに動かすための大きな助けになります。

SurfMindを入手する →