FR ▾
Obtenir une clé API
API sans censure compatible OpenAI pour les développeurs.Mis à jour le

Mode JSON et appel de fonctions avec Uncensored LLM API

Le commutateur du mode JSON de l'API LLM uncensored est le même que vous connaissez déjà avec les clients OpenAI : envoyez response_format avec type json_object et la réponse revient sous forme d'objet JSON. Cette page couvre cela, ainsi que l'appel de fonctions, avec du code que vous pouvez exécuter contre l'endpoint en direct.

Parenthèses lumineuses assemblées à partir de cubes avec un bras mécanique, illustrant la sortie JSON structurée et les appels d'outils

Démarrage rapide avec curl

La plus petite requête de mode JSON fonctionnelle ressemble à ceci. Elle utilise l'URL de base https://api.uncensoredllmapi.com/v1, le modèle uncensored et votre clé en tant que jeton bearer :

curl https://api.uncensoredllmapi.com/v1/chat/completions   -H "Authorization: Bearer $UNCENSORED_API_KEY"   -H "Content-Type: application/json"   -d '{
    "model": "uncensored",
    "response_format": {"type": "json_object"},
    "messages": [
      {"role": "system", "content": "Reply only with a JSON object."},
      {"role": "user", "content": "Create a tavern NPC with keys name, trade and rumour."}
    ]
  }'

Le message de l'assistant dans choices[0].message.content est une chaîne contenant un objet JSON. Vous devez encore l'analyser vous-même. Ne sautez pas l'instruction dans le prompt : le mode JSON contraint la sortie à être un objet, mais il ne peut pas deviner quelles clés vous souhaitez. Nommer les clés, et idéalement montrer un exemple d'une ligne, est ce qui vous donne une forme stable.

Si vous n'avez pas encore de clé, la page clé API distribue $0,50 de crédit d'essai en un clic après la création de compte. Ce crédit ne nécessite aucun paiement, dure 7 jours et est limité à un par personne.

Mode JSON en Python avec validation

Traitez la sortie du modèle comme n'importe quelle autre entrée externe. Analysez-la, vérifiez-la par rapport à un schéma et réessayez un nombre limité de fois si cela échoue. Pydantic rend cela court :

import json, os
from openai import OpenAI
from pydantic import BaseModel, ValidationError

client = OpenAI(
    base_url="https://api.uncensoredllmapi.com/v1",
    api_key=os.environ["UNCENSORED_API_KEY"],
)

class Npc(BaseModel):
    name: str
    trade: str
    rumour: str

SYSTEM = (
    "Reply only with a JSON object with exactly these keys: "
    "name, trade, rumour. Each value is a string."
)

def make_npc(setting, tries=3):
    for _ in range(tries):
        r = client.chat.completions.create(
            model="uncensored",
            response_format={"type": "json_object"},
            messages=[
                {"role": "system", "content": SYSTEM},
                {"role": "user", "content": f"Setting: {setting}"},
            ],
            temperature=0.7,
            max_tokens=300,
        )
        choice = r.choices[0]
        if choice.finish_reason == "length":
            continue           # cut off, so the JSON is incomplete
        try:
            return Npc(**json.loads(choice.message.content))
        except (json.JSONDecodeError, ValidationError, TypeError):
            continue
    raise RuntimeError("no valid JSON after retries")

print(make_npc("a river port in a plague year"))

Trois habitudes dans cet extrait valent le coup d'être copiées. Le code vérifie finish_reason avant l'analyse, car une réponse qui s'arrête à max_tokens se termine au milieu de l'objet. Il utilise une température modérée, car des températures élevées rendent les sorties malformées plus probables. Et il limite les tentatives, afin qu'un prompt défectueux ne tourne pas indéfiniment. Puisque les requêtes échouées ou refusées ne sont pas facturées, le budget de tentative est une question de latence plutôt que de coût.

Erreurs courantes en mode JSON

  • Demander du JSON dans le prompt mais pas dans response_format. Le modèle s'y conformera souvent, mais il peut envelopper l'objet dans du texte ou une balise de code. Définissez les deux.
  • Définir max_tokens trop bas. Estimez la réponse valide la plus longue et ajoutez une marge. Une longue liste d'éléments peut facilement dépasser 300 tokens.
  • S'attendre à un tableau de niveau supérieur. Le mode JSON demande un objet. Si vous avez besoin d'une liste, demandez {"items": [...]}.
  • Empiler une séquence d'arrêt qui apparaît dans le JSON. Le paramètre stop est passé tel quel, et une chaîne d'arrêt qui apparaît à l'intérieur d'une valeur coupera la réponse court.
  • Utilisation du mode JSON avec streaming et analyse de chaque chunk. Collectez d'abord tout le texte, puis analysez une seule fois à la fin.

