Referencia de Uncensored API explicada campo por campo

Convenciones y transporte

La URL base es https://api.uncensoredapis.com/v1. Todos los cuerpos son JSON y UTF-8. Cada petición lleva Authorization: Bearer <key>; una clave faltante o incorrecta devuelve 401. Solo existen dos rutas, y cualquier otra ruta devuelve 404.

Método	Ruta	Propósito
POST	/v1/chat/completions	Generar un mensaje del asistente, opcionalmente en streaming
GET	/v1/models	Listar el id de modelo que puedes solicitar

La API es solo texto. No hay rutas de embeddings, imagen, audio o video ni de fine-tuning, y hay exactamente un modelo, direccionado como uncensored. Debido a que el formato de la línea es compatible con la convención de chat completions, los SDK oficiales de Python y Node.js funcionan cuando sobrescribes base_url. La documentación cubre la configuración inicial; esta página es el complemento a nivel de campo.

Campos del cuerpo de la petición

La tabla lista los campos que entiende el endpoint. Los campos de muestreo se pasan a la generación sin cambios, por lo que los valores que elijas se comportarán como lo harían en cualquier API de estilo chat-completions.

Campo	Tipo	Notas
model	string	Siempre "uncensored".
messages	array	Objetos ordenados con role (system, user, assistant, tool) y content.
max_tokens	integer	Tope de finalización. Por defecto 2048, máximo 32.000.
temperature	number	Aleatoriedad. Menor es más determinista.
top_p	number	Corte de muestreo de núcleo.
stop	string o array	Secuencias que finalizan la generación.
stream	boolean	true cambia la respuesta a eventos enviados por el servidor.
tools	array	Definiciones de funciones en el formato estándar de JSON-schema.

Aquí tienes una petición anotada completa. El mensaje del sistema establece el comportamiento, el mensaje del usuario contiene la tarea, y stop finaliza la generación al primer línea en blanco.

Copycurl https://api.uncensoredapis.com/v1/chat/completions \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "uncensored",
    "messages": [
      {"role": "system", "content": "You are a terse release-notes writer."},
      {"role": "user", "content": "Summarize: fixed login bug, added dark mode."}
    ],
    "max_tokens": 120,
    "temperature": 0.4,
    "stop": ["\n\n"]
  }'

Importan dos reglas de presupuesto. Primero, el prompt más la completación deben caber en 100,000 tokens, por lo que una petición cuyos tokens de prompt más max_tokens excedan ese límite se rechaza con un 400. Segundo, el cuerpo serializado no puede exceder 8 MB. Si envías historiales largos, recorta las turnos antiguos por tu cuenta antes de que se acerquen a cualquiera de los dos límites.

El objeto de respuesta

Una llamada sin streaming devuelve un único objeto JSON. Léelo de arriba a abajo de la siguiente manera.

Copy{
  "id": "chatcmpl-example123",
  "object": "chat.completion",
  "created": 1767225600,
  "model": "uncensored",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "v1.4: Login bug fixed. Dark mode added."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 38,
    "completion_tokens": 14,
    "total_tokens": 52
  }
}

• id: un identificador único para la completación. Regístralo junto con tu propio id de petición cuando necesites correlacionar eventos.
• object: la constante chat.completion.
• created: marca de tiempo Unix en segundos.
• model: repite uncensored.
• choices: un array. Recibes una única entrada, por lo que choices[0] es la respuesta. index es su posición.
• choices[].message: role es assistant; content contiene el texto, o es null cuando el modelo devolvió llamadas a funciones en lugar de texto.
• choices[].finish_reason: por qué se detuvo la generación; consulta la siguiente sección.
• usage: contabilidad de tokens para facturación, cubierta más abajo.

Valores de finish_reason

Evalúa finish_reason antes de confiar en el contenido. Una respuesta truncada y una respuesta completa se ven idénticas hasta que la verificas.

Valor	Significado	Qué debe hacer tu código
stop	El modelo alcanzó un final natural o uno de tus secuencias stop.	Usa el contenido tal cual.
length	Se alcanzó el límite de max_tokens (o la ventana de contexto) a mitad de la respuesta.	Aumenta max_tokens, acorta el prompt o pide al modelo que continúe.
tool_calls	El modelo quiere que se ejecuten una o más funciones.	Execútalas y envía los resultados de vuelta como mensajes tool.

Cuando el valor es tool_calls, el mensaje se ve así, con los argumentos entregados como un JSON string que debes analizar tú mismo:

Copy{
  "choices": [{
    "index": 0,
    "message": {
      "role": "assistant",
      "content": null,
      "tool_calls": [{
        "id": "call_abc1",
        "type": "function",
        "function": {"name": "get_order", "arguments": "{\"order_id\": 8841}"}
      }]
    },
    "finish_reason": "tool_calls"
  }]
}

Envuelve siempre json.loads o JSON.parse en arguments en un bloque de manejo de errores, porque el JSON generado puede estar ocasionalmente malformado.

El bloque de uso y lo que cuesta

usage informa prompt_tokens, completion_tokens y total_tokens. Estos son los números contra los que se descuenta tu saldo: entrada a $0.25 por millón de tokens y salida a $1.00 por millón. El saldo prepagado se descuenta por petición, sin suscripción.

