DOCUMENTAZIONE API

Integrate Sealarca nella vostra applicazione.

Autenticatevi con la vostra chiave API Sealarca, scoprite i modelli disponibili, inviate richieste Responses, Chat Completions o Claude Messages e collegate il servizio al vostro software.

Iniziare Vedere la guida rapida

Gli esempi usano un ID modello restituito da GET /v1/models. Nessun modello è fissato in questa documentazione.

Prima chiamata

cURL · Responses

curl https://api.sealarca.ch/v1/responses \
  -H "Authorization: Bearer $SEALARCA_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"model\":\"$SEALARCA_MODEL_ID\",\"input\":\"Riassumi questo testo riservato in tre punti.\",\"max_output_tokens\":256}"

Struttura della risposta

JSON · Risposta abbreviata

{"id":"<response-id>","object":"response","status":"completed","model":"<model-id>","output":[{"type":"message","role":"assistant","content":[{"type":"output_text","text":"<generated text>"}]}]}

INIZIATE QUI

Dall’account alla prima risposta

Seguite questo ordine: accesso, scoperta dei modelli e poi una richiesta lato server.

01
Creare un account
Create il vostro account Sealarca per accedere al dashboard.
02
Aggiungere crediti
Ricaricate il saldo prepagato in CHF prima di chiamare l’API.
03
Creare una chiave API
Create una chiave API Sealarca e conservatela sul server.
04
Elencare i modelli
Chiamate GET /v1/models e scegliete un ID visibile alla vostra chiave.
05
Effettuare la prima chiamata
Usate l’ID restituito con Responses, Chat Completions o Claude Messages.

Autenticare ogni richiesta

L’API pubblica accetta una chiave API Sealarca come Bearer token oppure, per i client Claude, tramite `x-api-key` sulla route Messages.

Header di autenticazione

Usate `Authorization: Bearer ...` per Responses e Chat Completions. I client Claude possono usare `x-api-key: ...` con `anthropic-version` su `/v1/messages`.

Authorization: Bearer $SEALARCA_API_KEYx-api-key: $SEALARCA_API_KEYanthropic-version: 2023-06-01

Conservare la chiave sul server

Non esponetela mai in un’applicazione web pubblica, un’app mobile distribuita, un repository o una variabile NEXT_PUBLIC_*. Desk è un client locale distinto: l’utente fornisce la chiave, conservata solo per la sessione della scheda.

Prima richiesta

Sono sufficienti una chiave lato server, la base URL e un corpo JSON. L'esempio canonico usa Responses.

Base URL: https://api.sealarca.ch/v1
Token Bearer: Authorization: Bearer $SEALARCA_API_KEY
Content-Type: application/json

Solo chiave lato server. Non inserite mai la chiave in un’applicazione web pubblica, in un bundle del browser, in una variabile `NEXT_PUBLIC_*`, in un repository Git o in un’app mobile distribuita. Un’applicazione web pubblica deve chiamare il vostro backend, che chiama poi Sealarca.

1. Configura e chiama Responsesbash

export SEALARCA_API_KEY="YOUR_SEALARCA_API_KEY"
export SEALARCA_MODEL_ID="MODEL_ID_FROM_V1_MODELS"

curl https://api.sealarca.ch/v1/responses \
  -H "Authorization: Bearer $SEALARCA_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"model\":\"$SEALARCA_MODEL_ID\",\"input\":\"Riassumi questo testo riservato in tre punti.\",\"max_output_tokens\":256}"

Risposta JSON minima prevista

Scegli un altro modello

2. Leggi la rispostajson

{"id":"<response-id>","object":"response","status":"completed","model":"<model-id>","output":[{"type":"message","role":"assistant","content":[{"type":"output_text","text":"<generated text>"}]}]}

Scopri i modelli

Interroga il catalogo con la stessa chiave e usa l'`id` restituito esattamente in `modello`.

GET /v1/modelsbash

curl https://api.sealarca.ch/v1/models \
  -H "Authorization: Bearer $SEALARCA_API_KEY"

Risposta abbreviatajson

{"data":[{"id":"<model-id>","object":"model"}]}

La risposta è limitata dalla chiave. Usate un id restituito esattamente come valore di model; non copiate un nome modello da questa pagina.

