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_tokensdemasiado 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
stopse 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.
