Riferimento API

URL base

Ogni richiesta viene inviata a:

Autenticazione

Crea una chiave nella pagina chiavi API, poi inviala come token bearer nell’header Authorization. Viene memorizzato solo un hash della tua chiave — copiala al momento della creazione, perché GatifyAI non potrà più mostrartela in seguito.

Avvio rapido

Una richiesta minima in curl, Python o TypeScript:

curl https://gatifyai.com/api/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MODEL_NAME",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

Limitare una chiave a modelli specifici

Per impostazione predefinita, una nuova chiave può usare qualsiasi modello gratuito di GatifyAI, con lo stesso fallback automatico usato dalla chat web se uno non è disponibile. Puoi invece limitare una chiave a un modello specifico o a un elenco ristretto — la chiave userà quindi solo i modelli di quell’elenco, nell’ordine indicato, indipendentemente dal modello richiesto. Richiedere un modello al di fuori di quell’elenco restituisce un errore 400 che indica i modelli che la chiave può effettivamente usare.

Chattare come una persona

Passa model: "persona/<slug>" per chattare come una persona pubblicata nella galleria della community — la sua personalità e i modelli preferiti vengono usati automaticamente, sempre vincolati dai modelli consentiti dalla tua chiave, se ne hai impostati. Trova lo slug di una persona e un esempio pronto all’uso nella sua pagina, nella scheda API.

{
  "model": "persona/senior-engineer",
  "messages": [{"role": "user", "content": "Review my code."}]
}

Streaming e non-streaming

Imposta stream: true per ricevere i token man mano che vengono generati, esattamente come il formato di streaming di OpenAI (Server-Sent Events, terminato da [DONE]). Ometti questo parametro, o impostalo su false, per attendere la risposta completa e ricevere un’unica risposta JSON — questo è il comportamento predefinito.

Errori

Gli errori seguono il formato di errore di OpenAI: {"error": {"message": "...", "type": "..."}}. Un 401 indica una chiave mancante, non valida o revocata. Un 400 indica che la richiesta stessa non è valida — il più delle volte un modello non riconosciuto, uno slug di persona non pubblicato/sconosciuto, oppure un modello al di fuori dell’elenco consentito dalla tua chiave. Un 502 indica che nessun modello candidato ha risposto.

{
  "error": {
    "message": "This API key may only use: llama-3.1-8b:free",
    "type": "invalid_request_error"
  }
}

Limiti di frequenza

Le richieste API contano ai fini dello stesso limite di frequenza chat per account usato dall’app web — al momento non esiste una quota separata per il traffico API.