Confronta modelli, funzionalità e prezzi

Contratto degli endpoint pubblici

Questi stati descrivono il contratto pubblicato. Le route non disponibili non sono pubblicate intenzionalmente.

Endpoint pubblici Sealarca
Metodo	Endpoint	Stato	Streaming	Uso e limiti
GET	Models `/models`	Confermato	—	Scopri gli ID dei modelli visibili alla chiave. Risposta limitata alla chiave; l’esempio seguente è abbreviato.
POST	Responses `/responses`	Confermato	SSE	Formato consigliato per le nuove integrazioni OpenAI SDK. Il JSON viene restituito per impostazione predefinita; impostare `stream: true` per richiedere SSE.
POST	Chat Completions `/chat/completions`	Confermato	SSE	Formato Messages per i client esistenti. Il JSON viene restituito per impostazione predefinita; impostare `stream: true` per richiedere SSE.
POST	Claude Messages `/messages`	Confermato	SSE	Formato Messages per client compatibili con Claude e integrazioni che usano la Messages API. Usate l’identificativo esatto restituito da `/models`. Le capacità disponibili dipendono dal modello pubblicato.
POST	Embeddings `/embeddings`	Confermato	—	Creare rappresentazioni vettoriali per ricerca e similarità. Contratto tecnico dell’endpoint, subordinato a un modello Embedding restituito dal catalogo. Nessun modello di embedding è disponibile nel catalogo pubblico attualmente documentato. Nessuno streaming.
GET	Prova Vault `/vault/proofs/{receiptId}`	Confermato	—	Consultare lo stato e i controlli associati a una ricevuta Vault. Autenticazione richiesta; 202 per pending, 200 per il verdetto, 404 se assente o non autorizzato, 410 se scaduto.
GET	Bundle di prova firmato `/vault/proofs/{receiptId}/bundle`	Confermato	—	Scaricare il JWS firmato di una prova Vault terminale. Stesso isolamento utente; 202 se pending, 200 quando firmato, 404 o 410 secondo il caso, 503 se la firma non è disponibile.
GET	Chiavi di firma Vault `/vault/proofs/signing-keys`	Confermato	—	Ottenere il JWKS pubblico delle chiavi attive e ritirate. Pubblico e senza autenticazione; conservate l’impronta di riferimento prevista dal contratto.
GET	Attestazione Vault `/vault/attestation?nonce=…`	Confermato	—	Richiedere un’attestazione recente legata a un nonce del client. Il nonce deve contenere esattamente 64 caratteri esadecimali minuscoli.

GET

Models

/models

Confermato

Scopri gli ID dei modelli visibili alla chiave.

Streaming: —
Nota: Risposta limitata alla chiave; l’esempio seguente è abbreviato.

POST

Responses

/responses

Confermato

Formato consigliato per le nuove integrazioni OpenAI SDK.

Streaming: SSE
Nota: Il JSON viene restituito per impostazione predefinita; impostare `stream: true` per richiedere SSE.

POST

Chat Completions

/chat/completions

Confermato

Formato Messages per i client esistenti.

Streaming: SSE
Nota: Il JSON viene restituito per impostazione predefinita; impostare `stream: true` per richiedere SSE.

POST

Claude Messages

/messages

Confermato

Formato Messages per client compatibili con Claude e integrazioni che usano la Messages API.

Streaming: SSE
Nota: Usate l’identificativo esatto restituito da `/models`. Le capacità disponibili dipendono dal modello pubblicato.

POST

Embeddings

/embeddings

Confermato

Creare rappresentazioni vettoriali per ricerca e similarità.

Streaming: —
Nota: Contratto tecnico dell’endpoint, subordinato a un modello Embedding restituito dal catalogo. Nessun modello di embedding è disponibile nel catalogo pubblico attualmente documentato. Nessuno streaming.

GET

Prova Vault

/vault/proofs/{receiptId}

Confermato

Consultare lo stato e i controlli associati a una ricevuta Vault.

Streaming: —
Nota: Autenticazione richiesta; 202 per pending, 200 per il verdetto, 404 se assente o non autorizzato, 410 se scaduto.

GET

Bundle di prova firmato

