CurlとHTTPをUnslothに接続

curl（または任意のHTTPクライアント）でUnslothのAPIにアクセスするためのガイド。すべてのエンドポイントと機能について、コピペ可能なレシピ付きです。

Unsloth は、Unsloth が起動したポート上の同じベース URL で、OpenAI/Anthropic 互換の3つのワイヤ形式を公開します。いずれも1つの Authorization: Bearer sk-unsloth-… ヘッダーを使い、設定したかどうかに応じて JSON または SSE を返します stream. このページではレシピをエンドポイント（/v1/chat/completions, /v1/messages, /v1/responses, /v1/models)でグループ化し、最後に Unsloth の組み込みの共通セクションで終わります サーバー側ツール。これらはすべてのチャットエンドポイントで動作します。

どの URL / キー / モデル名を使えばよいかわからない場合は、まず API 概要を読んでください。Unsloth の起動、モデルの読み込み、そして sk-unsloth-… キー。

🔑 認証

すべてのリクエストには Authorization ヘッダー:

Authorization: Bearer sk-unsloth-xxxxxxxxxxxx

キーがシェル履歴に残らないようにするには、キーを一度 export し、環境変数を参照してください:

export UNSLOTH_STUDIO_AUTH_TOKEN=sk-unsloth-xxxxxxxxxxxx

以下のスニペットでは、キーを次のようにインラインで記述しています: sk-unsloth-xxxxxxxxxxxx わかりやすさのためです。実際には、次のものに置き換えてください: $UNSLOTH_STUDIO_API_KEY.

📋 読み込まれているモデルを一覧表示

curl http://localhost:8888/v1/models \
  -H "Authorization: Bearer sk-unsloth-xxxxxxxxxxxx"

レスポンス:

{
  "object": "list",
  "data": [
    {"id": "unsloth/gemma-3-27b-it-GGUF", "object": "model", "owned_by": "local"}
  ]
}

次のものを使用してください: id フィールドは、リクエストで次のものが必要な場合に使用します: "model" の値（または opencode のようなクライアントが次のものを求める場合） モデル ID).

💬 Chat Completions（/v1/chat/completions)

OpenAI Chat Completions の方言です。互換性の範囲が最も広く、OpenAI SDK、opencode、Cursor、Continue、Cline、Open WebUI、SillyTavern、およびほとんどの OpenAI 互換ツールで動作します。

基本リクエスト

curl http://localhost:8888/v1/chat/completions \
  -H "Authorization: Bearer sk-unsloth-xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "default",
    "messages": [{"role": "user", "content": "こんにちは"}]
  }'

ストリーミング

追加して "stream": true すると、レスポンスは Server-Sent Events（text/event-stream）に切り替わります。 curl に、バイトが届くたびにフラッシュするよう指示します。 --no-buffer (-N):

curl -N http://localhost:8888/v1/chat/completions \
  -H "Authorization: Bearer sk-unsloth-xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen-local",
    "messages": [{"role": "user", "content": "ローカルで実行される LLM についての俳句を書いてください。"}],
    "stream": true
  }'

レスポンスの各行は次のようになります: data: {"choices":[{"delta":{"content":"..."}}]}、最後は data: [DONE].

画像（vision）

画像を次のものとして添付します: image_url ユーザーメッセージ内の content 部分。URL は HTTPS または base64 データ: URI:

# ローカルファイルを base64 として埋め込む（簡潔さのため省略）
IMG=$(base64 -w 0 test.jpg)

cat > /tmp/request.json <<EOF
{
  "model":"default",
  "messages":[{"role":"user","content":[
    {"type":"text","text":"画像を説明してください。"},
    {"type":"image_url","image_url":{"url":"data:image/jpeg;base64,$IMG"}}
  ]}],
  "max_tokens":200,
  "stream":false
}
EOF

curl http://localhost:8888/v1/chat/completions \
  -H "Authorization: Bearer sk-unsloth-xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d @/tmp/request.json

読み込まれたモデルはマルチモーダルである必要があります。テキスト専用モデルを読み込むと、リクエストの構造上は成功しますが、モデルは画像を処理できません。

関数呼び出し（OpenAI tools）

OpenAI 形式の tools および（必要に応じて） tool_choice。クライアントが各ツール呼び出しを実行し、次のターンで結果を返します。

