Parlez à Joshua
depuis vos programmes

Pour commencer

1. Ouvrez Joshua. L'API démarre avec lui, à l'adresse http://127.0.0.1:7861/v1.
2. Dans la colonne de droite, ouvrez 🔌 API. Elle montre l'adresse, votre clé et une commande prête à essayer.
3. Copiez la clé. Chaque demande doit l'avoir, comme un mot de passe. Seul votre ordinateur la connaît ; Créer une nouvelle clé la remplace si jamais elle fuit.

Joshua doit être en marche pour que l'API réponde. La clé est enregistrée dans ~/AskJoshua/joshua/api.json.

Votre première demande

Dans le Terminal, listez les modèles que vous pouvez utiliser, puis posez une question. Remplacez YOUR-KEY par la clé du panneau.

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 réponse revient au format standard ; le texte est dans 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 peut chercher sur le web, lire des pages ou exécuter du code avant de répondre, donc une réponse peut prendre de quelques secondes à quelques minutes, selon la question et votre ordinateur.

Python

Le plus simple est la bibliothèque officielle openai : pointez-la vers Joshua au lieu d'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)

Ou avec la simple requests, par exemple sur un robot Raspberry Pi qui poursuit la conversation en renvoyant l'historique à chaque fois :

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

Une page web d'un autre site ne peut pas appeler Joshua directement ; exécutez ceci dans Node ou dans votre appli.

Envoyer des images

Envoyez une photo comme URL data: dans le message. Avec un modèle qui voit les images (qwen3-vl le fait), Joshua la regarde directement ; sinon il utilise son outil d'images local.

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)

Options

Vous pouvez donner à Joshua des instructions supplémentaires avec un message system : elles s'ajoutent après les siennes. Et vous pouvez lui demander de ne pas enregistrer l'échange comme discussion :

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
)

Depuis d'autres appareils

Par défaut, seuls les programmes du même ordinateur peuvent se connecter. Pour utiliser Joshua depuis un robot, un téléphone ou un autre ordinateur de la maison :

1. Dans 🔌 API, cochez Autoriser les autres appareils de mon réseau.
2. Redémarrez Joshua (lancez ~/AskJoshua/stop.sh, puis rouvrez Joshua).
3. Le panneau montre maintenant l'adresse réseau de votre ordinateur, comme http://192.168.1.20:7861/v1. Utilisez cette adresse sur l'autre appareil, avec la même clé.

Gardez-le dans le réseau de la maison. N'ouvrez pas le port 7861 sur votre box : la clé protège Joshua, mais la connexion n'est pas chiffrée.

Référence

Vous voulez seulement le modèle nu, sans les outils et la mémoire de Joshua ? Ollama a sa propre API sur http://127.0.0.1:11434, compatible OpenAI aussi sur /v1, sans clé.

Confidentialité

• Avec un modèle local, les demandes reçoivent leur réponse entièrement sur votre ordinateur.
• Chaque demande est enregistrée comme discussion 🔌 dans Joshua, pour que vous voyiez toujours ce que les programmes ont demandé, sauf si le programme envoie joshua_save: false.
• Les demandes API ne s'ajoutent pas à la mémoire que Joshua a de vous, mais les modèles locaux peuvent utiliser vos notes pour répondre.
• Un modèle cloud n'est utilisé que si un programme le demande par son nom ; la conversation va alors aux serveurs d'Ollama, comme décrit dans où sont vos données.