/vault/proofs/{receiptId}/bundle

Confermato

Scaricare il JWS firmato di una prova Vault terminale.

Streaming: —
Nota: Stesso isolamento utente; 202 se pending, 200 quando firmato, 404 o 410 secondo il caso, 503 se la firma non è disponibile.

GET

Chiavi di firma Vault

/vault/proofs/signing-keys

Confermato

Ottenere il JWKS pubblico delle chiavi attive e ritirate.

Streaming: —
Nota: Pubblico e senza autenticazione; conservate l’impronta di riferimento prevista dal contratto.

GET

Attestazione Vault

/vault/attestation?nonce=…

Confermato

Richiedere un’attestazione recente legata a un nonce del client.

Streaming: —
Nota: Il nonce deve contenere esattamente 64 caratteri esadecimali minuscoli.

Esempi per linguaggio

Quattro esempi: tre usano Responses e il quarto Messages. Scegliete un modello autorizzato per l’endpoint interessato.

cURLbash

curl https://api.sealarca.ch/v1/responses \
  -H "Authorization: Bearer $SEALARCA_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"model\":\"$SEALARCA_MODEL_ID\",\"input\":\"Analizza questo documento e restituisci tre rischi.\"}"

Trasmettere una risposta

Responses, Chat Completions e Claude Messages possono richiedere eventi inviati dal server con stream: true.

Attivare lo streaming

Impostate stream su true e usate curl -N o un client HTTP equivalente. La risposta usa text/event-stream.

Leggere il flusso

Elaborate i record data: separati da righe vuote. I payload e la terminazione dipendono dal contratto della route.

POST /v1/responses · stream=truebash

curl -N https://api.sealarca.ch/v1/responses \
  -H "Authorization: Bearer $SEALARCA_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"model\":\"$SEALARCA_MODEL_ID\",\"input\":\"Riassumi questo file.\",\"stream\":true}"

POST /v1/messages · stream=truebash

curl -N https://api.sealarca.ch/v1/messages \
  -H "x-api-key: $SEALARCA_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d "{\"model\":\"$SEALARCA_MODEL_ID\",\"max_tokens\":256,\"stream\":true,\"messages\":[{\"role\":\"user\",\"content\":\"Riassumi questo file.\"}]}"

Framing illustrativotext

Content-Type: text/event-stream

data: <JSON event>

GLM 5.3 Flash — Shield

Una rotta confidenziale multimodale per testo, immagini, strumenti e output strutturati, con streaming.

Shield associa un ambiente di esecuzione protetto a una ricevuta firmata da Sealarca. Questa ricevuta documenta lo scambio osservato dal nostro gateway.
Gli hash riguardano i corpi JSON e i flussi SSE tra il gateway Sealarca e il proxy di cifratura, prima delle conversioni della risposta. Non identificano i byte HTTP originali del client. I digest dei manifest sono osservazioni dell’ambiente senza un legame hardware indipendente con la risposta.
Inviare la conversazione in ogni richiesta. store=true, background, previous_response_id, conversation e cache_salt vengono rifiutati. Gli strumenti eseguiti sul server non sono disponibili.
reasoning_effort accetta low, high o max. Il valore predefinito è low; il ragionamento non può essere disattivato. I token di ragionamento sono fatturati come token di output, anche quando il flusso viene interrotto prima che sia visualizzata una risposta.
Contesto del modello: fino a 1 048 576 token. Limite di output configurato da Sealarca: 131 072 token per richiesta. Le quote e i limiti effettivi della rotta possono ridurre questo limite. Responses viene convertito in Chat Completions. Rotta in anteprima.
Ricevute firmate e metadati sono conservati per 90 giorni. Ricevute e log non contengono prompt, risposte o immagini. La cache condivisa è disattivata.

POST /v1/responsesbash

curl https://api.sealarca.ch/v1/responses \
  -H "Authorization: Bearer $SEALARCA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "glm.5.3-flash-shield",
  "input": "Reply with OK.",
  "reasoning": {
    "effort": "low"
  },
  "store": false,
  "max_output_tokens": 256
}'

POST /v1/chat/completionsbash

