Come funziona il Gateway

Architettura

La tua applicazione comunica con Pura LLM usando il formato API OpenAI. Autentichiamo la API key, applichiamo quote, instradiamo verso il provider configurato e restituiamo la risposta — senza memorizzare i contenuti.

Flusso della richiesta

1. La tua app invia una richiesta a /v1/chat/completions con la API key Pura LLM
2. Il gateway valida la key, verifica saldo wallet e rate limit
3. La richiesta viene instradata verso il provider LLM configurato nell'UE
4. La risposta del provider torna alla tua app in formato OpenAI
5. I metadata di utilizzo token vengono registrati per il billing — i contenuti non vengono mai salvati

Endpoint supportati

Sono disponibili tutti gli endpoint standard compatibili OpenAI:

Tracciabilità delle richieste: compliance_metadata v2

Quando presenti, i metadati di compliance descrivono la tracciabilità della singola richiesta. Leggi i campi e la versione restituiti nella risposta; consulta le condizioni del servizio per i requisiti di residenza applicabili.

Il contratto v2 garantisce provider, modello effettivo, data_zone UE, ingress_region, upstream_request_id originale, gateway_request_id e timestamp UTC. La regione di ingresso non identifica la regione effettiva di elaborazione: Azure Data Zone Standard e i profili geografici Bedrock possono distribuire le richieste tra regioni della zona certificata. Il campo region resta riservato ai deployment regionali v1.

provider_raw è facoltativo e può variare per provider. Non usarlo come dipendenza del tuo codice: per correlare una richiesta usa i campi di tracciabilità documentati.

{
  "extensions": {
    "compliance_metadata": {
      "schema_version": "2",
      "provider": "azure",
      "model": "example-model",
      "data_zone": "EU",
      "ingress_region": "Italy North",
      "upstream_request_id": "provider-request-id",
      "gateway_request_id": "2c5b008e-3931-4ce8-a7d5-f5e7c38215ea",
      "timestamp": "2026-09-29T12:00:00.000Z",
      "provider_raw": {
        "headers": {
          "apim-request-id": "provider-request-id"
        }
      }
    }
  }
}

Il nucleo è disponibile negli header HTTP prima del primo evento di contenuto. In SSE viene ripetuto in un chunk finale con choices vuoto, prima di [DONE]. Gestisci anche i chunk senza choices; uno stream interrotto non garantisce il chunk finale.

X-Pura-Compliance-Schema-Version: 2
X-Pura-Compliance-Provider: azure
X-Pura-Compliance-Model: example-model
X-Pura-Compliance-Data-Zone: EU
X-Pura-Compliance-Ingress-Region: Italy North
X-Pura-Compliance-Upstream-Request-Id: provider-request-id
X-Pura-Compliance-Gateway-Request-Id: 2c5b008e-3931-4ce8-a7d5-f5e7c38215ea
X-Pura-Compliance-Timestamp: 2026-09-29T12:00:00.000Z

L’estensione è annidata in extensions.compliance_metadata. La modalità predefinita e X-Pura-Compliance: 2 restituiscono il contratto della route. X-Pura-Compliance: headers mantiene il body OpenAI standard e restituisce i metadati negli header, senza chunk finale. X-Pura-Compliance: 1 è riservato alle route regionali v1 e rifiuta le route con zona geografica.

HTTP 502 indica che la richiesta non ha ricevuto una risposta utilizzabile. Conserva timestamp e identificativi disponibili per il supporto; evita di ripetere automaticamente un’inferenza con esito incerto.

Per immagini e altri contenuti generati, gestisci i riferimenti e i metadati restituiti nella risposta. La presenza di un marcatore di provenienza dipende dal contenuto e dal servizio utilizzato.

Gli identificativi di tracciabilità disponibili nei log possono aiutarti nelle richieste di assistenza. Per il trattamento dei contenuti e dei metadati consulta la guida sulla conservazione dei dati.