Les paramètres d'échantillonnage tels que temperature, top_p, seed et les pénalités sont passés tels quels. Pour les tâches d'extraction, une température faible autour de 0,2 et un seed fixe donnent la sortie la plus reproductible. Pour la génération créative comme le PNJ ci-dessus, une valeur plus élevée convient tant que vous validez.

Appel de fonctions : la boucle complète

Les appels d'outils permettent au modèle de demander à votre code de faire quelque chose, puis de continuer avec le résultat. Le flux comporte quatre étapes : vous déclarez les outils, le modèle répond avec tool_calls, vous les exécutez, et vous renvoyez les résultats en tant que messages avec role: "tool".

import json, os
from openai import OpenAI

client = OpenAI(
    base_url="https://api.uncensoredllmapi.com/v1",
    api_key=os.environ["UNCENSORED_API_KEY"],
)

tools = [{
    "type": "function",
    "function": {
        "name": "lookup_inventory",
        "description": "Return the stock count for an item in the shop.",
        "parameters": {
            "type": "object",
            "properties": {"item": {"type": "string"}},
            "required": ["item"],
        },
    },
}]

def lookup_inventory(item):
    stock = {"healing potion": 4, "rope": 12}
    return {"item": item, "count": stock.get(item.lower(), 0)}

messages = [{"role": "user", "content": "Do you still have healing potions?"}]

for _ in range(4):                      # hard cap on tool rounds
    r = client.chat.completions.create(
        model="uncensored", messages=messages, tools=tools, tool_choice="auto"
    )
    msg = r.choices[0].message
    if not msg.tool_calls:
        print(msg.content)
        break
    messages.append(msg)
    for call in msg.tool_calls:
        args = json.loads(call.function.arguments)
        result = lookup_inventory(**args)
        messages.append({
            "role": "tool",
            "tool_call_id": call.id,
            "content": json.dumps(result),
        })

Les arguments arrivent sous forme de chaîne JSON, que vous devez analyser, et le modèle peut occasionnellement produire des arguments qui ne correspondent pas à votre schéma. Validez-les avant d'exécuter quoi que ce soit ayant des effets secondaires. Ne les passez jamais à un shell, une chaîne SQL ou un chemin de fichier sans vérifications.

Le champ tool_choice vous permet de diriger le comportement. Laissez-le sur "auto" et le modèle décide. Nommez une fonction spécifique pour forcer un appel, ce qui est utile lorsque vous souhaitez une extraction structurée via un schéma d'outil au lieu du mode JSON.

Streaming des appels d'outils dans Node

Avec stream: true, les tool_calls arrivent par morceaux. Chaque chunk porte un fragment du nom de la fonction ou de la chaîne d'arguments, indexé par position. Vous devez concaténer les fragments par index et analyser uniquement à la fin du stream.

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.uncensoredllmapi.com/v1",
  apiKey: process.env.UNCENSORED_API_KEY,
});

const stream = await client.chat.completions.create({
  model: "uncensored",
  stream: true,
  messages: [{ role: "user", content: "Check stock for rope." }],
  tools: [{
    type: "function",
    function: {
      name: "lookup_inventory",
      description: "Return the stock count for an item.",
      parameters: {
        type: "object",
        properties: { item: { type: "string" } },
        required: ["item"],
      },
    },
  }],
});

const calls = [];
for await (const chunk of stream) {
  const delta = chunk.choices[0]?.delta;
  for (const tc of delta?.tool_calls ?? []) {
    const slot = (calls[tc.index] ??= { id: "", name: "", args: "" });
    if (tc.id) slot.id = tc.id;
    if (tc.function?.name) slot.name += tc.function.name;
    if (tc.function?.arguments) slot.args += tc.function.arguments;
  }
}

for (const c of calls) {
  console.log(c.name, JSON.parse(c.args));
}

N'oubliez pas qu'une requête en streaming occupe l'un de vos slots de concurrence jusqu'à la fin du stream. Une clé complète permet 8 requêtes simultanées et 300 par minute, une clé d'essai 2 et 60. Atteindre l'une ou l'autre donne un HTTP 429 avec le code concurrency ou rate_limited. Les totaux d'utilisation sont rapportés à la fin du stream, ce qui est pratique pour enregistrer le coût.