curl https://api.sealarca.ch/v1/chat/completions \
  -H "Authorization: Bearer $SEALARCA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "glm.5.3-flash-shield",
  "messages": [
    {
      "role": "user",
      "content": "Reply with OK."
    }
  ],
  "reasoning_effort": "low",
  "max_tokens": 256,
  "stream": true
}'

POST /v1/messagesbash

curl https://api.sealarca.ch/v1/messages \
  -H "Authorization: Bearer $SEALARCA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "glm.5.3-flash-shield",
  "max_tokens": 256,
  "messages": [
    {
      "role": "user",
      "content": "Reply with OK."
    }
  ]
}'

Leggere X-Sealarca-Receipt-ID e X-Sealarca-Receipt-URL dalla risposta. La ricevuta è disponibile dopo finalizzazione e consegna; un 404 può essere temporaneo. complete, interrupted e failed descrivono lo scambio osservato.

Shield receiptbash

# X-Sealarca-Receipt-ID / X-Sealarca-Receipt-URL / X-Sealarca-Proof-Profile
curl https://api.sealarca.ch/v1/vault/proofs/$RECEIPT_ID/bundle \
  -H "Authorization: Bearer $SEALARCA_API_KEY"
# JWKS: https://api.sealarca.ch/v1/vault/proofs/signing-keys

Consultare la prova di un’inferenza Vault

Ogni inferenza Vault accettata fornisce una ricevuta che collega la risposta alla route e alla sessione verificate da Sealarca.

Controllo prima di ogni esecuzione

Prima di qualsiasi inoltro per l’esecuzione, Sealarca controlla che l’ambiente di fiducia e il canale associati alla route soddisfino i requisiti Vault. Se questo controllo fallisce o non è disponibile, l’inferenza viene rifiutata senza fallback verso una route non protetta. La ricevuta Vault collega quindi la risposta alla route e alla sessione verificate.

Inferenza e header della provabash

curl -i https://api.sealarca.ch/v1/responses \
  -H "Authorization: Bearer $SEALARCA_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"model\":\"$SEALARCA_MODEL_ID\",\"input\":\"Riassumi questo file.\"}"

Tre header da conservare

Lo stato iniziale è pending. Conservate l’identificatore della ricevuta e usate l’URL fornito per consultare il verdetto finale.

X-Sealarca-Vault-Receipt-ID
X-Sealarca-Vault-Proof-Status
X-Sealarca-Vault-Proof-URL

GET /v1/vault/proofs/{receiptId}bash

export SEALARCA_VAULT_PROOF_URL="<X-Sealarca-Vault-Proof-URL>"

curl "$SEALARCA_VAULT_PROOF_URL" \
  -H "Authorization: Bearer $SEALARCA_API_KEY"

sealarca-vault-proof/1json

{
  "schema": "sealarca-vault-proof/1",
  "receipt_id": "<receipt-id>",
  "status": "verified",
  "model": "<model-id>",
  "created_at": "<ISO-8601>",
  "updated_at": "<ISO-8601>",
  "verified_at": "<ISO-8601>",
  "expires_at": "<ISO-8601>",
  "admission": {
    "status": "verified",
    "checked_at": "<ISO-8601>",
    "attested_at": "<ISO-8601>",
    "expires_at": "<ISO-8601>",
    "evidence_digest": "sha256:<hex>",
    "keyset_digest": "sha256:<hex>"
  },
  "checks": [
    { "id": "attestation", "status": "verified" },
    { "id": "receipt", "status": "verified" }
  ],
  "hashes": {
    "request": "sha256:<hex>",
    "response": "sha256:<hex>",
    "request_received": "sha256:<hex>",
    "request_forwarded": "sha256:<hex>",
    "response_returned": "sha256:<hex>",
    "keyset": "sha256:<hex>",
    "evidence": "sha256:<hex>",
    "runtime": "sha256:<hex>"
  }
}

202 · pending

La verifica è ancora in corso. Riprovate dopo un breve intervallo.

200 · verified

L’ammissione, la ricevuta e la sessione Vault referenziata hanno soddisfatto i controlli richiesti.

200 · failed

La prova non è stata verificata. Non considerate il risultato come verificato.

404 / 410

404 indica che la prova è assente o inaccessibile; 410 indica che è scaduta.

