Referencia de la API

unbleep habla la API de Chat Completions de OpenAI. Si ya has llamado a OpenAI antes, ya conoces esta API: apunta tu cliente a https://unbleep.ai/v1 y cambia la clave.

Inicio rápido

Instala el SDK de OpenAI, configura la URL base y tu clave, y haz una llamada.

from openai import OpenAI

client = OpenAI(
    base_url="https://unbleep.ai/v1",
    api_key="ub_live_9f2c…",
)

resp = client.chat.completions.create(
    model="unbleep",
    messages=[{"role": "user", "content": "Say hello."}],
)
print(resp.choices[0].message.content)

Autenticación

Cada solicitud necesita un token Bearer en la cabecera Authorization. Las claves llevan un prefijo para que una filtración sea evidente para los escáneres de secretos:

• ub_live_…: producción, se factura contra tu crédito prepago.
• ub_test_…: para desarrollo local. Se factura exactamente igual que una clave live, a la misma tarifa por token y contra el mismo crédito prepago; la única diferencia es un límite de tasa por clave más bajo (ver Límites de tasa). Una clave de prueba es una credencial independiente y revocable, no un nivel gratuito.

Authorization: Bearer ub_live_9f2c…

Mantén las claves en el servidor. Nunca incluyas una clave live en código de navegador o de aplicación móvil.

Modelos

Pasa uno de estos ID como model. El alias sin fecha apunta siempre a la última versión; los ID de snapshot con fecha también se aceptan y actualmente resuelven a esa misma versión. Envíes la forma que envíes, la respuesta devuelve el ID sin fecha: una solicitud con unbleep-250811 vuelve como "model": "unbleep".

Chat completions

POST /v1/chat/completions: el endpoint principal. Los cuerpos de solicitud y respuesta siguen el esquema de OpenAI.

curl https://unbleep.ai/v1/chat/completions \
  -H "Authorization: Bearer ub_live_9f2c…" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "unbleep",
    "messages": [
      {"role": "system", "content": "You are terse."},
      {"role": "user", "content": "Explain abliteration in one line."}
    ],
    "temperature": 0.7,
    "max_tokens": 256
  }'

{
  "id": "chatcmpl_a1b2c3",
  "object": "chat.completion",
  "model": "unbleep",
  "choices": [{
    "index": 0,
    "message": { "role": "assistant", "content": "…" },
    "finish_reason": "stop"
  }],
  "usage": { "prompt_tokens": 24, "completion_tokens": 18, "total_tokens": 42 }
}

Streaming

Establece "stream": true para recibir Server-Sent Events. Cada evento es un chat.completion.chunk con un delta; el stream termina con un data: [DONE] literal.

data: {"choices":[{"delta":{"content":"Ab"}}]}
data: {"choices":[{"delta":{"content":"literation"}}]}
data: {"choices":[{"delta":{},"finish_reason":"stop"}]}
data: [DONE]

Razonamiento

Los modelos de razonamiento piensan antes de responder. La traza vuelve como reasoning_content junto al content habitual: en message en una llamada normal, y en delta durante el streaming. El campo solo está presente cuando el modelo produjo realmente una traza, así que trátalo como opcional y lee content para obtener la respuesta en sí.

{
  "index": 0,
  "message": {
    "role": "assistant",
    "reasoning_content": "The question asks for one line, so…",
    "content": "…"
  },
  "finish_reason": "stop"
}

Los tokens de razonamiento se facturan. La traza es salida generada y se cobra a la tarifa de salida normal del modelo, lea tu código el campo o no. Una deliberación larga sobre una pregunta corta es una línea real en tu factura.

Envía "thinking": false para desactivar el razonamiento, de modo que el presupuesto de la respuesta vaya a la respuesta en lugar de a la traza:

{
  "model": "unbleep",
  "messages": […],
  "thinking": false
}

Dial de política

El diferenciador de unbleep. El parámetro opcional policy define cuánta gobernanza se aplica a una solicitud. Por defecto es off.

• off: línea base sin filtrar (predeterminado). No se inyecta ningún rechazo.
• research: responde exactamente igual que off. El valor se registra en la fila de uso para tus propios informes; no aplica ninguna revisión adicional.
• strict: contrasta el texto del mensaje con la lista de bloqueo del servicio y devuelve un error de política si hay coincidencia. La lista de bloqueo la mantiene el operador y se aplica a todos los que la activan; no hay una lista de bloqueo por cuenta que configurar.

{
  "model": "unbleep",
  "messages": […],
  "policy": "research"
}

Errores

Los errores usan el envoltorio de OpenAI, así que tu manejo de errores actual funciona sin cambios.

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_api_key",
    "message": "Incorrect API key provided."
  }
}

Límites de tasa

Se aplican dos límites independientes, ambos por cuenta: una tasa de solicitudes y un tope de concurrencia.

Tasa de solicitudes

60 solicitudes por minuto por cuenta, medidas en una ventana deslizante de 60 segundos. El límite es de la cuenta, no de la clave: crear claves adicionales no compra más rendimiento, y todas las claves que posees consumen de las mismas 60. Una clave de prueba tiene un techo por clave más bajo, de 15 solicitudes por minuto; aun así cuenta contra la misma ventana de la cuenta.

Cada respuesta lleva las cabeceras estándar para que puedas dosificar las solicitudes sin adivinar. Informan de la ventana que esté más cerca de frenarte:

x-ratelimit-limit-requests: 60
x-ratelimit-remaining-requests: 58
x-ratelimit-reset-requests: 43

x-ratelimit-reset-requests es un entero sin más: segundos enteros hasta que la ventana libere un hueco, sin sufijo de unidad. Parséalo como número, no como cadena de duración.

Concurrencia

Como máximo 8 solicitudes en vuelo a la vez por cuenta. Una novena solicitud concurrente se rechaza de inmediato con 429 y el código too_many_concurrent_requests; la respuesta lleva retry-after: 1. No se factura nada por una solicitud rechazada. Una llamada en streaming conserva su hueco hasta que el stream termina, así que los streams largos son lo que suele llevarte al tope.

{
  "error": {
    "type": "rate_limit_error",
    "code": "too_many_concurrent_requests",
    "message": "Too many concurrent requests for this account (limit 8)."
  }
}

Ambos techos son fijos para las cuentas estándar: no escalan con tu saldo prepago. ¿Necesitas más margen? Enterprise los eleva.