指南 · Joshua API

从你的程序
和 Joshua 对话

Joshua 内置了 API：你的脚本、机器人、智能家居中枢，或任何支持 “OpenAI-compatible” 服务器的应用，都可以向它发送问题并得到回答。每个请求都会在你的电脑上运行完整的 Joshua，包括网络搜索、工具和记忆。

入门

打开 Joshua。API 随它一起启动，地址是 http://127.0.0.1:7861/v1。
在右侧栏打开 🔌 API。它会显示地址、你的密钥，以及一条可直接试用的命令。
复制密钥。每个请求都必须带上它，就像密码一样。只有你的电脑知道它；万一泄露，创建新密钥可以替换它。

Joshua 必须在运行，API 才会响应。密钥保存在 ~/AskJoshua/joshua/api.json。

你的第一个请求

在“终端”里列出你可以使用的模型，然后提一个问题。把 YOUR-KEY 换成面板里的密钥。

终端

curl http://127.0.0.1:7861/v1/models \
  -H "Authorization: Bearer YOUR-KEY"

终端

curl http://127.0.0.1:7861/v1/chat/completions \
  -H "Authorization: Bearer YOUR-KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "joshua",
    "messages": [{"role": "user", "content": "What is the weather in Turin today?"}]
  }'

回答以标准格式返回；文本在 choices[0].message.content 中：

回答

{
  "id": "chatcmpl-5f2c9a01",
  "object": "chat.completion",
  "model": "qwen3-vl:8b-instruct",
  "choices": [{
    "index": 0,
    "message": {"role": "assistant", "content": "Oggi è domenica, 8 novembre 2026."},
    "finish_reason": "stop"
  }]
}

Joshua 在回答前可能会上网搜索、阅读网页或运行代码，所以一次回答可能需要几秒到几分钟，取决于问题和你的电脑。

Python

最简单的方法是用官方的 openai 库：把它指向 Joshua，而不是 OpenAI。

python · openai

# pip install openai
from openai import OpenAI

joshua = OpenAI(base_url="http://127.0.0.1:7861/v1", api_key="YOUR-KEY")

reply = joshua.chat.completions.create(
    model="joshua",
    messages=[{"role": "user", "content": "Summarise today's main news in Italy in three lines."}],
)
print(reply.choices[0].message.content)

或者用简单的 requests，例如在一个树莓派机器人上，每次都把历史记录一起发送来延续对话：

python · requests

# pip install requests
import requests

URL = "http://192.168.1.20:7861/v1/chat/completions"   # your computer's address on the home network
KEY = "YOUR-KEY"

def ask_joshua(text, history=()):
    messages = [*history, {"role": "user", "content": text}]
    r = requests.post(URL, headers={"Authorization": f"Bearer {KEY}"},
                      json={"model": "joshua", "messages": messages}, timeout=600)
    r.raise_for_status()
    return r.json()["choices"][0]["message"]["content"]

print(ask_joshua("Which washing programme for a shirt marked 40 °C, gentle?"))

JavaScript

javascript

const reply = await fetch("http://127.0.0.1:7861/v1/chat/completions", {
  method: "POST",
  headers: { "Authorization": "Bearer YOUR-KEY", "Content-Type": "application/json" },
  body: JSON.stringify({
    model: "joshua",
    messages: [{ role: "user", content: "Write a haiku about Turin in the fog." }],
  }),
}).then(r => r.json());

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

其他网站上的网页不能直接调用 Joshua；请在 Node 或你的应用中运行这段代码。

发送图片

把照片作为 data: URL 放在消息里发送。如果模型能看图片（qwen3-vl 可以），Joshua 会直接看；否则它会用自己的本地图片工具。

python

import base64
from openai import OpenAI

joshua = OpenAI(base_url="http://127.0.0.1:7861/v1", api_key="YOUR-KEY")
photo = base64.b64encode(open("label.jpg", "rb").read()).decode()

reply = joshua.chat.completions.create(model="joshua", messages=[{
    "role": "user",
    "content": [
        {"type": "text", "text": "What does this care label say?"},
        {"type": "image_url", "image_url": {"url": f"data:image/jpeg;base64,{photo}"}},
    ],
}])
print(reply.choices[0].message.content)

选项

你可以用一条 system 消息给 Joshua 额外的指令：它们会附加在 Joshua 自己的指令之后。你也可以让它不要把这次交流保存为对话：

python

reply = joshua.chat.completions.create(
    model="joshua",
    messages=[
        {"role": "system", "content": "You are the voice of a small robot. Answer in one short sentence, in Italian."},
        {"role": "user", "content": "Che ore sono?"},
    ],
    extra_body={"joshua_save": False},   # don't keep this exchange as a chat
)

字段	作用
model	`joshua` = 你的默认本地模型。也可以是 `/v1/models` 中的任意名称，例如 `qwen3-vl:8b-instruct`。云端模型（名称以 `cloud` 结尾）只有在你指定时才会使用。
messages	对话：`system`、`user` 和 `assistant` 消息，按从旧到新排列。Joshua 在请求之间不保留任何内容，所以请发送你希望它记住的历史。
stream	`true` 适用于期望流式输出的客户端，但回答会在最后一次性返回。
joshua_save	`false` = 不把这次交流保存为 🔌 对话。默认 `true`。

从其他设备使用

默认只有同一台电脑上的程序能连接。要从机器人、手机或家里的另一台电脑使用 Joshua：

在 🔌 API 中，勾选允许我网络中的其他设备。
重启 Joshua（运行 ~/AskJoshua/stop.sh，然后重新打开 Joshua）。
面板现在会显示你电脑的网络地址，例如 http://192.168.1.20:7861/v1。在另一台设备上用这个地址和同一个密钥。

只在家庭网络中使用。不要在路由器上开放 7861 端口：密钥能保护 Joshua，但连接没有加密。

参考

请求	作用
GET /v1/models	列出 `joshua` 以及每个已安装、能使用工具的模型。`owned_by` 显示 `this computer` 或 `cloud`。
POST /v1/chat/completions	在消息上运行 Joshua，并以 OpenAI 对话格式返回它的回答。

错误	含义
401	缺少密钥或密钥错误。请发送 `Authorization: Bearer YOUR-KEY`。
400	请求有问题，例如模型名称未知。提示信息会说明原因。
connection refused	Joshua 没有运行，或者（从其他设备访问时）“允许其他设备”未开启，或 Joshua 没有重启。

只需要裸模型，不要 Joshua 的工具和记忆？Ollama 有自己的 API，地址 http://127.0.0.1:11434，在 /v1 上也兼容 OpenAI，无需密钥。

隐私

使用本地模型时，请求完全在你的电脑上得到回答。
每个请求都会在 Joshua 中保存为一个 🔌 对话，让你随时能看到程序问了什么，除非程序发送 joshua_save: false。
API 请求不会加入 Joshua 关于你的记忆，但本地模型可以用你的笔记来回答。
只有当程序按名称请求时才会使用云端模型；这时对话会发送到 Ollama 的服务器，详见你的数据在哪里。