curl http://localhost:8888/v1/chat/completions \
  -H "Authorization: Bearer sk-unsloth-xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model":"default",
    "input":[{"role":"user","content":"パリの天気はどうですか?"}],
    "tools":[{
      "type":"function",
      "name":"get_weather",
      "description":"都市の現在の天気を取得します。",
      "parameters":{
        "type":"object",
        "properties":{"city":{"type":"string"}},
        "required":["city"]
      }
    }],
    "tool_choice":"required"
  }' | jq '.output, .usage'

📨 Anthropic Messages（/v1/messages)

Claude Code、Anthropic SDK、OpenClaw、その他 Messages API を話すクライアントで使われる、Unsloth の Anthropic 互換方言です。

基本リクエスト

curl http://localhost:8888/v1/messages \
  -H "Authorization: Bearer sk-unsloth-xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "default",
    "max_tokens": 1024,
    "messages": [{"role": "user", "content": "こんにちは"}]
  }'

max_tokens は次で必須です: /v1/messages （次では省略可能です /v1/chat/completions).

ストリーミング

curl -N http://localhost:8888/v1/messages \
  -H "Authorization: Bearer sk-unsloth-xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen-local",
    "max_tokens": 1024,
    "messages": [{"role": "user", "content": "LoRA を2文で説明してください。"}],
    "stream": true
  }'

イベントは Anthropic の SSE 形式に従います: message_start, content_block_start, content_block_delta, content_block_stop, message_delta, message_stop、さらに Unsloth 独自の tool_result イベントがサーバー側ツールの出力用にあります。

画像（vision）

Anthropic 形式の画像コンテンツは source ブロックと base64 データを使用します:

IMG=$(base64 -w 0 test.jpg)

cat > /tmp/request.json <<EOF
{
  "messages":[{"role":"user","content":[
    {"type":"text","text":"画像を説明してください。"},
    {"type":"image","source":{"type":"base64","media_type":"image/jpeg","data":"$IMG"}}
  ]}],
  "max_tokens":200,
  "stream":true
}
EOF

curl -s http://3.128.175.236:8888/v1/messages \
  -H "Authorization: Bearer sk-unsloth-xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d @/tmp/request.json

ツール呼び出し（Anthropic tools）

curl http://localhost:8888/v1/messages \
  -H "Authorization: Bearer sk-unsloth-xxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen-local",
    "max_tokens": 1024,
    "messages": [{"role": "user", "content": "東京の天気はどうですか?"}],
    "tools": [
      {
        "name": "get_weather",
        "description": "都市の現在の天気を取得します",
        "input_schema": {
          "type": "object",
          "properties": {
            "city": {"type": "string"}
          },
          "required": ["city"]
        }
      }
    ],
    "tool_choice": {"type": "auto"}
  }'

tool_choice 値は OpenAI 方言では次のように対応します: Anthropic auto → OpenAI auto、Anthropic any → OpenAI required、Anthropic {type: "tool", name: "x"} → OpenAI {type: "function", function: {name: "x"}}、Anthropic none → OpenAI none.

🧬 Responses（/v1/responses)

Unsloth は新しい OpenAI Responses API, Codex やその他の最近の OpenAI クライアントが採用しているプロトコルです。

curl http://localhost:8888/v1/responses \
  -H "Authorization: Bearer sk-unsloth-xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen-local",
    "input": "1文の挨拶を書いてください。"
  }'

ストリーミングは Chat Completions と同じように動作します。追加して "stream": true し、次のものと組み合わせます: -N.

🧰 Unsloth サーバー側ツール（省略形）

クライアント側の関数呼び出しに加えて、Unsloth は実行できます Python, bash、および ウェブ検索 をサーバー側で実行し、結果をカスタムな tool_result イベントとしてストリーミングで返します。これが、Unsloth を箱から出してすぐに「本物の」エージェントのように感じさせる機能で、クライアントを通してツール呼び出しを往復させる必要がありません。

次の追加フィールドを渡すことで有効にします: いずれかの /v1/chat/completions または /v1/messages:

フィールド	型	注記
enable_thinking	boolean	false で思考を無効にします。 true デフォルトでは
enable_tools	boolean	true でサーバー側ツールの実行を有効にします。
enabled_tools	array<string>	モデルが呼び出せるツールです。サポート対象: python, bash, web_search.
session_id	string	任意。ツールの状態（例: Python カーネル）を呼び出し間で保持します。

