Vai al contenuto

Riferimento API

Autenticazione, endpoint, streaming, reasoning ed errori sulla superficie OpenAI, API native Anthropic e matrice di compatibilità per endpoint.

Autenticazione

Ogni richiesta a /v1/* si autentica con una chiave virtuale nell'header Authorization: Bearer. Crea le chiavi in Workload nella Console.

  • Il segreto viene mostrato una sola volta e ne viene memorizzato solo l'hash.
  • Una chiave è una credenziale per un workload. Il workload gestisce limiti di frequenza, budget, modelli consentiti e deroghe alle policy. La policy dell'organizzazione continua ad applicarsi.
  • Una chiave può avere una scadenza facoltativa. Dopo di essa, la chiave viene rifiutata esattamente come una chiave sconosciuta.
  • Un modello che non è nella lista di consentiti non vuota del workload viene rifiutato con un 403 permission_error sigillato, prima che venga inoltrato alcunché. Il rifiuto stesso finisce nella catena di audit.
  • Un workload può limitare le sue chiavi a famiglie di endpoint, per esempio chat ed embeddings. Le altre famiglie ricevono un 403 operation_not_allowed sigillato, prima che venga inoltrato alcunché.
  • Per creare una chiave di produzione serve un indirizzo email verificato.
  • Un'eccezione: i link di download firmati e a tempo per i documenti anonimizzati non richiedono alcuna chiave.
Credenziali del workload: gestisci le chiavi API e le impostazioni di accesso.
Credenziali del workload: gestisci le chiavi API e le impostazioni di accesso.Interfaccia in inglese · dati dimostrativi illustrativi. Apri l’immagine a dimensione intera.
curl https://api.sluis.ai/v1/models \
  -H "Authorization: Bearer $SLUIS_KEY"

# a model outside the workload's allow-list never dispatches:
# → 403 permission_error, and the refusal is sealed in the audit chain

Endpoint

Sluis espone la superficie compatibile con OpenAI qui sotto, più i percorsi Anthropic nativi descritti più avanti.

Gli endpoint senza un handler dedicato vengono inoltrati tali e quali al provider instradato, streaming compreso, così gli upstream compatibili con OpenAI mantengono piena fedeltà.

Un browser che apre un percorso che l'API non serve, come l'host API nudo, viene reindirizzato a questa documentazione. I client API ricevono invece un semplice 404.

EndpointScopo
POST /v1/chat/completionsChat completions, la superficie principale: instradamento, protezione dei dati, caching, streaming.
POST /v1/completionsCompletamenti di testo legacy.
POST /v1/embeddingsEmbeddings.
POST /v1/moderationsClassificazione di moderazione.
POST /v1/responsesL'API OpenAI Responses.
POST /v1/systemoneNative System One typed decisions, not OpenAI chat messages.
POST /v1/ocrOCR dei documenti (Mistral, oppure completamente locale con il modello sluis/ocr), fatturato per pagina. Con la policy dlp_documents attiva, i documenti inline vengono anonimizzati prima di uscire.
POST /v1/documents/anonymizeAnonimizzazione dei documenti: i dati personali sostituiti da «MERGE_TAG», le immagini sfocate. Fatturata per pagina o immagine.
POST /v1/documents/anonymize/jobsJob di anonimizzazione asincroni: metti in coda un documento grande, controlla /jobs/{id} e recupera /jobs/{id}/result. Il link di download firmato (/v1/documents/deliverables/{id}) è a tempo e non richiede chiave API.
GET /v1/modelsModelli consentiti dalla tua policy, credenziali e workload, con tipo, finestra di contesto, capacità, residenza, destinazione dell'alias e prezzo finale di questa organizzazione in EUR, IVA esclusa.
GET /v1/models/{id}Metadati e prezzo specifico dell'organizzazione per un modello, nello stesso formato della lista.
POST /v1/audio/*Trascrizione, traduzione e voce, inoltrate al provider instradato. Con il modello sluis/transcribe, POST /v1/audio/transcriptions esegue il riconoscimento vocale proprio di Sluis con rilevamento dei parlanti. Vedi Voce in testo.
POST /v1/images/*Generazione e modifica di immagini, inoltrate. mistral/image-generation è l'eccezione: Mistral la serve solo tramite il suo connettore agent, quindi il gateway traduce la richiesta OpenAI e risponde con b64_json, fatturata per immagine.
POST /v1/video/generationsGenerazione di video, inoltrata.
/v1/filesOperazioni sui file, inoltrate con la chiave propria della tua organizzazione (BYOK o provider personalizzato). I file con purpose=batch sono l'eccezione: passano dal gate del gateway e possono usare chiavi gestite.
/v1/batchesBatch in formato OpenAI: carica un file JSONL con purpose=batch su /v1/files, poi crea, controlla e annulla qui. Ogni riga passa protezione dei dati e residenza come una chiamata live. I risultati arrivano entro 24 ore, fatturati a metà del prezzo live. Mistral, Azure, OpenAI e Qwen.
POST /v1/messages/batchesAnthropic Message Batches: create, list, get, results e cancel. Disattivate a meno che la tua installazione non le abiliti. Richiedono la conservazione dei contenuti e girano solo su modelli Anthropic. Altrimenti queste rotte restituiscono 404.
POST /v1/messagesIngresso nativo Anthropic Messages: punta qualsiasi strumento con SDK Anthropic su Sluis, con qualsiasi modello connesso.
POST /v1/messages/count_tokensStima locale dei token per la gestione del contesto degli SDK Anthropic. Non viene inviato nulla.
GET /anthropic/v1/modelsIndividuazione nativa dei modelli Anthropic (list e get), servita dal catalogo in-process. Su /v1/models l'header anthropic-version seleziona la stessa forma.
HEAD /api/helloSonda di riscaldamento per i client SDK Anthropic come Claude Code: 200 con corpo vuoto.
GET /v1/realtimeWebSocket compatibile con OpenAI Realtime per la voce dal vivo (speech to speech) con vertex/gemini-3.8-live, ospitato nella multi-regione UE su Google Vertex AI. Disponibile anche su /openai/v1/realtime; il parametro di query model è obbligatorio. Autentica la richiesta di upgrade con Authorization: Bearer o x-api-key. Parla i nomi di evento GA; i formati beta OpenAI-Beta: realtime=v1, i segreti client effimeri, le chiavi via sotto-protocollo del browser e l'audio G.711 non sono supportati. Strumenti lato server, ripresa della sessione, replica della voce e output avatar vengono rifiutati in fase di setup. Il testo è protetto come su ogni endpoint; i frame audio e video vengono inoltrati senza ispezione. Una sessione termina al tetto di spesa di 2 EUR, e il provider chiude una connessione dopo circa 10 minuti; riconnettiti per continuare. Fatturazione per token alle tariffe per modalità del modello (testo, audio, frame immagine e video), dal report di utilizzo del provider. Non disponibile in Sluis Workspace, nel Playground né negli alias sluis/*. L'elenco completo degli eventi è nell'agent skill.
GET /ws/google.ai.generativelanguage.v1beta.GenerativeService.BidiGenerateContentWebSocket Gemini Live nativo (BidiGenerateContent), anche su /ws/google.cloud.aiplatform.v1.LlmBidiService/BidiGenerateContent; la versione nel nome del servizio può essere v1, v1beta, v1beta1 o v1alpha. Un SDK google-genai con l'origine della gateway come URL base si connette senza modifiche. Autentica la richiesta di upgrade con x-goog-api-key, Authorization: Bearer o x-api-key; il parametro di query ?key= non è accettato. I frame vengono inoltrati come li definisce il protocollo Gemini Live, e setup.model è gemini-3.8-live. I rifiuti arrivano come frame di chiusura WebSocket con il motivo in testo. Stesso modello, stessi limiti, stessa protezione dei dati e stessa fatturazione di /v1/realtime.
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" }] }'
Playground con un modello selezionato e una richiesta di esempio completata.
Playground con un modello selezionato e una richiesta di esempio completata.Interfaccia in inglese · dati dimostrativi illustrativi. Apri l’immagine a dimensione intera.

Ogni body JSON qui sopra può portare anche l'estensione della gateway sluis.remove, che nomina i termini da pseudonimizzare nel prompt prima dell'invio. Viene rimossa prima che la richiesta lasci la gateway; vedi il riferimento Protezione dei dati.

# 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" } }'

Voce in testo con rilevamento dei parlanti

Imposta il modello su sluis/transcribe e invia POST /v1/audio/transcriptions. Il gateway esegue il proprio riconoscimento vocale, senza uscita verso provider.

  • Invia un file multipart fino a 240 minuti. La lingua viene rilevata automaticamente.
  • response_format è json (il default), text oppure verbose_json (segmenti con un parlante).
  • Fatturato a 0,02 € al minuto di audio, per secondo iniziato.
  • La modalità DLP dell'organizzazione si applica alla trascrizione, come per sluis/ocr.
  • Risponde 503 dove l'installazione non esegue la trascrizione.
# Speech to text with speaker detection, billed €0.02 per minute of audio (per started second).
# model "sluis/transcribe" runs in the gateway's own worker: no provider egress, language detected automatically.
curl https://api.sluis.ai/v1/audio/transcriptions \
  -H "Authorization: Bearer $SLUIS_KEY" \
  -F model=sluis/transcribe \
  -F response_format=verbose_json \
  -F file=@meeting.m4a
# 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"], "remove": ["Project Nightingale"] }'
Playground Documents: carica un documento da anonimizzare.
Playground Documents: carica un documento da anonimizzare.Interfaccia in inglese · dati dimostrativi illustrativi. Apri l’immagine a dimensione intera.

System One typed decisions

# The router behind sluis/auto: send state only, not questions.
curl https://api.sluis.ai/v1/systemone \
  -H "Authorization: Bearer $SLUIS_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"sluis/typed/router",
       "state":{"request":"Compare these two supplier contracts clause by clause and list the risks.",
                "previous":"Here are both contracts.",
                "attachments":["contract_a.pdf (application/pdf)","contract_b.pdf (application/pdf)"]}}'
Local router contract (sluis/typed/router)Behaviour
Model idssluis/typed/router is the router Sluis uses for sluis/auto, with its own calibrated questions. For your own questions, use a typesafe/jev-* model with your own TypeSafe key.
sluis/typed/routerSend the text a request carries: state.request (required), and optional previous, system and attachments (a string or a list of "name (mime)" strings); a plain string is the request. It answers reasoning (noul, P(needs multi-step reasoning)), complexity (score, 0 trivial to 3 hard, with legend and probabilities per level) and task (choice over code, writing, translation, extraction, document, support, smalltalk, action). decision holds the route and demand sluis/auto would take from this text alone, or null. Files, images, JSON mode, tools, prompt size and your organisation's policy are not part of this input and can change a real sluis/auto route. answers.reasoning keeps the keys it always had; the rest is additional.
TypeSafeBring your own key only; no sluis/* alias reaches it. Name the model explicitly, for example typesafe/jev-latest. The normal gate applies: it is a US provider, so your residency policy must allow US. The other rows describe sluis/typed/router only.
AvailabilityEvery answer comes from verified model weights, reported as revision. If the router is unavailable or cannot be verified, the call fails closed with 503.
StateRequired JSON object, list (array) or string, at most 128 KiB (131072 bytes) of serialized JSON before DLP. Missing or invalid state returns 422; oversized state returns 413.
Questionssluis/typed/router supplies its own calibrated questions: any questions field, including null or an empty object, returns 400.
ResponseJSON with model, answers, decision and revision (weights SHA256). Each answer has its type, its typed value (choice, score or noul), confidence, probabilities, legend and answer_confidence. No chat completion or streaming envelope.
Latencysluis/typed/router usually answers well under 200 ms; when busy it returns 503 with Retry-After: 2.
Data protectionTenant DLP applies locally to the state: block refuses; tokenize or mask rewrites what the router is shown. Per-request removal terms are honoured.
ResidencyProcessed on Sluis infrastructure with no outside provider and no upstream residency routing step.
MeteringEach successful local decision is sealed and billed per input token at €0.01 per 1M tokens; output is free. The router reports no token count, so input is estimated at about 4 characters per token over the state it was shown. Normal limits, budgets and model allow-lists still apply.
AliasesAn existing tenant alias with the same name takes precedence over the local router.

Documenti in input

Allega un file PDF, Word, immagine o di testo semplice a una richiesta chat come parte di contenuto "type": "file" con un data URL base64 in file_data.

Qualsiasi modello instradato lo accetta. I provider che capiscono nativamente le parti file le ricevono invariate. Per tutti gli altri provider il gateway converte il documento prima del dispatch.

Come il modello riceve il documento

  • Con un renderer PDF, i modelli con visione ricevono ogni pagina del PDF come parte image_url. Il budget è di 48 pagine per richiesta, condiviso tra tutti i documenti allegati, e possono valere i limiti del provider. Senza renderer, il fallback dell'installazione estrae il testo oppure rifiuta.
  • I modelli senza input immagine ricevono il testo estraibile del documento come testo del prompt. La scansione di protezione dei dati lo copre poi come ogni altro testo.
  • I documenti più lunghi o più pesanti vanno su /v1/ocr.
  • La Responses API usa parti input_file invece della forma file annidata delle chat completions.
  • Sluis non può ispezionare né risolvere i riferimenti file_id lato provider. Passano solo a un provider che li supporta, con la tua chiave provider e con l'ispezione dei documenti disattivata. Altrimenti inserisci i byte inline come file_data.

Protezione dei dati per i documenti

  • Con la policy dlp_documents attiva, il documento viene anonimizzato o rifiutato prima che qualcosa lasci il gateway.
  • Se è disattivata e la modalità DLP è protettiva (tokenize, mask o block), i documenti che viaggerebbero come immagini non ispezionabili vengono rifiutati. Con allow_log passano con un marcatore esplicito di non analizzato nel registro di audit.
  • Le parti audio (input_audio) non possono essere analizzate. block o il riconoscimento IA obbligatorio con ispezione documenti attiva le rifiuta con 422. Altrimenti riportano x-sluis-unscanned: audio.
# Attach a document as an OpenAI-style `file` content part. The gateway
# normalizes it for the routed provider, so this works on any model.
curl https://api.sluis.ai/v1/chat/completions \
  -H "Authorization: Bearer $SLUIS_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "model": "scaleway/gemma-4-26b-a4b-it",
        "messages": [{ "role": "user", "content": [
          { "type": "file",
            "file": { "filename": "drawing.pdf",
                      "file_data": "data:application/pdf;base64,'"$(base64 -w0 drawing.pdf)"'" } },
          { "type": "text", "text": "Which discipline does this drawing document?" }
        ] }] }'

Streaming

Imposta stream: true e la risposta arriva come server-sent events. Ogni frame è un delta chat.completion.chunk e lo stream termina con data: [DONE].

Gli stream non vengono mai bufferizzati nel gateway: lo attraversano in tee, e il sigillo di audit e la misurazione avvengono anche se il client si disconnette in anticipo.

Chiedi stream_options.include_usage e il gateway richiede al provider un frame finale di consumo. Se il provider non ne invia nessuno, o lo stream viene interrotto, il gateway stima il consumo per la misurazione.

Vuoi vedere quanto è costata alla tua organizzazione una chiamata in streaming? Invia x-sluis-include-cost: true insieme a stream_options.include_usage. L'oggetto usage finale contiene allora sluis_cost_eur, vedi Costo di una chiamata.

Bedrock separa il ragionamento dalla risposta in reasoning_content e reasoning_signature, anche nei delta dello stream. I rifiuti usano finish_reason: content_filter, i limiti di output length, anche con chiamate parziali agli strumenti. Non eseguire argomenti incompleti degli strumenti. Le eccezioni di streaming AWS diventano frame di errore senza dettagli sensibili.

Keepalive, header e riavvii

  • Dopo 15 secondi senza frame il gateway scrive una riga di commento SSE (: keepalive) tra gli eventi, così i proxy con timeout di inattività tengono aperta la connessione mentre un modello ragiona. I client SSE la ignorano.
  • Gli stream portano Cache-Control: no-cache e X-Accel-Buffering: no.
  • Quando una replica del gateway si riavvia, continua a servire gli stream aperti fino a cinque minuti. Uno stream ancora aperto dopo quel tempo termina con un evento di errore con codice server_restarting: ripeti la richiesta.
  • Gli stream tokenizzati accettano singoli eventi fino a 4 MiB. Eventi più grandi chiudono lo stream con un errore.
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="")

Ragionamento

Passa il parametro OpenAI reasoning_effort (minimal | low | medium | high) su qualsiasi modello capace di ragionare. Sluis lo traduce per ciascun provider (il livello di thinking di Gemini, l'effort di adaptive thinking di Claude) e lo omette dove un modello lo rifiuterebbe, così un solo parametro funziona su tutto il catalogo.

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
)

Cache dei prompt

I prefissi di prompt ripetuti (prompt di sistema, strumenti, cronologia della conversazione) possono essere messi in cache presso il provider per ridurre costi e latenza. Sluis traduce per ciascun provider i blocchi cache_control in stile Anthropic (TTL facoltativo di 5m o 1h) e i campi di primo livello OpenAI prompt_cache_key e prompt_cache_retention.

Più confini di breakpoint system o assistant possono fondersi nella traduzione, anche con TTL diversi.

ProviderComportamento della cache dei prompt
Anthropiccache_control esplicito su blocchi di sistema, contenuto e strumenti, TTL incluso. Letture e scritture sono riportate separatamente.
Bedrockcache_control diventa blocchi cachePoint di Converse in system, messages e toolConfig.
OpenAI · AzureCache automatica. Dopo l'attivazione, prompt_cache_key e prompt_cache_retention restano su chat e Responses; opzioni e marcatori non supportati vengono rimossi.
Gemini · VertexFunzionano la cache implicita Gemini e i relativi consumi; i riferimenti espliciti cachedContent non sono supportati. Claude su Vertex traduce cache_control e TTL come Anthropic.
xAI · DeepSeek · Mistral · Qwen · Moonshot · ZhipuCache automatica se disponibile; tutte le direttive esplicite vengono rimosse. Il campo nativo usage.cached_tokens di Moonshot è riconosciuto.
ScalewayCache automatica se disponibile; tutte le direttive esplicite vengono rimosse. Le letture usano la tariffa ufficiale Scaleway in EUR per input in cache, se disponibile, non LiteLLM.
NebulCache automatica se disponibile; tutte le direttive esplicite vengono rimosse. Le letture usano la tariffa ufficiale in EUR per input in cache, se disponibile.
Nebius · nebius-euCache automatica se disponibile; tutte le direttive esplicite vengono rimosse. I prezzi ufficiali non usano sconti cache LiteLLM; il fallback LiteLLM può fornire una tariffa cache in assenza del prezzo ufficiale del modello.
CustomDopo l'attivazione dell'organizzazione, le direttive passano inalterate; il supporto dipende dal contratto dell'operatore.

La cache esplicita dei prompt è opt-in

La cache esplicita dei prompt è un'impostazione a livello di organizzazione (provider_prompt_cache). È disattivata per default e indipendente dalla conservazione dei contenuti Sluis e dalla cache delle risposte esatte. Attivala in Console › Protezione dei dati.

  • I prefissi in cache restano presso il provider dopo che la protezione dei dati Sluis li ha filtrati.
  • Quando è disattivata, il gate rimuove prompt_cache_key, prompt_cache_retention, prompt_cache_options, cache_control e prompt_cache_breakpoint. Non disattiva la cache automatica propria del provider.
  • Senza una tua chiave per un provider, le chiamate usano una credenziale Sluis condivisa con altre organizzazioni. Su OpenAI e Azure, Sluis imposta un prompt_cache_key derivato dalla tua organizzazione al posto del tuo. Su ogni altro provider, i conteggi dei token in cache nei tuoi consumi mostrano 0. La fatturazione applica comunque il reale sconto cache.

Fatturazione e limiti

  • Letture e scritture della cache sono sottoinsiemi dei token di prompt totali, non input aggiuntivo. Le letture usano la tariffa cache disponibile.
  • Le scritture Anthropic 1h usano la tariffa specifica per TTL quando sono disponibili dettaglio dei consumi e tariffa. Altrimenti si applica la tariffa di creazione predefinita.
  • Una tariffa cache mancante significa prezzo di input ordinario, mai fatturazione zero.
  • I consumi della cache compaiono nel pannello di audit e in Utilizzo e budget.
  • I prompt lunghi sono fatturati alla tariffa a contesto lungo del provider. Quando il prompt (token in cache compresi) supera la soglia del modello, l'intera chiamata è fatturata a quella tariffa. Viene mostrata sotto il prezzo nella tabella dei modelli.

Con una chiave gestita da Sluis, Sluis rifiuta con 400 una richiesta, prima di inviare qualsiasi cosa, quando seleziona un sovrapprezzo che Sluis non può misurare:

  • un cache_control con ttl diverso da 5m, dove il provider lo rispetta (Anthropic, Bedrock, Claude su Vertex)
  • un service_tier diverso da auto, default, flex o standard_only
  • la beta Anthropic a contesto lungo (context-1m) su un modello per cui Sluis non ha una tariffa a contesto lungo

Con la tua chiave provider, tutti e tre vengono inoltrati invariati.

Codici di errore

Gli errori usano l'envelope di errore di OpenAI; il valore error.type rispecchia lo stato HTTP, così la gestione degli errori del tuo SDK continua a funzionare invariata.

CodiceQuando
400 invalid_request_errorCorpo o parametri della richiesta malformati.
400 invalid_request_errorAll'id del modello manca il prefisso del provider. Ogni id richiamabile è provider/model, per esempio mistral/mistral-large-latest. Il messaggio dice: model must be provider-prefixed.
400 invalid_request_errorLa richiesta contiene l'header rimosso x-sluis-dlp. Le deroghe per singola richiesta sono state sostituite dalle deroghe di opzione del workload: configurale in Console › Workload.
401 authentication_errorChiave API mancante o sconosciuta.
402 insufficient_quotaNessun piano attivo, oppure il budget è esaurito. Attiva un piano o aumenta il budget. La richiesta non raggiunge mai un provider.
403 permission_errorLa chiave non ha il permesso, per esempio il modello non è nella lista di consentiti del workload.
422 invalid_request_errorRifiutata prima del dispatch, per esempio la protezione dei dati in modalità block ha riconosciuto la richiesta.
422 document_too_large_to_scanUn documento è troppo grande per il percorso che ha preso: una pagina ancora oltre il limite di pixel di rendering alla risoluzione minima di scansione, oppure un file oltre il limite di byte per l'estrazione del testo. Le pagine di grande formato (disegni A0 e A1) vengono ridotte automaticamente. Riduci o dividi il documento e reinvia.
429 rate_limit_errorLimite di frequenza raggiunto. Applicato al gateway, quindi la richiesta non arriva mai a un provider.
403 permission_errorBloccata dalla policy di residenza: nessuna giurisdizione consentita serve la richiesta. Il corpo include il motivo.
403 scope_violationRifiutata dal controllo del perimetro del workload in modalità block: la chiamata esce dal perimetro scritto per quel workload. Il messaggio riporta il motivo del controllo e la richiesta non raggiunge mai un provider.
422 malware_detectedIl file caricato corrispondeva a una firma di malware ed è stato rifiutato prima di essere salvato o analizzato. Il nome della firma non viene mai restituito.
503 pdf_renderer_unavailableUn PDF inline doveva essere inviato come immagini delle pagine perché il modello instradato legge input immagine, ma questa installazione non ha un renderer PDF. Viene rifiutato invece di rispondere dal testo estratto, che scarterebbe ciò che mostra un disegno o una scansione.
503 malware_scan_unavailableIl file caricato non ha potuto essere analizzato per malware (scanner non disponibile o lento, oppure il file supera il limite di scansione di 100 MiB), quindi non è stato accettato. Non è stato salvato nulla. Riprova con backoff.
503 scope_guard_unavailableIl controllo del perimetro del workload è in modalità block ma non ha raggiunto un verdetto, quindi la chiamata viene rifiutata invece di essere lasciata passare. Riprova con backoff.
503 auth_unavailableIl gateway non ha potuto leggere il proprio archivio delle chiavi, quindi non ha potuto verificare la chiave. Non si sa che la chiave non sia valida. Riprova con backoff e rispetta Retry-After.
504 api_errorIl provider non ha risposto entro il timeout di risposta del workload: 300 secondi per default, da 10 a 600 se il workload lo imposta, meno se la richiesta ha inviato x-sluis-upstream-timeout. error.sluis.cause è timeout. Il gateway non ha ripetuto la chiamata, perché il provider potrebbe ancora eseguirla. Accorcia il prompt o chiedi un timeout più lungo prima di reinviare.
5xx api_errorErrore del provider upstream dopo i tentativi. Il circuit breaker devia il traffico dai provider non sani. Il corpo riporta il messaggio del provider stesso e un oggetto error.sluis che indica la causa e ogni tentativo, con il suo stato upstream o errore di trasporto e la durata.
{
  "error": {
    "message": "model must be provider-prefixed, e.g. \"mistral/mistral-large-latest\"",
    "type": "invalid_request_error",
    "param": null,
    "code": "invalid_request"
  }
}

Anthropic Messages API

Sluis parla nativamente l'API Anthropic Messages. Punta Claude Code o qualsiasi SDK Anthropic sul gateway e chiama POST /v1/messages. /anthropic/v1/messages è il percorso con prefisso, non ambiguo, verso lo stesso handler.

La richiesta viene tradotta nella forma interna, passa dalla stessa pipeline Inspect, Route, Seal e Meter di ogni altra chiamata e torna nel formato Anthropic, streaming compreso.

Autenticazione

  • Invia la tua chiave Sluis nell'header x-api-key di Anthropic oppure nel solito header Authorization: Bearer. Entrambi sono accettati.
  • L'header anthropic-version è accettato con qualsiasi valore e non è mai obbligatorio. Su GET /v1/models la sua presenza seleziona la forma Anthropic.
  • Il parsing è volutamente aperto: campi del corpo sconosciuti, tipi di blocco di contenuto sconosciuti, valori anthropic-beta sconosciuti e la query ?beta=true che Claude Code invia sono tollerati, non rifiutati.
  • I flag beta viaggiano byte per byte verso gli upstream della famiglia Anthropic e sono ignorati ovunque altrove.

Endpoint

EndpointScopo
POST /v1/messagesMessages, in buffer o in streaming. Supporta prompt di sistema (stringa o blocchi), strumenti e risultati degli strumenti (compresi risultati di errore e immagini al loro interno), immagini, blocchi documento, blocchi thinking e redacted_thinking nella cronologia e marcatori cache_control in ogni posizione memorizzabile in cache.
POST /v1/messages/count_tokensStima locale dei token per la gestione del contesto degli SDK. Non viene inviato, conservato né misurato nulla.
GET /v1/models · GET /v1/models/{id}Individuazione nativa dei modelli nella forma Anthropic, servita dal catalogo in-process. Sul percorso radice l'header anthropic-version seleziona questa forma e senza di esso ottieni la forma OpenAI. Sotto /anthropic si applica sempre. I cursori before_id, after_id e limit sono best effort e created_at è un segnaposto fisso perché il catalogo non ha una data di rilascio per modello.
HEAD /api/helloLa sonda di riscaldamento che Claude Code invia prima di una sessione: solo HEAD, con risposta 200 e corpo vuoto.

Instradamento del modello

Il formato di trasporto non limita mai il modello: l'ingresso è un codec e l'id del modello decide la rotta.

  • Un id semplice come claude-sonnet-5 si risolve tramite il provider predefinito di questo ingresso, anthropic, a meno che la tua organizzazione non lo punti altrove (per esempio a vertex per Claude ospitato nell'UE). Il gate di residenza decide comunque se quel target può servire la richiesta.
  • Fissa un target esplicitamente con un id con prefisso del provider, come vertex/claude-opus-4-8.
  • Oppure passa un alias sluis/*. Uno strumento con SDK Anthropic gira allora su qualsiasi provider connesso, dentro la tua policy.

Streaming

Con "stream": true la risposta usa la grammatica completa degli eventi Anthropic:

  • message_start, poi content_block_start, content_block_delta e content_block_stop per ogni blocco, poi message_delta con il consumo cumulativo (compresi i token di lettura e creazione della cache), poi message_stop.
  • Il testo arriva come text_delta, gli argomenti degli strumenti come input_json_delta e il ragionamento come thinking_delta più signature_delta quando il provider instradato l'ha prodotto.
  • message_start porta il conteggio dei token di input quando il provider lo riporta nel primo chunk. Altrimenti parte da zero e message_delta riporta il consumo aggiornato.
  • Un evento ping segue message_start e si ripete dopo circa 15 secondi di silenzio dell'upstream, così un lungo turno di ragionamento non fa mai scattare il watchdog di un client.
  • Un errore a metà stream viene ricodificato come evento error invece di uno stream troncato.
  • stop_sequence porta la sequenza corrispondente quando la risposta viene da un provider della famiglia Anthropic, ed è null altrimenti.
  • Invia x-sluis-include-cost: true e l'uso in message_delta contiene anche sluis_cost_eur, il prezzo della chiamata per la tua organizzazione in EUR, più sluis_cost_estimated: true solo in caso di stima. Vedi Costo di una chiamata.
# native Anthropic Messages: the model id owns the route, not the wire format
curl https://api.sluis.ai/v1/messages \
  -H "x-api-key: $SLUIS_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{ "model": "vertex/claude-opus-4-8",
        "max_tokens": 256,
        "system": "Be concise.",
        "messages": [{ "role": "user", "content": "Say hi" }] }'

# /anthropic/v1/messages is the unambiguous prefixed path for the same handler

Errori

Gli errori degli handler Messages usano l'envelope di Anthropic: un "type": "error" di primo livello con il tipo di errore del produttore. Questo include i rifiuti che non raggiungono mai un modello, come una chiave sconosciuta o un blocco della protezione dei dati.

I tipi del produttore sono invalid_request_error, authentication_error, billing_error, permission_error, not_found_error, conflict_error, request_too_large, rate_limit_error, api_error e overloaded_error.

  • La risposta porta un header request-id e un campo request_id nel corpo, l'id di correlazione per il tuo client.
  • Dove la chiamata ha prodotto una riga di audit, l'header x-sluis-request-id identifica quella riga. Un errore di autenticazione non ha riga di audit.
  • Le risposte HTTP 5xx gestite dal gateway portano anche un x-request-id diagnostico distinto. Un id sicuro fornito dal client viene restituito anche nelle altre risposte. Gli errori generati da un proxy prima del gateway non sono coperti.
  • I rifiuti a livello di gateway che avvengono prima dell'handler, come la backpressure del ledger o il sovraccarico, possono tornare nella forma di errore OpenAI.
# failures from the Messages handlers are Anthropic-shaped: auth and
# data-protection refusals included
{
  "type": "error",
  "error": {
    "type": "rate_limit_error",
    "message": "rate limit exceeded"
  },
  "request_id": "req_9f2e…"
}

Un array mcp_servers non vuoto viene rifiutato con 400 invalid_request_error invece di essere inoltrato. Un modello che chiama da sé un server MCP esterno starebbe fuori dal gate Sluis. Registra invece il server nella Console e chiama i suoi strumenti tramite il gateway MCP, dove ogni chiamata di strumento eseguita viene ispezionata, instradata, sigillata e misurata.

Matrice di compatibilità

Ciò che gli ingressi nativi coprono oggi, endpoint per endpoint. Questa tabella è la dichiarazione: quello che qui non risulta supportato è in roadmap, rifiutato di proposito o appartiene a un'altra superficie di prodotto, mai sottinteso.

AnthropicStatoNote
POST /v1/messages✓ nativoIn buffer e in streaming, strumenti, immagini, blocchi documento, round-trip del thinking e marcatori di cache dei prompt.
POST /v1/messages/count_tokens✓ stima localeRisposta locale. Non viene inviato nulla.
GET /v1/models · /v1/models/{id}✓ nativoForma nativa di list e get dal catalogo in-process. Negoziata dall'header sul percorso radice, incondizionata sotto /anthropic.
HEAD /api/hello✓La sonda di riscaldamento di Claude Code, solo HEAD.
Message Batches✓ opt-inDisponibili quando la tua installazione le abilita: create, list, get, results e cancel, per i modelli che si risolvono su Anthropic. Altrimenti 404. Per gli altri provider usa /v1/batches in formato OpenAI.
Files✗ roadmapL'API Files non è collegata. I blocchi documento inline e file_data coprono il percorso comune.
mcp_servers✗ rifiutatoUn array non vuoto viene rifiutato con 400 invece di essere inoltrato. Registra il server e usa il gateway MCP di Sluis.
Skills · Agents · Admin✗ fuori perimetroSkills, agenti gestiti e le API di amministrazione, uso e costi sono un'altra superficie di prodotto, non compatibilità di inferenza.

Instradamento tra protocolli

I campi specifici del produttore sopravvivono finché la richiesta atterra su un provider che parla lo stesso protocollo. Una richiesta Anthropic servita da un provider della famiglia Anthropic conserva i blocchi thinking, i marcatori di cache, i flag beta e la stop_sequence corrispondente.

Instradati tra protocolli diversi, quei campi cadono al dispatch e non vengono mai rifiutati all'ingresso. La riga di audit registra sia il formato di trasporto sia il provider risolto, così ogni perdita è attribuibile.

I valori opachi non vengono mai riscritti: le firme del thinking e i payload redacted_thinking sono inoltrati alla lettera o non del tutto. È anche il motivo per cui un blocco thinking parcheggiato che la scansione di protezione dei dati segnala viene scartato invece che mascherato: un blocco riscritto porterebbe una firma non valida.