Mode JSON ou schéma d'outil

Les deux vous donnent des données structurées, alors lequel devez-vous utiliser ? La question décisive est de savoir si le modèle produit des données ou choisit une action.

Utilisez le mode JSON lorsque la sortie elle-même est le produit : une fiche de PNJ, une liste de balises, une classification avec un champ de confiance. Vous contrôlez tout le prompt, vous obtenez un objet en retour, et il n'y a qu'une requête à payer.

Utilisez des outils lorsque le modèle doit décider d'agir, ou lorsque plusieurs actions différentes sont possibles. Un schéma par fonction documente le contrat, tool_choice vous permet de forcer ou d'autoriser un appel, et la boucle de la section précédente gère le travail multi-étapes. Le coût est une requête supplémentaire par tour, plus les définitions d'outils comptées comme entrée chaque fois.

Un compromis pratique pour l'extraction : déclarez un outil dont les paramètres sont les champs que vous souhaitez, et définissez tool_choice sur cette fonction. Vous obtenez un JSON d'arguments qui suit la forme du schéma de votre outil sans écrire la liste des clés dans le prompt. Dans les deux cas, validez le résultat avant de lui faire confiance, et journalisez la valeur X-Request-Id de toute requête qui a produit quelque chose d'inattendu.

Ce que cela coûte

Le JSON et les appels d'outils sont facturés comme n'importe quel autre token : $0,15 par 1M en entrée et $0,50 par 1M en sortie. Les définitions d'outils comptent comme entrée sur chaque requête, et chaque résultat d'outil que vous renvoyez s'ajoute à l'entrée de la requête suivante.

Exemple : un tour d'assistant utilisant un outil avec un schéma d'outil et un prompt de 600 tokens, un appel de modèle de 150 tokens, puis une deuxième requête contenant 900 tokens d'entrée (les messages antérieurs plus un résultat d'outil) et une réponse de 200 tokens.

  • Requête une : 600 entrées et 150 sorties. Entrée 600 x $0,15 / 1M = $0,00009. Sortie 150 x $0,50 / 1M = $0,000075. Sous-total $0,000165.
  • Requête deux : 900 entrées et 200 sorties. Entrée 900 x $0,15 / 1M = $0,000135. Sortie 200 x $0,50 / 1M = $0,0001. Sous-total $0,000235.
  • Total pour le tour : $0,0004.

À ce tarif, 1 000 tours coûtent $0,40. Le crédit est prépayé en montants entiers de $20 à $500 (bonus : +5% à partir de $50, +10% à partir de $100, +15% à partir de $200), payé en crypto avec USDT sur TRC20 ou USDC sur Base. Voir la page tarifs pour les chiffres actuels.

Où aller ensuite

La référence pour chaque champ de requête se trouve dans la documentation API. Si vous préparez une application pour le trafic réel, la liste de contrôle de production est la prochaine page à lire, et support peut aider si une requête se comporte de manière inattendue. Gardez votre ID de requête, qui revient dans l'en-tête X-Request-Id, à portée de main.

Le service est uniquement textuel et la fenêtre de contexte est de 100 000 tokens, incluant vos définitions et résultats d'outils. Le contenu sexuel impliquant des mineurs n'est pas autorisé, et cela s'applique à la sortie structurée et pilotée par des outils exactement comme à la discussion simple.

Questions et réponses

Le mode JSON garantit-il mon schéma exact ?

Non. Il renvoie une réponse au format objet JSON, mais les clés proviennent de votre prompt. Validez le résultat avec une bibliothèque de schémas et réessayez en cas d'échec.

Comment renvoyer les résultats d'outils ?

Ajoutez le message de l'assistant contenant tool_calls, puis ajoutez un message par appel avec role tool, l'identifiant tool_call_id correspondant et le résultat sous forme de chaîne.

Puis-je streamer les appels d'outils ?

Oui. Avec stream défini sur true, les tool_calls arrivent par fragments. Concaténez les chaînes de nom et d'arguments par index et analysez une seule fois à la fin du stream.

Les réponses JSON invalides sont-elles facturées ?

Une réponse qui aboutit est facturée, même si votre analyseur la rejette. Les requêtes échouées ou refusées ne sont pas facturées.

Votre clé est à un formulaire de vous

Créez un compte, copiez la clé, modifiez l'URL de base. C'est toute la configuration.