503 · VAULT_VERIFICATION_UNAVAILABLE

La verifica Vault non è disponibile. L’inferenza viene rifiutata senza passare a un’esecuzione non protetta.

L’interfaccia standard espone il risultato della verifica effettuata da Sealarca. Non è un’esportazione completa degli artefatti grezzi per una verifica crittografica indipendente; l’accesso resta soggetto alla procedura contrattuale applicabile.

Qualsiasi chiave attiva dello stesso utente può consultare la cronologia. Non inserite mai una chiave API nell’URL.

In streaming, la ricevuta viene annunciata con la risposta; il verdetto finale diventa disponibile dopo la fine del flusso.

Le prove sono conservate per 90 giorni e non contengono prompt, risposta o chiave API.

Controllo avanzato dell’ambiente Vault

Fornite un nonce univoco di 64 caratteri esadecimali minuscoli per richiedere un’attestazione recente e autenticata.

GET /v1/vault/attestation?nonce=…bash

export SEALARCA_VAULT_NONCE="<64-lowercase-hex-characters>"

curl "https://api.sealarca.ch/v1/vault/attestation?nonce=$SEALARCA_VAULT_NONCE" \
  -H "Authorization: Bearer $SEALARCA_API_KEY"

Schema sealarca-vault-attestation/1

La risposta standard contiene stato, nonce, date di verifica e scadenza, controlli normalizzati, digest di evidence, runtime e keyset e le impronte utili delle chiavi dell’ambiente. Gli artefatti completi restano riservati all’esportazione di audit autorizzata contrattualmente.

sealarca-vault-attestation/1json

{
  "schema": "sealarca-vault-attestation/1",
  "status": "verified",
  "nonce": "<64-lowercase-hex-characters>",
  "verified_at": "<ISO-8601>",
  "expires_at": "<ISO-8601>",
  "checks": [{ "id": "<check-id>", "status": "verified" }],
  "measurements": {
    "evidence": "sha256:<hex>",
    "runtime": "sha256:<hex>",
    "keyset": "sha256:<hex>"
  },
  "key_fingerprints": {
    "receipt_signing": ["sha256:<hex>"],
    "tls": ["sha256:<hex>"],
    "e2ee": ["sha256:<hex>"]
  }
}

Definizione degli hash

Ogni valore è sha256: seguito dal digest esadecimale dei byte osservati nella catena Vault. request_received copre il corpo ricevuto dall’ambiente, request_forwarded il corpo eventualmente trasformato prima del modello e response_returned i byte di risposta osservati, compresi i flussi. Dopo normalizzazione o trasformazione, questi byte possono differire dai byte HTTP originali del client.

Bundle firmato e verifica offline

Una prova terminale verified o failed è disponibile come sealarca-vault-proof-bundle/1. Il payload è canonizzato secondo RFC 8785 e poi firmato in formato JWS con Ed25519. Il JWKS pubblico conserva le chiavi attive e ritirate per verificare un bundle archiviato dopo 90 giorni.

La firma garantisce l’integrità e l’origine Sealarca del bundle. Non estende la validità temporale dell’attestazione e, da sola, non costituisce una verifica hardware indipendente.

GET /v1/vault/proofs/{receiptId}/bundle · sealarca-vault-proof-bundle/1bash

curl -f "$SEALARCA_VAULT_PROOF_URL/bundle" \
  -H "Authorization: Bearer $SEALARCA_API_KEY" \
  -o sealarca-vault-proof.jws.json

curl -f "https://api.sealarca.ch/v1/vault/proofs/signing-keys" \
  -o sealarca-vault-jwks.json

Verifica Ed25519 offline con Node.jsjavascript

import { createHash, createPublicKey, verify } from "node:crypto";
import { readFileSync } from "node:fs";

