Parla con Joshua
dai tuoi programmi

Per cominciare

1. Apri Joshua. L'API parte con lui, all'indirizzo http://127.0.0.1:7861/v1.
2. Nella colonna di destra apri 🔌 API. Mostra l'indirizzo, la tua chiave e un comando pronto da provare.
3. Copia la chiave. Ogni richiesta deve averla, come una password. La conosce solo il tuo computer; Crea una nuova chiave la sostituisce se dovesse mai uscire.

Joshua deve essere in funzione perché l'API risponda. La chiave è salvata in ~/AskJoshua/joshua/api.json.

La tua prima richiesta

Nel Terminale, elenca i modelli che puoi usare, poi fai una domanda. Sostituisci YOUR-KEY con la chiave del pannello.

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

La risposta torna nel formato standard; il testo è in 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 può cercare sul web, leggere pagine o eseguire codice prima di rispondere, quindi una risposta può richiedere da pochi secondi a qualche minuto, a seconda della domanda e del tuo computer.

Python

Il modo più semplice è la libreria ufficiale openai: puntala su Joshua invece che su 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)

Oppure con la semplice requests, per esempio su un robot con Raspberry Pi che porta avanti la conversazione rimandando ogni volta la cronologia:

# 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

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

Una pagina web su un altro sito non può chiamare Joshua direttamente; esegui questo in Node o nella tua app.

Inviare immagini

Invia una foto come URL data: dentro il messaggio. Con un modello che vede le immagini (qwen3-vl lo fa), Joshua la guarda direttamente; altrimenti usa il suo strumento locale per le immagini.

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)

Opzioni

Puoi dare a Joshua istruzioni in più con un messaggio system: vengono aggiunte dopo le sue. E puoi chiedergli di non salvare lo scambio come chat:

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
)

Da altri dispositivi

Di base possono collegarsi solo i programmi sullo stesso computer. Per usare Joshua da un robot, da un telefono o da un altro computer di casa:

1. In 🔌 API, spunta Consenti gli altri dispositivi della mia rete.
2. Riavvia Joshua (esegui ~/AskJoshua/stop.sh, poi riapri Joshua).
3. Ora il pannello mostra l'indirizzo di rete del tuo computer, come http://192.168.1.20:7861/v1. Usa quell'indirizzo sull'altro dispositivo, con la stessa chiave.

Tienilo nella rete di casa. Non aprire la porta 7861 sul router: la chiave protegge Joshua, ma la connessione non è cifrata.

Riferimento

Ti serve solo il modello nudo, senza gli strumenti e la memoria di Joshua? Ollama ha una sua API su http://127.0.0.1:11434, compatibile OpenAI anche su /v1, senza chiave.

Privacy

• Con un modello locale le richieste ricevono risposta interamente sul tuo computer.
• Ogni richiesta viene salvata come chat 🔌 in Joshua, così puoi sempre vedere cosa hanno chiesto i programmi, a meno che il programma non invii joshua_save: false.
• Le richieste API non si aggiungono alla memoria che Joshua ha di te, ma i modelli locali possono usare le tue note per rispondere.
• Un modello cloud viene usato solo se un programma lo chiede per nome; in quel caso la conversazione va ai server di Ollama, come descritto in dove stanno i tuoi dati.