ES ▾
Obtener clave de API
API sin censura compatible con OpenAI para desarrolladores.Actualizado

Modo JSON y llamadas a funciones de Uncensored LLM API

El interruptor del modo JSON de la API LLM sin censura es el mismo que ya conoces de los clientes de OpenAI: envía response_format con type json_object y la respuesta vuelve como un objeto JSON. Esta página cubre eso, además de las llamadas a funciones, con código que puedes ejecutar contra el endpoint en vivo.

Corchetes brillantes ensamblados a partir de cubos con un brazo mecánico, ilustrando la salida JSON estructurada y las llamadas a funciones

Inicio rápido con curl

La petición de modo JSON más pequeña posible se ve así. Usa la URL base https://api.uncensoredllmapi.com/v1, el modelo uncensored y tu clave como token 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."}
    ]
  }'

El mensaje del asistente en choices[0].message.content es una cadena que contiene un objeto JSON. Todavía tienes que analizarlo tú mismo. No omitas la instrucción en el prompt: el modo JSON restringe la salida para que sea un objeto, pero no puede adivinar qué claves necesitas. Nombrar las claves y, idealmente, mostrar un ejemplo de una línea es lo que te da una estructura estable.

Si aún no tienes una clave, la página de clave de API otorga $0,50 de crédito de prueba con un solo clic tras iniciar sesión. Ese crédito no requiere pago, dura 7 días y está limitado a uno por persona.

Modo JSON en Python con validación

Trata la salida del modelo como cualquier otra entrada externa. Analízala, compruébala contra un esquema y reintenta un número limitado de veces si falla. Pydantic hace esto breve:

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

Tres hábitos en ese fragmento valen la pena copiar. El código verifica finish_reason antes de analizar, porque una respuesta que se detiene en max_tokens termina a mitad del objeto. Usa una temperatura moderada, ya que temperaturas altas hacen más probable una salida mal formada. Y limita los reintentos, para que un prompt malo no gire para siempre. Como las peticiones fallidas o rechazadas no se facturan, el presupuesto de reintentos es una cuestión de latencia más que de coste.

Errores comunes del modo JSON

  • Pedir JSON en el prompt pero no en response_format. El modelo suele cumplir, pero puede envolver el objeto en prosa o en un bloque de código. Configura ambos.
  • Configurar max_tokens demasiado bajo. Estima la respuesta válida más larga y añade margen. Una larga lista de elementos puede exceder fácilmente los 300 tokens.
  • Esperar una matriz de nivel superior. El modo JSON pide un objeto. Si necesitas una lista, pide {"items": [...]}.
  • Apilar una secuencia de parada que aparece en el JSON. El parámetro stop se pasa tal cual, y una cadena de parada que aparezca dentro de un valor cortará la respuesta a mitad.
  • Usar el modo JSON con streaming y analizar cada fragmento. Recopila todo el texto primero, luego analízalo una sola vez al final.

Los ajustes de muestreo como temperature, top_p, seed y las penalizaciones se pasan tal cual. Para tareas de extracción, una temperatura baja de alrededor de 0,2 y un seed fijo dan la salida más repetible. Para generación creativa como el NPC anterior, un valor más alto está bien siempre que valides.

Llamadas a herramientas: el ciclo completo

Las llamadas a funciones permiten que el modelo pida a tu código que haga algo y luego continúe con el resultado. El flujo tiene cuatro pasos: declaras las herramientas, el modelo responde con tool_calls, las ejecutas y envías los resultados de vuelta como mensajes con 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),
        })

Los argumentos llegan como una cadena JSON, que debes analizar, y el modelo ocasionalmente puede producir argumentos que no coinciden con tu esquema. Valídalos antes de ejecutar cualquier cosa con efectos secundarios. Nunca los pases a una shell, una cadena SQL o una ruta de archivo sin comprobaciones.

El campo tool_choice te permite dirigir el comportamiento. Déjalo en "auto" y el modelo decide. Nombra una función específica para forzar una llamada, lo cual es útil cuando quieres una extracción estructurada a través de un esquema de herramienta en lugar del modo JSON.

Streaming de llamadas a herramientas en Node

Con stream: true, las llamadas a funciones llegan en piezas. Cada fragmento lleva una parte del nombre de la función o la cadena de argumentos, indexada por posición. Tienes que concatenar los fragmentos por índice y analizar solo cuando termina el streaming.

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

