InferNode

InferNode es el gateway de modelos de Saptiva. Expone los modelos de tu infraestructura y los de proveedores externos detrás de una sola API compatible con OpenAI. Los agentes y workflows de Studio lo usan sin que configures nada; también puedes llamarlo desde tu propio código.

Qué hace por ti

Un solo punto de acceso. Cambias de modelo cambiando el nombre en la petición, no la integración. Los identificadores son los del Catálogo (Qwen/Qwen3.6-27B-FP8) o el alias público que el administrador dio al activarlo.
Límites por plan. Cinco contadores: peticiones por minuto y por día, tokens por minuto y por día, e imágenes por minuto. Se aplican por organización, por usuario y por llave. Cada respuesta indica cuánto te queda en las cabeceras X-RateLimit-*; un 429 trae Retry-After y el contador que se superó.
Créditos. Cada llamada tiene un costo en créditos (USD) que se descuenta del saldo del Cliente; la respuesta incluye el costo (X-Request-Cost) y el saldo restante (X-Credits-Remaining). X-Credits-Warning aparece cuando el saldo es bajo. Un plan puede ser exento de facturación (habitual en instalaciones on-prem): entonces X-Request-Cost sigue informando el costo teórico, pero no se descuenta nada y no hay X-Credits-Remaining. El administrador puede fijar topes de gasto por organización, usuario o llave.
Guardas de contenido. Opcionalmente, las conversaciones se evalúan contra categorías de riesgo con un modelo de guarda del Catálogo y quedan registradas con su categoría.
Trazabilidad. Cada petición lleva X-Request-Id; es lo que Saptiva necesita para investigar una llamada.

Cómo se cuenta una llamada

Los tokens de entrada (tu prompt, el historial y los documentos que el agente incluye) cuestan menos que los de salida, y el precio por token depende del modelo (GET /v1/models/{name} lo muestra). Un agente con Historial amplio y Longitud larga consume varias veces más créditos por mensaje que uno con Historial normal y Longitud corta.

Endpoints

Endpoint	Para qué
`POST /v1/chat/completions`	Conversación con un modelo. Admite streaming, herramientas, formato JSON.
`POST /v1/embeddings`	Vectores para búsqueda semántica (modelos de tipo Embeddings).
`POST /v1/images/generations`	Generación de imágenes (asíncrona: devuelve un trabajo que consultas con `GET /v1/images/generations/{job_id}`).
`POST /v1/guard`	Evaluar un texto contra las guardas de contenido sin generar respuesta.
`GET /v1/models`	Modelos disponibles para tu llave, con tipo, capacidades, contexto, máximo de salida y precio por token.
`GET /v1/models/{name}`	Ficha de un modelo. Si `name` es un alias, responde con `X-Alias-Of`.
`GET /v1/models/aliases`	Alias públicos (nombres estables que apuntan a un modelo).
`GET /v1/me`	Tu identidad, plan y límites.
`GET /v1/billing/balance`	Saldo, plan, topes de gasto y consumo del mes.
`GET /v1/billing/usage?period=AAAA-MM`	Consumo del mes: peticiones, tokens de entrada y salida, costo, desglose por modelo, por llave y por día.
`GET /v1/billing/transactions`	Movimientos de créditos (`debit` y `credit`) con totales del periodo.

Cabeceras de respuesta

Cabecera	Significado
`X-Request-Id`	Identificador de la petición. Inclúyelo en cualquier reporte.
`X-RateLimit-Limit-Requests`, `X-RateLimit-Remaining-Requests`, `X-RateLimit-Reset-Requests`	Límite, restante y momento de reinicio, en peticiones.
`X-RateLimit-Limit-Tokens`, `X-RateLimit-Remaining-Tokens`, `X-RateLimit-Reset-Tokens`	Lo mismo en tokens.
`X-Request-Cost`, `X-Credits-Remaining`, `X-Credits-Warning`	Costo de esta llamada, saldo y aviso cuando el saldo es bajo.
`X-Model-Deprecated`, `X-Model-Retires-At`	El modelo está en retiro y la fecha en que dejará de responder. La ficha del modelo (`deprecation`) indica por cuál sustituirlo.
`X-Alias-Of`	Pediste un alias; esta cabecera nombra el modelo real que respondió.
`X-Saptiva-Passthrough`, `X-Saptiva-Model-Defaults`	Parámetros que se reenviaron al modelo sin validar, y valores por defecto que el administrador fijó para ese modelo.

Guardas de contenido

POST /v1/guard recibe input (una lista de mensajes con role y content, hasta 128) y opcionalmente model, y devuelve la puntuación por cada categoría de riesgo activa (código, etiqueta, severidad). Con guard: true en chat/completions, la evaluación se hace sobre la conversación completa después de responder y queda registrada; GET /v1/guard/events lista las evaluaciones de tu Cliente. Los modelos de guarda aparecen en el Catálogo con tipo Otros (por ejemplo, un modelo de content safety).

Errores

La envoltura es la de OpenAI con dos campos más: code con el módulo como prefijo cuando aplica, y request_id.

{
  "error": {
    "type": "authentication_error",
    "code": "identity.invalid_token",
    "message": "Missing or malformed bearer token.",
    "param": null,
    "request_id": "req_3026fcfe4c8c4a59b4fc82a5db8ae6da"
  }
}

Código HTTP	`type`	Qué pasó
401	`authentication_error`	`identity.invalid_token`: falta la cabecera o está mal formada. `identity.unauthorized`: la llave no existe, fue revocada, o su cuenta u organización están suspendidas ("Token is invalid, revoked, or for a suspended org / disabled user").
403	`permission_error`	La llave no tiene acceso a ese modelo o recurso.
404	`not_found_error` (`model_not_found`)	El nombre de modelo no existe para tu plan.
402	`billing_error` (`insufficient_credits`)	Sin créditos.
429	`rate_limit_error` (`rate_limit_exceeded`)	Límite de peticiones o tokens. Espera lo que indique `X-RateLimit-Reset-*`.
502	`provider_error`	El proveedor del modelo falló. Reintenta con espera exponencial.
503	`maintenance_error`	Mantenimiento programado.

Qué hace por ti​

Cómo se cuenta una llamada​

Endpoints​

Cabeceras de respuesta​

Guardas de contenido​

Errores​

Siguiente paso​