Un ejemplo práctico bajo supuestos establecidos: supongamos que una petición usa 2.000 tokens de prompt y 500 tokens de completación. El costo de entrada es 2.000 / 1.000.000 x $0,25 = $0,0005. El costo de salida es 500 / 1.000.000 x $1,00 = $0,0005. La petición suma $0,0010. Estos conteos de tokens son supuestos para aritmética, no una medición de ninguna carga de trabajo real. La página de precios tiene las tarifas en un solo lugar.

Dado que los tokens de salida cuestan cuatro veces más que los tokens de entrada, un max_tokens ajustado es tu control de costos más directo.

Formato de fragmento de streaming

Establece "stream": true y la respuesta se convierte en text/event-stream. Cada evento es una línea que comienza con data: seguida de JSON, separada por una línea en blanco. El tipo de objeto cambia a chat.completion.chunk y message se reemplaza por delta.

Copydata: {"id":"chatcmpl-example123","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"role":"assistant","content":""},"finish_reason":null}]}

data: {"id":"chatcmpl-example123","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":"v1.4: "},"finish_reason":null}]}

data: {"id":"chatcmpl-example123","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":"Login bug fixed."},"finish_reason":null}]}

data: {"id":"chatcmpl-example123","object":"chat.completion.chunk","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}

data: {"id":"chatcmpl-example123","object":"chat.completion.chunk","choices":[],"usage":{"prompt_tokens":38,"completion_tokens":14,"total_tokens":52}}

data: [DONE]

1. El primer fragmento suele establecer delta.role a assistant con contenido vacío.
2. Los fragmentos de contenido llevan un fragmento en delta.content. Concaténalos en orden de llegada.
3. El fragmento de cierre de contenido tiene un delta vacío y un finish_reason no nulo.
4. Un fragmento final con un array choices vacío lleva usage. No lo solicitas; se añade automáticamente.
5. El literal data: [DONE] termina el stream.

Protege contra ese array choices vacío: indexar choices[0] en el fragmento de uso genera un error en bucles simples. El ejemplo del SDK a continuación lo maneja.

Copyimport os
from openai import OpenAI

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

reason, usage = None, None
for chunk in client.chat.completions.create(
    model="uncensored",
    messages=[{"role": "user", "content": "Name three uses of a rubber duck in debugging."}],
    stream=True,
):
    if chunk.choices:
        piece = chunk.choices[0].delta.content
        if piece:
            print(piece, end="", flush=True)
        if chunk.choices[0].finish_reason:
            reason = chunk.choices[0].finish_reason
    if getattr(chunk, "usage", None):
        usage = chunk.usage

print("\nfinish:", reason, "| tokens:", usage.total_tokens if usage else "n/a")

Para llamadas a herramientas en streaming, delta.tool_calls llega en fragmentos; acumula la cadena arguments por índice de llamada y analiza una sola vez cuando finish_reason es tool_calls.

El endpoint de modelos

GET /v1/models solo necesita el encabezado Bearer y devuelve un objeto de lista. Debido a que hay un único modelo, data contiene una única entrada, uncensored. Los clientes que poblen un menú desplegable de modelos desde esta ruta mostrarán por tanto una única opción.

Copycurl https://api.uncensoredapis.com/v1/models -H "Authorization: Bearer $API_KEY"

{
  "object": "list",
  "data": [
    {"id": "uncensored", "object": "model"}
  ]
}

También es la forma más barata de verificar una clave: un 200 significa que la clave es válida, un 401 significa que es incorrecta o fue regenerada. Llamar a esta ruta no genera tokens. Para el manejo de estados y reglas de reintento, consulta el manual de errores y límites de peticiones.

Lista de verificación de referencia para autores de clientes

Si estás escribiendo una biblioteca de cliente o envolviendo el endpoint en un gateway, verifica cada uno de estos comportamientos contra la especificación anterior antes de lanzar.

1. Higiene de encabezados. Envía la clave solo en el encabezado Authorization, nunca en la cadena de consulta y nunca registres el valor del encabezado.
2. Analiza de forma defensiva. Trata los campos extra desconocidos en las respuestas como ignorables. Fija tu analizador a los campos documentados aquí en lugar de al orden exacto de las claves JSON.
3. Verifica finish_reason en cada respuesta. Muestra un indicador visible cuando es igual a length, de lo contrario los usuarios leerían texto cortado como si fuera la respuesta completa.
4. Presupuesto antes de enviar. Estima los tokens de prompt, suma tu max_tokens y compara la suma con 100,000. Rechazar localmente es más rápido que esperar un 400.
5. Maneja el final del stream. Espera un fragmento con una lista choices vacía y un objeto usage, luego [DONE]. Cierra la conexión después del centinela.
6. Registra el uso. Almacena total_tokens por petición para que puedas conciliar tu propia medición contra el saldo prepago más tarde.
7. Respeta el techo. La cuenta permite 300 peticiones por minuto por clave, por lo que un gateway que distribuya a muchos usuarios necesita su propia cola.

Ninguno de estos pasos depende de un SDK de proveedor. Un cliente HTTP básico que establezca el encabezado Bearer y decodifique JSON es suficiente, y los ejemplos de SDK en esta página son comodidades, no requisitos. Combina esta lista de verificación con la tabla de errores en el manual y cubres todo el ciclo de vida de la petición: construir, enviar, transmitir, analizar, contabilizar y recuperar.