Dokumentacja

Referencja API

Uwierzytelnianie, powierzchnia endpointów zgodna z OpenAI, streaming, reasoning i taksonomia błędów.

Uwierzytelnianie

Każde żądanie do /v1/* uwierzytelnia się wirtualnym kluczem w nagłówku Authorization: Bearer. Klucze tworzysz w Konsoli; sekret jest pokazywany tylko raz, a przechowywany jest wyłącznie jego hash. Klucz niesie własne limity zapytań, budżet, tagi, opcjonalną listę dozwolonych modeli (pusta = dowolny model) oraz rzadkie option_overrides odbiegające od polityki organizacji (tryb ochrony danych, model NER, tryb skanowania injection).

Żądanie, którego model nie znajduje się na niepustej liście dozwolonych modeli klucza, zostaje odrzucone zapieczętowanym 403 permission_error zanim cokolwiek zostanie wysłane; sama odmowa trafia do łańcucha audytu.

Utworzenie klucza produkcyjnego wymaga zweryfikowanego adresu e-mail.

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

Endpointy

Sluis udostępnia poniższą powierzchnię zgodną z OpenAI. Endpointy bez dedykowanej obsługi są przekazywane dosłownie do wyznaczonego dostawcy, wraz ze streamingiem, więc zgodne z OpenAI usługi nadrzędne zachowują pełną wierność.

EndpointPrzeznaczenie
POST /v1/chat/completionsChat completions, główna powierzchnia: routing, ochrona danych, buforowanie, streaming.
POST /v1/completionsStarsze text completions.
POST /v1/embeddingsEmbeddingi; zasilają też cache semantyczny.
POST /v1/moderationsKlasyfikacja moderacji.
POST /v1/responsesAPI OpenAI Responses.
POST /v1/ocrOCR dokumentów (Mistral, lub w pełni lokalnie z modelem sluis/ocr) · rozliczane za stronę. Z włączoną polityką dlp_documents dokumenty inline są anonimizowane przed wysyłką.
POST /v1/documents/anonymizeAnonimizacja dokumentów · PII stają się «MERGE_TAG»ami, obrazy są rozmywane · rozliczane za stronę/obraz.
POST /v1/documents/anonymize/jobsAsynchroniczne zadania anonimizacji · kolejkuj duże dokumenty, sprawdzaj status i pobieraj wynik przez podpisany URL o ograniczonej ważności, bez klucza API.
GET /v1/modelsModele, które Twoja polityka i poświadczenia faktycznie osiągają, nic hipotetycznego.
GET /v1/models/{id}Metadane pojedynczego modelu.
POST /v1/audio/*Transkrypcja, tłumaczenie, mowa · przekazywane do wyznaczonego dostawcy.
POST /v1/images/*Generowanie i edycja obrazów · przekazywane.
POST /v1/video/generationsGenerowanie wideo · przekazywane.
/v1/filesOperacje na plikach · przekazywane.
POST /v1/messagesNatywne wejście Anthropic Messages · skieruj dowolne narzędzie z SDK Anthropic na Sluis; dowolny podłączony model.
POST /v1/messages/count_tokensLokalne oszacowanie tokenów dla zarządzania kontekstem SDK Anthropic; nic nie jest wysyłane.
POST /v1beta/models/{model}:generateContentNatywne wejście Google Gemini · skieruj SDK Gemini na Sluis (:streamGenerateContent strumieniuje).
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" }] }'
# 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" } }'
# 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 }'

Dokumenty na wejściu

Dołącz PDF, dokument Word, obraz lub plik tekstowy do żądania czatu jako część treści "type": "file" z URL-em file_data w base64. Zaakceptuje to każdy wybrany model: dostawcy, którzy natywnie rozumieją części plikowe, otrzymują je bez zmian, a dla wszystkich pozostałych brama konwertuje dokument przed wysyłką. Referencje file_id po stronie dostawcy nie są rozwiązywane; osadź bajty jako file_data.

Modele z widzeniem otrzymują każdą stronę PDF wyrenderowaną jako część image_url (budżet 48 stron na żądanie, wspólny dla wszystkich załączonych dokumentów); modele bez wejścia obrazowego otrzymują możliwy do wyodrębnienia tekst dokumentu wstawiony jako tekst promptu, który skan ochrony danych obejmuje potem jak każdy inny tekst. Dłuższe lub cięższe dokumenty należą do /v1/ocr. Przy włączonej polityce dlp_documents dokument jest anonimizowany lub odrzucany, zanim cokolwiek opuści bramę. Gdy jest wyłączona, a tryb DLP organizacji jest ochronny (tokenize, mask lub block), dokumenty, które podróżowałyby jako niemożliwe do zbadania obrazy, są odrzucane; przy allow_log przechodzą z jawnym znacznikiem braku skanowania w dzienniku audytu.

# 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

Ustaw stream: true, a odpowiedź nadchodzi jako server-sent events: każda ramka to delta chat.completion.chunk, a strumień kończy się data: [DONE]. Strumienie nigdy nie są buforowane w bramie: przepływają przez nią rozgałęzieniem (tee), a zapieczętowanie audytu i pomiar następują nawet wtedy, gdy klient rozłączy się wcześniej.

Poproś o stream_options.include_usage a ostatnia ramka niesie dokładne zużycie tokenów, te same liczby, które brama mierzy i rozlicza.

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="")

Rozumowanie

Przekaż parametr OpenAI reasoning_effort (minimal | low | medium | high) na dowolnym modelu zdolnym do myślenia. Sluis tłumaczy go zależnie od dostawcy (poziom myślenia Gemini, adaptacyjny wysiłek myślowy Claude) i pomija go tam, gdzie model by go odrzucił, więc jeden parametr działa w całym katalogu.

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
)

Kody błędów

Błędy używają koperty błędów OpenAI; wartość error.type odzwierciedla status HTTP, więc obsługa błędów w Twoim SDK działa bez zmian.

KodKiedy
400 invalid_request_errorNieprawidłowy body żądania lub parametry.
400 invalid_request_errorIdentyfikator modelu bez prefiksu dostawcy. Każdy wywoływalny identyfikator to provider/model, np. mistral/mistral-large-latest; treść odpowiedzi brzmi: model must be provider-prefixed.
400 invalid_request_errorŻądanie niesie usunięty nagłówek x-sluis-dlp. Nadpisania per żądanie zastąpiono option overrides per klucz; skonfiguruj je w Konsola → API keys.
401 authentication_errorBrakujący lub nieznany klucz API.
402 insufficient_quotaBrak aktywnego planu lub osiągnięty budżet. Aktywuj plan albo podnieś budżet; żądanie nigdy nie dociera do dostawcy.
403 permission_errorKlucz nie ma uprawnień, na przykład model nie jest na jego liście dozwolonych.
422 invalid_request_errorOdrzucone przed wysyłką, na przykład ochrona danych w trybie block dopasowała żądanie.
422 document_too_large_to_scanStrona dokumentu przekracza limit pikseli renderowania nawet przy minimalnej rozdzielczości skanowania. Strony wielkoformatowe (rysunki A0/A1) są renderowane z automatycznym pomniejszeniem; dedykowany kod pozwala klientowi pomniejszyć stronę i wysłać ją ponownie.
429 rate_limit_errorOsiągnięty limit zapytań. Egzekwowane na bramie; żądanie nigdy nie dociera do dostawcy.
451 permission_errorZablokowane przez politykę rezydencji: żadna dozwolona jurysdykcja nie obsłuży żądania. Body zawiera powód.
5xx api_errorAwaria dostawcy nadrzędnego po ponowieniach; bezpiecznik kieruje ruch z pominięciem niesprawnych dostawców.
{
  "error": {
    "message": "model must be provider-prefixed, e.g. mistral/mistral-large-latest",
    "type": "invalid_request_error",
    "param": null,
    "code": "invalid_request"
  }
}