将 Curl 和 HTTP 连接到 Unsloth

使用 curl（或任何 HTTP 客户端）访问 Unsloth API 的指南，包含每个端点和功能都可直接复制粘贴的示例。

Unsloth 在 Unsloth 启动时所使用端口的同一基础 URL 上公开了三种与 OpenAI/Anthropic 兼容的线协议格式。它们都接受一个 Authorization: Bearer sk-unsloth-… 标头，并根据你是否设置了 stream来返回 JSON 或 SSE。 本页按端点对这些用法进行分组（/v1/chat/completions, /v1/messages, /v1/responses, /v1/models），并在最后提供一个关于 Unsloth 内置 服务端工具的共享章节，它们可在所有聊天端点中使用。

如果你不确定该使用什么 URL / 密钥 / 模型名称，请先阅读 API 概览。它会带你完成启动 Unsloth、加载模型以及创建一个 sk-unsloth-… 密钥。

🔑 身份验证

每个请求都需要一个 Authorization 标头：

Authorization: Bearer sk-unsloth-xxxxxxxxxxxx

为了避免密钥出现在你的 shell 历史记录中，请导出一次密钥并引用该环境变量：

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).

💬 聊天补全（/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": "Hello"}]
  }'

流式传输

添加 "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].

图像（视觉）

将图像作为一个 image_url 内容部分附加到用户消息中。URL 可以是 HTTPS，也可以是 base64 data: 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)

Unsloth 与 Anthropic 兼容的方言，被 Claude Code、Anthropic SDK、OpenClaw 以及任何使用 Messages API 的客户端所使用。

基本请求

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": "Hello"}]
  }'

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。"}],
    "stream": true
  }'

事件遵循 Anthropic 的 SSE 结构： message_start, content_block_start, content_block_delta, content_block_stop, message_delta, message_stop，再加上 Unsloth 自定义的 tool_result 事件，用于服务端工具输出。

图像（视觉）

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": "写一句问候语。"
  }'

流式传输的工作方式与 Chat Completions 相同。添加 "stream": true 并通过以下方式管道传递 -N.

🧰 Unsloth 服务端工具（简写）

除了客户端侧函数调用之外，Unsloth 还可以在服务端执行 Python, bash，以及 网页搜索 ，并将结果作为自定义 tool_result 事件流式返回。这项功能让 Unsloth 开箱即用时就像一个“真正的”代理，无需通过你的客户端来回传递工具调用。

通过向 任一 /v1/chat/completions 或 /v1/messages:

字段	类型	说明
enable_thinking	布尔值	false 以禁用思考。 true 默认
enable_tools	布尔值	true 以启用服务端工具执行。
enabled_tools	array<string>	模型可以调用哪些工具。支持 python, bash, web_search.
session_id	字符串	可选。可在多次调用之间持久化工具状态（例如 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": "用一句话总结量子隧穿"}],
    "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 未授权 - 该 Authorization 标头缺失或密钥错误。请再次检查： Authorization: Bearer sk-unsloth-….

curl 流式请求时挂起 - 添加 -N （与 --no-buffer相同）。没有它， curl 会缓冲 SSE 流，直到结束你才会看到输出。

不同操作系统之间的 Base64 编码不同 - Linux 的 base64 默认会换行，而 macOS / BSD 不会。请在 Linux 上使用 base64 -w 0 ，在 macOS 上使用 base64 ，或者将输出通过管道传递给 tr -d '\n'.

shell 中的 JSON 转义 - Heredoc（-d @file.json）在请求体变复杂后比内联字符串更清晰。示例： curl ... -d @body.json.

max_tokens 报错于 /v1/messages - Anthropic 方言要求它。请添加 "max_tokens": 1024 （或你想要的任何限制）。

对于端点级别的问题（模型未加载、连接断开、端口错误），请参阅 API 概览页面。