const bundle = JSON.parse(readFileSync("sealarca-vault-proof.jws.json", "utf8"));
const jwks = JSON.parse(readFileSync("sealarca-vault-jwks.json", "utf8"));
const header = JSON.parse(Buffer.from(bundle.protected, "base64url"));
if (header.alg !== "EdDSA" || header.typ !== "sealarca-vault-proof+jws") throw new Error("Unexpected JWS algorithm");
const jwk = jwks.keys.find((key) => key.kid === header.kid);
if (!jwk || jwk.kty !== "OKP" || jwk.crv !== "Ed25519") throw new Error("Signing key not found or unsupported");
// Obtain this fingerprint independently from your current Sealarca contract/guide.
// Never trust a fingerprint received alongside an untrusted bundle.
const expected = process.env.SEALARCA_VAULT_JWK_SHA256;
if (!expected) throw new Error("Trusted JWK fingerprint required");
const thumbprint = createHash("sha256")
  .update(JSON.stringify({ crv: jwk.crv, kty: jwk.kty, x: jwk.x }))
  .digest("hex");
if ("sha256:" + thumbprint !== expected) throw new Error("Unexpected signing key");
const valid = verify(
  null,
  Buffer.from(bundle.protected + "." + bundle.payload),
  createPublicKey({ key: jwk, format: "jwk" }),
  Buffer.from(bundle.signature, "base64url"),
);
if (!valid) throw new Error("Invalid Vault proof signature");
console.log(JSON.parse(Buffer.from(bundle.payload, "base64url")));

503 · VAULT_PROOF_SIGNING_UNAVAILABLE

Riferimento degli endpoint

Campi minimi, formato di output e comportamento dello streaming per le route confermate.

GET

/models

Confermato

Richiesta

Nessun corpo della richiesta. Token Bearer obbligatorio.

Risposta

Elenco limitato dalla chiave, contenente gli ID dei modelli visibili a quella chiave.

POST

/responses

Confermato

Obbligatorio

model
input

Comune

max_output_tokens
stream

Output

Oggetto `response`; gli SDK espongono `output_text`.

Obbligatori: `model` e `input`. Campi comuni documentati: `max_output_tokens` (intero positivo) e `stream` (booleano). Gli altri campi dipendono dal modello e non fanno parte di questo contratto minimo.

POST /v1/responsesbash

export SEALARCA_API_KEY="YOUR_SEALARCA_API_KEY"
export SEALARCA_MODEL_ID="MODEL_ID_FROM_V1_MODELS"

curl https://api.sealarca.ch/v1/responses \
  -H "Authorization: Bearer $SEALARCA_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"model\":\"$SEALARCA_MODEL_ID\",\"input\":\"Riassumi questo testo riservato in tre punti.\",\"max_output_tokens\":256}"

POST

/chat/completions

Confermato

Obbligatorio

model
messages

Comune

max_tokens
stream

Output

choices[0].message.content

Obbligatori: `model` e `messages`. Campi comuni documentati: `max_tokens` (intero positivo) e `stream` (booleano). Gli altri campi dipendono dal modello e non fanno parte di questo contratto minimo.

POST /v1/chat/completionsbash

curl https://api.sealarca.ch/v1/chat/completions \
  -H "Authorization: Bearer $SEALARCA_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"model\":\"$SEALARCA_MODEL_ID\",\"messages\":[{\"role\":\"user\",\"content\":\"Riassumi questo file.\"}],\"max_tokens\":256}"

POST

/messages

Confermato

Obbligatorio

model
messages

Comune

max_tokens
stream

Output

content

Obbligatori: `model`, `max_tokens` e `messages`. `stream` attiva gli eventi SSE. Gli altri campi dipendono dal contratto pubblicato.

POST /v1/messagesbash