Recuerda que una petición en streaming ocupa una de tus ranuras de concurrencia hasta que termina el streaming. Una clave completa permite 8 peticiones simultáneas y 300 por minuto, una clave de prueba 2 y 60. Al alcanzar cualquiera de los límites se devuelve HTTP 429 con el código concurrency o rate_limited. Los totales de uso se reportan al final del streaming, lo cual es útil para registrar el coste.

Modo JSON o un esquema de herramienta

Ambos te dan datos estructurados, ¿cuál deberías usar? La pregunta decisiva es si el modelo está produciendo datos o eligiendo una acción.

Usa el modo JSON cuando la salida en sí sea el producto: una ficha de NPC, una lista de etiquetas, una clasificación con un campo de confianza. Controlas todo el prompt, obtienes un objeto de vuelta y hay una petición que pagar.

Usa herramientas cuando el modelo tenga que decidir si actuar, o cuando haya varias acciones posibles. Un esquema por función documenta el contrato, tool_choice te permite forzar o permitir una llamada, y el bucle en la sección anterior maneja el trabajo en múltiples pasos. El coste es una petición extra por ronda, más las definiciones de herramientas contadas como entrada cada vez.

Un término medio práctico para la extracción: declara una herramienta cuyos parámetros sean los campos que quieres, y configura tool_choice a esa función. Obtienes un JSON de argumentos que sigue la forma del esquema sin escribir la lista de claves en el prompt. En cualquier caso, valida el resultado antes de confiar en él y registra el valor X-Request-Id de cualquier petición que haya producido algo inesperado.

Lo que cuesta

El JSON y las llamadas a funciones se facturan como cualquier otro token: $0,15 por cada 1M de entrada y $0,50 por cada 1M de salida. Las definiciones de herramientas cuentan como entrada en cada petición, y cada resultado de herramienta que envíes de vuelta se suma a la entrada de la siguiente petición.

Ejemplo: un turno de asistente que usa herramientas con un esquema de herramienta y prompt de 600 tokens, una llamada de modelo de 150 tokens, luego una segunda petición que contiene 900 tokens de entrada (los mensajes previos más un resultado de herramienta) y una respuesta de 200 tokens.

  • Petición uno: 600 de entrada y 150 de salida. Entrada 600 x $0.15 / 1M = $0.00009. Salida 150 x $0.50 / 1M = $0.000075. Subtotal $0.000165.
  • Petición dos: 900 de entrada y 200 de salida. Entrada 900 x $0.15 / 1M = $0.000135. Salida 200 x $0.50 / 1M = $0.0001. Subtotal $0.000235.
  • Total para el turno: $0.0004.

A ese ritmo, 1.000 turnos cuestan $0,40. El crédito es prepago en cantidades enteras desde $20 hasta $500 (bono: +5% desde $50, +10% desde $100, +15% desde $200), pagado en cripto con USDT en TRC20 o USDC en Base. Consulta la página de precios para las cifras actuales.

A dónde ir a continuación

La referencia de cada campo de la solicitud está en la documentación de la API. Si estás preparando una aplicación para tráfico real, la lista de verificación de producción es la siguiente página que debes leer, y soporte puede ayudarte si una solicitud se comporta de forma inesperada. Mantén a mano tu ID de solicitud, que se devuelve en el encabezado X-Request-Id.

El servicio es solo de texto y la ventana de contexto es de 100.000 tokens, incluidas tus definiciones de herramientas y los resultados. El contenido sexual que involucre a menores no está permitido, y eso se aplica a la salida impulsada por herramientas exactamente igual que al chat sin formato.

Preguntas y respuestas

¿Garantiza el modo JSON mi esquema exacto?

No. Convierte la respuesta en un objeto JSON, pero las claves provienen de tu prompt. Valida el resultado con una librería de esquemas y reintenta si falla.

¿Cómo envío los resultados de las herramientas?

Añade el mensaje del asistente que contenía tool_calls, luego añade un mensaje por llamada con role: tool, el tool_call_id correspondiente y el resultado como cadena.

¿Puedo hacer streaming de las llamadas a funciones?

Sí. Con stream en true, las tool_calls llegan en fragmentos. Concatena las cadenas de nombre y argumentos por índice y analiza una vez que termine el streaming.

¿Se cobran las respuestas JSON inválidas?

Se cobra una respuesta que se completa, incluso si tu parser la rechaza. Las solicitudes fallidas o rechazadas no se cobran.

Tu clave está a un formulario de distancia

Crea una cuenta, copia la clave, cambia la URL base. Esa es toda la configuración.