Connecter Curl et HTTP à Unsloth

Guide pour interroger l’API d’Unsloth avec curl (ou tout client HTTP), avec des exemples prêts à copier-coller pour chaque point de terminaison et fonctionnalité.

Unsloth expose trois formats de fil compatibles OpenAI/Anthropic à la même URL de base sur le port sur lequel Unsloth a démarré. Tous prennent un Authorization: Bearer sk-unsloth-… en-tête et renvoient soit du JSON soit du SSE, selon que vous définissez stream. Cette page regroupe les recettes par point de terminaison (/v1/chat/completions, /v1/messages, /v1/responses, /v1/models) et se termine par une section commune sur les outils côté serveur, qui fonctionnent sur tous les points de terminaison de chat.

Si vous ne savez pas quelle URL / clé / nom de modèle utiliser, lisez d'abord la vue d'ensemble de l'API. Elle vous guide pour démarrer Unsloth, charger un modèle et créer une sk-unsloth-… clé.

🔑 Authentification

Chaque requête a besoin d'un Authorization en-tête :

Authorization: Bearer sk-unsloth-xxxxxxxxxxxx

Pour éviter que les clés apparaissent dans l'historique de votre shell, exportez la clé une fois et référencez la variable d'environnement :

export UNSLOTH_STUDIO_AUTH_TOKEN=sk-unsloth-xxxxxxxxxxxx

Les extraits ci-dessous intègrent la clé en ligne sous la forme sk-unsloth-xxxxxxxxxxxx pour plus de clarté. En pratique, remplacez $UNSLOTH_STUDIO_AUTH_TOKEN.

📋 Lister les modèles chargés

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

Réponse:

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

Utilisez le id champ chaque fois qu'une requête a besoin d'une "model" valeur (ou lorsqu'un client comme opencode demande un ID du modèle).

💬 Complétions de chat (/v1/chat/completions)

Le dialecte OpenAI Chat Completions. La surface de compatibilité la plus large. Fonctionne avec le SDK OpenAI, opencode, Cursor, Continue, Cline, Open WebUI, SillyTavern et la plupart des outils compatibles OpenAI.

Requête de base

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

Flux en streaming

Ajoutez "stream": true et la réponse passe aux événements envoyés par le serveur (text/event-stream). Indiquez à curl de vider la sortie au fur et à mesure que les octets arrivent avec --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": "Écris un haïku sur des LLM exécutés localement."}],
    "stream": true
  }'

Chaque ligne de la réponse ressemble à data: {"choices":[{"delta":{"content":"..."}}]}, et se terminant par data: [DONE].

Images (vision)

Joignez une image en tant que image_url partie de contenu dans le message utilisateur. L'URL peut être HTTPS ou une URI base64 data: URI :

# Intégrer un fichier local en base64 (tronqué pour plus de concision)
IMG=$(base64 -w 0 test.jpg)

cat > /tmp/request.json <<EOF
{
  "model":"default",
  "messages":[{"role":"user","content":[
    {"type":"text","text":"Décrivez l'image."},
    {"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

Le modèle chargé doit être multimodal. Si vous chargez un modèle texte uniquement, la requête réussit structurellement mais le modèle ne traitera pas l'image.

Appel de fonctions (outils OpenAI)

Passez des tools et, éventuellement, tool_choice. Votre client exécute chaque appel d'outil et renvoie le résultat au tour suivant.

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":"Quel temps fait-il à Paris ?"}],
    "tools":[{
      "type":"function",
      "function":{
        "name":"get_weather",
        "description":"Obtenir la météo actuelle d'une ville.",
        "parameters":{
          "type":"object",
          "properties":{"city":{"type":"string"}},
          "required":["city"]
        }
      }
    }],
    "tool_choice":"required"
  }' | jq '.choices[0].message, .usage'

📨 Messages Anthropic (/v1/messages)

Le dialecte compatible Anthropic d'Unsloth utilisé par Claude Code, le SDK Anthropic, OpenClaw et tout client qui parle l'API Messages.

Requête de base

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

max_tokens est requis sur /v1/messages (il est facultatif sur /v1/chat/completions).

Flux en streaming

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": "Expliquez LoRA en deux phrases."}],
    "stream": true
  }'

Les événements suivent la structure SSE d'Anthropic : message_start, content_block_start, content_block_delta, content_block_stop, message_delta, message_stopainsi que l'événement personnalisé tool_result pour la sortie des outils côté serveur.

Images (vision)

Le contenu d'image au format Anthropic utilise un source bloc avec des données base64 :

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

cat > /tmp/request.json <<EOF
{
  "messages":[{"role":"user","content":[
    {"type":"text","text":"Décrivez l'image."},
    {"type":"image","source":{"type":"base64","media_type":"image/jpeg","data":"$IMG"}}
  ]}],
  "max_tokens":200,
  "stream":true
}
EOF

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

Appel d'outils (outils Anthropic)

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": "Quel temps fait-il à Tokyo ?"}],
    "tools": [
      {
        "name": "get_weather",
        "description": "Obtenir la météo actuelle d'une ville",
        "input_schema": {
          "type": "object",
          "properties": {
            "city": {"type": "string"}
          },
          "required": ["city"]
        }
      }
    ],
    "tool_choice": {"type": "auto"}
  }'

tool_choice les valeurs correspondent comme suit au dialecte OpenAI : Anthropic auto → OpenAI auto, Anthropic any → OpenAI required, Anthropic {type: "tool", name: "x"} → OpenAI {type: "function", function: {name: "x"}}, Anthropic none → OpenAI none.

🧬 Réponses (/v1/responses)

Unsloth parle aussi de la nouvelle API OpenAI Responses, le protocole vers lequel Codex et d'autres clients OpenAI récents ont migré.

curl http://localhost:8888/v1/responses \
  -H "Authorization: Bearer sk-unsloth-xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen-local",
    "input": "Écrivez une salutation en une phrase."
  }'

Le streaming fonctionne de la même façon que pour Chat Completions. Ajoutez "stream": true et canalisez avec -N.

🧰 Outils côté serveur d'Unsloth (abrégé)

En plus de l'appel de fonctions côté client, Unsloth peut exécuter Python, bashainsi que la recherche web côté serveur et renvoyer les résultats sous forme d'événements personnalisés tool_result Cette fonctionnalité donne à Unsloth l'impression d'être un véritable agent dès le départ, sans faire transiter les appels d'outils par votre client.

Activez cette fonctionnalité en passant ces champs supplémentaires à soit /v1/chat/completions ou /v1/messages:

Champ	Type	Notes
enable_thinking	boolean	false pour désactiver le raisonnement. true par défaut
enable_tools	boolean	true pour activer l'exécution des outils côté serveur.
enabled_tools	array<string>	Quels outils le modèle peut appeler. Prend en charge python, bash, web_search.
session_id	string	Facultatif. Conserve l'état des outils (par ex. le noyau Python) d'un appel à l'autre.

Mode raisonnement

Le mode raisonnement est activé par défaut.

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": "résumez l'effet tunnel quantique en une phrase"}],
    "stream": false
  }'