curl https://api.sealarca.ch/v1/messages \
  -H "x-api-key: $SEALARCA_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d "{\"model\":\"$SEALARCA_MODEL_ID\",\"max_tokens\":256,\"messages\":[{\"role\":\"user\",\"content\":\"Riassumi questo file.\"}]}"

Errori e regole per i nuovi tentativi

Non riprovare alla cieca. Correggi gli errori 4xx deterministici e applica un backoff limitato agli errori temporanei.

Codici di errore e regole per i nuovi tentativi
HTTP	Causa	Azione consigliata	Nuovo tentativo	Retry-After
400	JSON non valido, campo mancante o parametro non supportato.	Correggi la richiesta prima di riprovare.	No, senza modifiche	—
401	Token Bearer mancante, non valido o revocato.	Controlla e sostituisci la chiave.	No, non senza una nuova chiave	—
402	Saldo di crediti insufficiente.	Ricarica i crediti nella dashboard.	Dopo la ricarica	—
403	La chiave API non è autorizzata a usare la route o il modello richiesto.	Controllare i diritti e usare un ID modello restituito per questa chiave.	No, senza modificare i diritti o la richiesta.	—
404	Route pubblica o ID modello sconosciuto; l’indisponibilità del modello può essere segnalata anche come 503.	Leggere `/models`, verificare il percorso e correggere il modello o la route prima di riprovare.	No, senza modifiche	—
408	Il gateway ha raggiunto il timeout prima del completamento della richiesta.	Ridurre la dimensione dell’input o dell’output, quindi riprovare con un backoff limitato.	Sì, con limitazioni	Quando presente
409	La richiesta è temporaneamente non disponibile.	Attendete brevemente, poi riprovate con un backoff limitato.	Sì, limitato	Quando presente
422	Un parametro della richiesta non è valido per il modello selezionato.	Controllate i campi documentati e correggete la richiesta.	No, senza modifiche	—
429	Raggiunto il limite di frequenza o la capacità temporanea.	Riduci la concorrenza e applica un backoff.	Sì	Rispetta quando presente
500	Errore interno del servizio Sealarca.	Riprovare con un backoff limitato e conservare l’ID della richiesta o dell’errore.	Sì, con limitazioni	—
502	Risposta non valida della route.	Riprovare con un backoff limitato.	Sì	Quando presente
503	Modello selezionato temporaneamente non disponibile.	Riprovare con un limite e usare un altro modello se necessario.	Sì	Quando presente
504	Il gateway ha raggiunto il timeout prima del completamento della richiesta.	Ridurre la dimensione dell’input o dell’output, quindi riprovare con un backoff limitato.	Sì, con limitazioni	Quando presente

400

Causa: JSON non valido, campo mancante o parametro non supportato.
Azione: Correggi la richiesta prima di riprovare.
Nuovo tentativo: No, senza modifiche
Retry-After: —

401

Causa: Token Bearer mancante, non valido o revocato.
Azione: Controlla e sostituisci la chiave.
Nuovo tentativo: No, non senza una nuova chiave
Retry-After: —

402

Causa: Saldo di crediti insufficiente.
Azione: Ricarica i crediti nella dashboard.
Nuovo tentativo: Dopo la ricarica
Retry-After: —

403

Causa: La chiave API non è autorizzata a usare la route o il modello richiesto.
Azione: Controllare i diritti e usare un ID modello restituito per questa chiave.
Nuovo tentativo: No, senza modificare i diritti o la richiesta.
Retry-After: —

404

Causa: Route pubblica o ID modello sconosciuto; l’indisponibilità del modello può essere segnalata anche come 503.
Azione: Leggere `/models`, verificare il percorso e correggere il modello o la route prima di riprovare.
Nuovo tentativo: No, senza modifiche
Retry-After: —

408

Causa: Il gateway ha raggiunto il timeout prima del completamento della richiesta.
Azione: Ridurre la dimensione dell’input o dell’output, quindi riprovare con un backoff limitato.
Nuovo tentativo: Sì, con limitazioni
Retry-After: Quando presente

409

Causa: La richiesta è temporaneamente non disponibile.
Azione: Attendete brevemente, poi riprovate con un backoff limitato.
Nuovo tentativo: Sì, limitato
Retry-After: Quando presente

422

Causa: Un parametro della richiesta non è valido per il modello selezionato.
Azione: Controllate i campi documentati e correggete la richiesta.
Nuovo tentativo: No, senza modifiche
Retry-After: —

429

Causa: Raggiunto il limite di frequenza o la capacità temporanea.
Azione: Riduci la concorrenza e applica un backoff.
Nuovo tentativo: Sì
Retry-After: Rispetta quando presente

500

Causa: Errore interno del servizio Sealarca.
Azione: Riprovare con un backoff limitato e conservare l’ID della richiesta o dell’errore.
Nuovo tentativo: Sì, con limitazioni
Retry-After: —

502

Causa: Risposta non valida della route.
Azione: Riprovare con un backoff limitato.
Nuovo tentativo: Sì
Retry-After: Quando presente

503

Causa: Modello selezionato temporaneamente non disponibile.
Azione: Riprovare con un limite e usare un altro modello se necessario.
Nuovo tentativo: Sì
Retry-After: Quando presente

504

Causa: Il gateway ha raggiunto il timeout prima del completamento della richiesta.
Azione: Ridurre la dimensione dell’input o dell’output, quindi riprovare con un backoff limitato.
Nuovo tentativo: Sì, con limitazioni
Retry-After: Quando presente

ID richiesta. Ogni risposta del contratto `/v1/` include un’intestazione `x-request-id` generata da Sealarca. Il corpo dell’errore può includere anche un identificativo distinto `(id=…)`; conservare entrambi quando presenti.

Buone pratiche operative

Queste raccomandazioni seguono il comportamento attuale di autenticazione, accesso ai modelli, fatturazione e tracciamento delle richieste.

Proteggere il segreto
Caricate la chiave da una variabile d’ambiente o da un secret manager e ruotatela se viene esposta.
Scoprire gli ID modello
Chiamate /v1/models con la stessa chiave ed evitate di fissare un ID modello nel codice distribuito.
Riprovare in modo selettivo
Correggete gli errori 4xx deterministici. Usate un backoff limitato per 429, 5xx e timeout del gateway.
Conservare gli ID richiesta
Conservate x-request-id e ogni ID errore restituito con un errore per l’assistenza e la diagnosi.

`store` e conservazione Il contratto pubblico non definisce `store` come controllo della conservazione. Non fare affidamento su `store: false` al posto delle garanzie Sealarca di assenza di registrazione dei contenuti e di cache delle risposte; i metadati operativi restano soggetti alle condizioni applicabili.

Crediti e limiti

L’API utilizza crediti prepagati in CHF. Il saldo viene verificato prima della richiesta e l’utilizzo effettivo viene addebitato.

Nessun abbonamento richiesto

Il saldo viene alimentato tramite ricariche di crediti.

Costo per modello

Input e output possono avere tariffe diverse. Il catalogo mostra i prezzi pubblici di ciascun modello.

HTTP 402

Ricarica il saldo prima di riprovare.

Visualizza modelli e prezzi

Continuare con la pagina Sealarca giusta

Usate questi link per accesso all’account, consumo dei modelli, protezioni e perimetro tecnico del servizio.

Pronti a integrare Sealarca?

Create l’accesso, scoprite un modello autorizzato e inviate la vostra prima richiesta lato server.

Iniziare Vedere le tariffe

Integrate Sealarca nella vostra applicazione.

Dall’account alla prima risposta

Creare un account

Aggiungere crediti

Creare una chiave API

Elencare i modelli

Effettuare la prima chiamata

Autenticare ogni richiesta

Prima richiesta

Risposta JSON minima prevista

Scopri i modelli

Contratto degli endpoint pubblici

Models

Responses

Chat Completions

Claude Messages

Embeddings

Prova Vault

Bundle di prova firmato

Chiavi di firma Vault

Attestazione Vault

Esempi per linguaggio

Trasmettere una risposta

Attivare lo streaming

Leggere il flusso

GLM 5.3 Flash — Shield

Consultare la prova di un’inferenza Vault

Controllo prima di ogni esecuzione

Tre header da conservare

202 · pending

200 · verified

200 · failed

404 / 410

Controllo avanzato dell’ambiente Vault

Schema sealarca-vault-attestation/1

Definizione degli hash

Bundle firmato e verifica offline

Riferimento degli endpoint

/models

Richiesta

Risposta

/responses

Obbligatorio

Comune

Output

/chat/completions

Obbligatorio

Comune

Output

/messages

Obbligatorio

Comune

Output

Errori e regole per i nuovi tentativi

Buone pratiche operative

Proteggere il segreto

Scoprire gli ID modello

Riprovare in modo selettivo

Conservare gli ID richiesta

Crediti e limiti

Nessun abbonamento richiesto

Costo per modello

HTTP 402

Continuare con la pagina Sealarca giusta

Creare la vostra chiave

Vedere le tariffe

Leggere sicurezza e riservatezza

Leggere l’infrastruttura

Pronti a integrare Sealarca?