Referencia de la API
La autenticación, la superficie de endpoints compatible con OpenAI, el streaming, el razonamiento y la taxonomía de errores.
Autenticación
Cada petición a /v1/* se autentica con una clave virtual en la cabecera Authorization: Bearer. Acuñe claves en la Consola; el secreto se muestra una sola vez y solo se almacena su hash. Una clave lleva sus propios límites de tasa, presupuesto, etiquetas y una lista opcional de modelos permitidos (vacía = cualquier modelo).
Una petición cuyo modelo no está en la lista de permitidos no vacía de la clave se rechaza con un 403 permission_error sellado antes de despachar nada; el propio rechazo queda registrado en la cadena de auditoría.
Acuñar una clave de producción requiere una dirección de correo verificada.
curl https://api.sluis.ai/v1/models \ -H "Authorization: Bearer $SLUIS_KEY" # a model outside the key's allow-list never dispatches: # → 403 permission_error · the refusal is sealed in the audit chain
{
"object": "list",
"data": [
{ "id": "mistral/mistral-large-latest", "object": "model", "owned_by": "mistral" },
{ "id": "vertex/claude-opus-4-8", "object": "model", "owned_by": "vertex" },
{ "id": "sluis/auto", "object": "model", "owned_by": "sluis" }
]
}Endpoints
Sluis expone la superficie compatible con OpenAI que se muestra a continuación. Los endpoints sin un handler de primera clase se retransmiten literalmente al proveedor enrutado, streaming incluido, de modo que los upstreams compatibles con OpenAI conservan plena fidelidad.
| Endpoint | Propósito |
|---|---|
| POST /v1/chat/completions | Chat completions, la superficie principal: enrutamiento, protección de datos, caché, streaming. |
| POST /v1/completions | Text completions heredadas. |
| POST /v1/embeddings | Embeddings; también alimenta la caché semántica. |
| POST /v1/moderations | Clasificación de moderación. |
| POST /v1/responses | La API de Responses de OpenAI. |
| POST /v1/ocr | OCR de documentos (Mistral, o totalmente local con el modelo sluis/ocr) · facturado por página. Con la política dlp_documents activa, los documentos inline se anonimizan antes de salir. |
| POST /v1/documents/anonymize | Anonimización de documentos · los PII se convierten en «MERGE_TAG»s, las imágenes se difuminan · facturado por página/imagen. |
| POST /v1/documents/anonymize/jobs | Trabajos de anonimización asíncronos · encole documentos grandes, consulte el estado y recoja el resultado con una URL firmada de duración limitada sin clave de API. |
| GET /v1/models | Los modelos que su política y sus credenciales pueden alcanzar de verdad, nada hipotético. |
| GET /v1/models/{id} | Metadatos de un modelo. |
| POST /v1/audio/* | Transcripción, traducción, voz · retransmitido al proveedor enrutado. |
| POST /v1/images/* | Generación y edición de imágenes · retransmitido. |
| POST /v1/video/generations | Generación de vídeo · retransmitido. |
| /v1/files | Operaciones con archivos · retransmitido. |
| POST /v1/messages | Entrada nativa Anthropic Messages · apunte cualquier herramienta con SDK de Anthropic a Sluis; cualquier modelo conectado. |
| POST /v1/messages/count_tokens | Estimación local de tokens para la gestión de contexto del SDK de Anthropic; no se envía nada. |
| POST /v1beta/models/{model}:generateContent | Entrada nativa de Google Gemini · apunte un SDK de Gemini a Sluis (:streamGenerateContent transmite). |
curl https://api.sluis.ai/v1/chat/completions \ -H "Authorization: Bearer $SLUIS_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "mistral/mistral-large-latest", "messages": [{ "role": "user", "content": "Say hi" }] }'
{
"id": "chatcmpl-9f2e…",
"object": "chat.completion",
"model": "mistral-large-latest",
"choices": [{
"index": 0,
"message": { "role": "assistant", "content": "Hi! How can I help?" },
"finish_reason": "stop"
}],
"usage": { "prompt_tokens": 9, "completion_tokens": 8, "total_tokens": 17 }
}# Document OCR, billed per page. Returns pages[] markdown + usage_info.pages_processed. # model "sluis/ocr" runs the gateway's own OCR engine: fully local, no provider egress (inline data: URLs only). curl https://api.sluis.ai/v1/ocr \ -H "Authorization: Bearer $SLUIS_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "mistral/mistral-ocr-latest", "document": { "type": "document_url", "document_url": "https://example.com/invoice.pdf" } }'
{
"pages": [{
"index": 0,
"markdown": "# Invoice 2026-118\nAcme BV · Keizersgracht 1…",
"images": [],
"dimensions": { "dpi": 150, "height": 1754, "width": 1240 }
}],
"model": "mistral-ocr-latest",
"usage_info": { "pages_processed": 1, "doc_size_bytes": 48213 }
}# Document anonymization, billed per page/image. PII becomes «MERGE_TAG»s; images are blurred. curl https://api.sluis.ai/v1/documents/anonymize \ -H "Authorization: Bearer $SLUIS_KEY" \ -F file=@contract.docx \ -F 'options={ "entities": ["person_name", "email", "iban"], "include_mapping": true }'
{
"filename": "contract.docx",
"content_type": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
"content_base64": "UEsDBBQABgAIA…",
"summary": { "pages": 4, "images": 1, "categories": ["EMAIL", "IBAN", "PERSON_NAME"], "downgraded": false },
"mapping": [
{ "token": "«PERSON_NAME_1»", "original": "Jan de Vries" },
{ "token": "«IBAN_1»", "original": "NL91ABNA0417164300" }
]
}Streaming
Ponga stream: true y la respuesta llega como server-sent events: cada frame es un delta chat.completion.chunk y el stream termina con data: [DONE]. Los streams nunca se almacenan en búfer en la pasarela: pasan a través de ella en modo tee, y el sellado de auditoría y la medición ocurren aunque el cliente cuelgue antes de tiempo.
Pida stream_options.include_usage y el frame final lleva el uso exacto de tokens, las mismas cifras que la pasarela mide y factura.
stream = client.chat.completions.create(
model="mistral/mistral-large-latest",
messages=[{"role": "user", "content": "Write a haiku"}],
stream=True,
stream_options={"include_usage": True},
)
for chunk in stream:
print(chunk.choices[0].delta.content or "", end="")const stream = await client.chat.completions.create({ model: "mistral/mistral-large-latest", messages: [{ role: "user", content: "Write a haiku" }], stream: true, stream_options: { include_usage: true }, }); for await (const chunk of stream) { process.stdout.write(chunk.choices[0]?.delta?.content ?? ""); }
# the raw event stream on the wire
data: {"object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":"Water"}}]}
data: {"object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":" finds a way."}}]}
data: {"object":"chat.completion.chunk","choices":[{"index":0,"delta":{},"finish_reason":"stop"}],"usage":{"prompt_tokens":12,"completion_tokens":9,"total_tokens":21}}
data: [DONE]Razonamiento
Pase el parámetro OpenAI reasoning_effort (minimal | low | medium | high) en cualquier modelo con capacidad de razonamiento. Sluis lo traduce por proveedor (el nivel de pensamiento de Gemini, el esfuerzo de pensamiento adaptativo de Claude) y lo omite donde un modelo lo rechazaría, así que un solo parámetro funciona en todo el catálogo.
resp = client.chat.completions.create(
model="vertex/claude-opus-4-8",
messages=[{"role": "user", "content": "Prove it step by step…"}],
reasoning_effort="high", # minimal | low | medium | high
)Códigos de error
Los errores usan el sobre de error de OpenAI; el valor error.type refleja el estado HTTP, así que el manejo de errores de su SDK sigue funcionando sin cambios.
| Código | Cuándo |
|---|---|
| 400 invalid_request_error | Cuerpo de la petición o parámetros mal formados. |
| 400 invalid_request_error | Identificador de modelo sin prefijo de proveedor. Cada identificador invocable es provider/model, p. ej. mistral/mistral-large-latest; el cuerpo indica: model must be provider-prefixed. |
| 401 authentication_error | Clave de API ausente o desconocida. |
| 402 insufficient_quota | Asignación gratuita agotada o presupuesto alcanzado. Active un plan o suba el presupuesto; la petición nunca llega a un proveedor. |
| 403 permission_error | La clave carece de permiso, por ejemplo el modelo no está en su lista de permitidos. |
| 422 invalid_request_error | Rechazada antes de despachar, por ejemplo la protección de datos en modo block coincidió con la petición. |
| 429 rate_limit_error | Límite de tasa alcanzado. Se aplica en la pasarela; la petición nunca llega a un proveedor. |
| 451 permission_error | Bloqueada por la política de residencia: ninguna jurisdicción permitida sirve la petición. El cuerpo incluye el motivo. |
| 5xx api_error | Fallo del proveedor upstream tras los reintentos; el cortacircuitos desvía el tráfico de los proveedores no saludables. |
{
"error": {
"message": "model must be provider-prefixed, e.g. mistral/mistral-large-latest",
"type": "invalid_request_error",
"param": null,
"code": "invalid_request"
}
}{
"error": {
"message": "model is not on this key's allow-list",
"type": "permission_error",
"param": null,
"code": "permission_denied"
}
}{
"error": {
"message": "blocked by residency policy: provider jurisdiction US is not in the allowed set [EU]",
"type": "permission_error",
"param": null,
"code": "permission_denied"
}
}