Le modèle réfléchira avant de fournir une réponse.

Pour désactiver le raisonnement, passez enable_thinking: false dans votre requête. Le modèle fournira une réponse sans réfléchir d'abord.

Exécution 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": "Quel est 123 * 456 ? Utilisez du code pour le calculer."}],
    "stream": false,
    "enable_tools": true,
    "enabled_tools": ["python"],
    "session_id": "my-session"
  }'

Recherche web + Python (streaming)

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": "Recherchez les fonctionnalités de Python 3.13"}],
    "stream": true,
    "enable_tools": true,
    "enabled_tools": ["web_search", "python"],
    "session_id": "my-session"
  }'

Sur /v1/messages

Le même raccourci fonctionne également avec le point de terminaison 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": "Recherchez les fonctionnalités de Python 3.13"}],
    "stream": true,
    "enable_tools": true,
    "enabled_tools": ["web_search", "python"],
    "session_id": "my-session"
  }'

Unsloth diffuse ses propres tool_result événements SSE en plus des types d'événements standard Anthropic / OpenAI ; le modèle voit la sortie de chaque outil à son tour suivant.

❔ Dépannage

401 Non autorisé - Le Authorization en-tête manque ou la clé est incorrecte. Vérifiez : Authorization: Bearer sk-unsloth-….

curl se bloque sur les requêtes en streaming - Ajoutez -N (même que --no-buffer). Sans lui, curl met en tampon le flux SSE et vous ne voyez rien avant la fin.

L'encodage base64 diffère selon les systèmes d'exploitation - Sur Linux, base64 a tendance à insérer des retours à la ligne par défaut, contrairement à macOS / BSD. Utilisez base64 -w 0 sur Linux, base64 sur macOS, ou envoyez la sortie à travers tr -d '\n'.

Échappement JSON dans les shells - Les heredocs (-d @file.json) sont plus propres que les chaînes en ligne lorsque le corps devient complexe. Exemple : curl ... -d @body.json.

max_tokens erreurs sur /v1/messages - Le dialecte Anthropic l'exige. Ajoutez "max_tokens": 1024 (ou toute autre limite souhaitée).

Pour les problèmes au niveau des points de terminaison (modèle qui ne se charge pas, connexion interrompue, mauvais port), consultez la page de vue d'ensemble de l'API.

Facultatif : ajuster les valeurs par défaut du serveur

Vous pouvez personnaliser le comportement par défaut au démarrage du serveur avec unsloth run.

# Démarrer le serveur avec des valeurs par défaut personnalisées
unsloth run \
  --model unsloth/Qwen3-1.7B-GGUF \
  --reasoning off \
  --temp 0.6 \
  -p 8888

Utilisez --reasoning off pour désactiver le raisonnement, ou --reasoning on pour l'activer sur les modèles qui prennent en charge le raisonnement.

# Exposer l'API sur votre réseau local
unsloth run \
  --model unsloth/Qwen3-1.7B-GGUF \
  -H 0.0.0.0 \
  -p 8888

Cela démarre le serveur sur 0.0.0.0:8888, permettant à d'autres appareils de votre réseau local de se connecter.

Remplacer les paramètres par requête

Vous pouvez également remplacer directement les paramètres de génération dans chaque requête 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": "Écrivez un court poème sur l'IA locale."
      }
    ],
    "temperature": 0.8,
    "top_p": 0.9,
    "max_tokens": 512
  }'

Les valeurs au niveau de la requête, comme temperature, top_p, max_tokensainsi que stream remplacent les valeurs par défaut du serveur pour cette requête.