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 flujos de Studio lo usan sin que configures nada; también puedes llamarlo desde tu propio código.

Qué hace por ti

• Trabajo en lote. Miles de peticiones en un archivo, que corren por su cuenta y no gastan tus peticiones por minuto (Procesar peticiones en lote).
• Un solo punto de acceso. Cambias de modelo cambiando el nombre en la petición, no la integración. Llama por el alias público (Saptiva Turbo): es un nombre estable que el administrador mantiene apuntando al modelo vigente. El nombre exacto del Catálogo (Qwen3.6 35B A3B (FP8)) también funciona, pero cambia cuando se actualiza el modelo y entonces tu código deja de encontrarlo (Elegir modelo: usa el alias).
• 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 AI 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	Solo en la ficha del modelo (GET /v1/models/{name}) pedida por alias: nombra el modelo al que apunta. Las respuestas de inferencia no la traen; ahí el modelo que contestó viene en el campo model.
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.

Siguiente paso

• Usar la API desde código
• Credenciales