思考モード

思考モードはデフォルトで有効です。

curl http://localhost:8888/v1/chat/completions \
  -H "Authorization: Bearer sk-unsloth-xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "default",
    "messages": [{"role": "user", "content": "量子トンネル効果を1文で要約してください"}],
    "stream": false,
  }'

モデルは回答を提供する前に思考します。

思考を無効にするには次を渡します: enable_thinking: false をリクエストに含めてください。モデルは最初に思考せずに回答します。

Python の実行

curl http://localhost:8888/v1/chat/completions \
  -H "Authorization: Bearer sk-unsloth-xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen-local",
    "messages": [{"role": "user", "content": "123 * 456 はいくつですか？コードを使って計算してください。"}],
    "stream": false,
    "enable_tools": true,
    "enabled_tools": ["python"],
    "session_id": "my-session"
  }'

ウェブ検索 + Python（ストリーミング）

curl http://localhost:8888/v1/chat/completions \
  -H "Authorization: Bearer sk-unsloth-xxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen-local",
    "messages": [{"role": "user", "content": "Python 3.13 の機能を検索してください"}],
    "stream": true,
    "enable_tools": true,
    "enabled_tools": ["web_search", "python"],
    "session_id": "my-session"
  }'

同様に /v1/messages

同じ省略形は Anthropic Messages エンドポイントでも使えます:

curl http://localhost:8888/v1/messages \
  -H "Authorization: Bearer sk-unsloth-xxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen-local",
    "max_tokens": 1024,
    "messages": [{"role": "user", "content": "Python 3.13 の機能を検索してください"}],
    "stream": true,
    "enable_tools": true,
    "enabled_tools": ["web_search", "python"],
    "session_id": "my-session"
  }'

Unsloth は独自の tool_result SSE イベントを、標準の Anthropic / OpenAI イベントタイプに加えてストリーミングします。モデルは次のターンで各ツールの出力を受け取ります。

❔ トラブルシューティング

401 Unauthorized - 次の Authorization ヘッダーがないか、キーが間違っています。次を再確認してください: Authorization: Bearer sk-unsloth-….

curl ストリーミング要求で停止する - 追加して -N （同じものです --no-buffer）。これがないと、 curl SSE ストリームをバッファリングするため、最後まで何も表示されません。

Base64 エンコードは OS によって異なります - Linux の base64 はデフォルトで改行を挿入しますが、macOS / BSD ではそうしません。次を使用してください: base64 -w 0 Linux では、 base64 macOS では、または出力を次へパイプしてください: tr -d '\n'.

シェルでの JSON エスケープ - ヒアドキュメント（-d @file.json）は、本文が複雑になるとインライン文字列よりもすっきりします。例: curl ... -d @body.json.

max_tokens でエラーになります /v1/messages - Anthropic 方言では必須です。次を追加してください: "max_tokens": 1024 （または任意の上限）。

エンドポイントレベルの問題（モデルが読み込まれない、接続が切れる、ポートが違う）については、API 概要ページを参照してください。

任意: サーバーのデフォルトを調整

サーバー起動時に次を使ってデフォルト動作をカスタマイズできます: unsloth run.

# カスタムのデフォルトでサーバーを起動
unsloth run \
  --model unsloth/Qwen3-1.7B-GGUF \
  --reasoning off \
  --temp 0.6 \
  -p 8888

次を使用してください: --reasoning off で思考をオフにするか、 --reasoning on で推論対応モデルの思考をオンにします。

# ローカルネットワークで API を公開
unsloth run \
  --model unsloth/Qwen3-1.7B-GGUF \
  -H 0.0.0.0 \
  -p 8888

これによりサーバーは次で起動します: 0.0.0.0:8888。これにより、ローカルネットワーク上の他のデバイスが接続できるようになります。

リクエストごとに設定を上書き

各 API リクエストで生成設定を直接上書きすることもできます。

curl http://localhost:8888/v1/chat/completions \
  -H "Authorization: Bearer $UNSLOTH_STUDIO_AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "default",
    "messages": [
      {
        "role": "user",
        "content": "ローカル AI についての短い詩を書いてください。"
      }
    ],
    "temperature": 0.8,
    "top_p": 0.9,
    "max_tokens": 512
  }'

次のようなリクエストレベルの値は temperature, top_p, max_tokens、および stream そのリクエストのサーバーデフォルトを上書きします。