Documentazione

Parti in 2 minuti.

L'API di Geraikita AI supporta due formati contemporaneamente: OpenAI Chat Completions e Anthropic Messages. Usa l'SDK di OpenAI, l'SDK di Anthropic, Claude Code CLI, Cline e altri strumenti — basta cambiare base URL e chiave API.

Base URL (OpenAI)https://ai.geraikita.com/v1

Base URL (Anthropic)https://ai.geraikita.com

AutenticazioneBearer gk-... (oppure x-api-key: gk-...)

Importante — non scrivere /v1 due volte.

OpenAIhttps://ai.geraikita.com/v1I client OpenAI aggiungono /chat/completions alla base URL — quindi la base termina con /v1.

Anthropic / Claude Code CLIhttps://ai.geraikita.comI client Anthropic (Claude Code CLI, SDK Anthropic) aggiungono /v1/messages da sé — quindi la base va senza /v1.

Se sbagli, il percorso diventa /v1/v1/messages → errore 400.

Il piano gratuito (Bansos) usa una CHIAVE SEPARATA — non la tua chiave a pagamento.

La chiave bansos va prima richiesta nella pagina Bansos (login + verifica Telegram, gratis, una volta per account). Una chiave gk- a pagamento della Dashboard non funziona sull'endpoint bansos, e viceversa — se le confondi ottieni 401 unauthorized.

Anche la base URL bansos è diversa da quella a pagamento qui sopra:

Base URL bansoshttps://ai.geraikita.com/v1/claude

OpenAIhttps://ai.geraikita.com/v1/claude/chat/completions

Anthropic / Claude Code CLIANTHROPIC_BASE_URL=https://ai.geraikita.com/v1/claudeL'SDK aggiunge /v1/messages da sé → https://ai.geraikita.com/v1/claude/v1/messages.

Scoperta dei modelliGET https://ai.geraikita.com/v1/claude/models

Tutto il resto è esattamente uguale all'endpoint a pagamento.

Autenticazione

Ogni richiesta porta la tua chiave API gk- nell'header Authorization: Bearer gk-.... Le chiavi si creano nella dashboard e vengono mostrate solo una volta alla creazione — conservale al sicuro. Puoi limitare ogni chiave a modelli specifici (allowlist).

Prima richiesta

from openai import OpenAI

client = OpenAI(
    base_url="https://ai.geraikita.com/v1",
    api_key="gk-xxxxxxxx",
)
resp = client.chat.completions.create(
    model="claude-sonnet-5",
    messages=[{"role": "user", "content": "Halo!"}],
)
print(resp.choices[0].message.content)

Claude Code CLI

Claude Code usa il formato Anthropic. Imposta la base URL sulla root (https://ai.geraikita.com — senza /v1), poi esegui claude. Usa i modelli claude-sonnet-5 / claude-opus-5 / claude-haiku-4-5.

# Base URL = ROOT senza /v1 (Claude Code aggiunge /v1/messages da sé)
export ANTHROPIC_BASE_URL="https://ai.geraikita.com"
export ANTHROPIC_AUTH_TOKEN="gk-xxxxxxxx"
export ANTHROPIC_DEFAULT_SONNET_MODEL="claude-sonnet-5"
export ANTHROPIC_DEFAULT_OPUS_MODEL="claude-opus-5"
export ANTHROPIC_DEFAULT_HAIKU_MODEL="claude-haiku-4-5"

claude

Cline e altri strumenti

Cline / Roo (OpenAI Compatible): provider OpenAI Compatible, Base URL https://ai.geraikita.com/v1, chiave API gk-..., Model ID claude-sonnet-5.

Cline (Anthropic): provider Anthropic, Base URL https://ai.geraikita.com, chiave API gk-....

Il tuo strumento rileva i modelli automaticamente? L'endpoint GET https://ai.geraikita.com/v1/models è disponibile. Se c'è un campo "Gateway base URL" che aggiunge automaticamente /v1/models, compilalo con https://ai.geraikita.com (root) così non diventa /v1/v1/models.

GeraiPoints

1 GP = Rp1. Ti viene fatturato per token in base all'uso reale di ogni richiesta — nessun costo fisso per richiesta, solo un piccolo minimo per richiesta per ciascun modello (floor). Ricarichi i GeraiPoints nella dashboard; il saldo non scade mai e vale per qualsiasi modello. Niente abbonamenti né quote mensili.

Elenco dei modelli

I valori di model che puoi inviare. Vedi la pagina dei prezzi per le tariffe di ciascun modello.

Scrivi il nome del modello ESATTAMENTE come elencato — senza prefisso. Invia claude-sonnet-5, non gp/claude-sonnet-5 né openai/claude-sonnet-5. Alcuni client/CLI antepongono al modello il nome di un provider (es. un profilo chiamato gp → il modello diventa gp/claude-sonnet-5) → il risultato è 404 unknown model. Il prefisso gk- è per le chiavi API (l'header Authorization), non per i nomi dei modelli.

Crea una chiave API

Apri la Dashboard → Crea chiave API, dalle un nome e (facoltativamente) limitala a modelli specifici. La chiave in chiaro viene mostrata solo una volta. Fino a 5 chiavi attive per account — revoca una vecchia per crearne una nuova.

Codici di errore

Stato	Significato
400	Base URL / body errati — assicurati che /v1 non sia doppio (es. /v1/v1/messages)
401	Chiave API non valida / corsia sbagliata — chiave a pagamento ≠ chiave bansos. Controlla la base URL: a pagamento usa /v1, bansos usa /v1/claude
402	GeraiPoints insufficienti — ricarica per favore
403	Modello non consentito per questa chiave
404	Modello sconosciuto — invia il NOME ESATTO DEL MODELLO (es. claude-sonnet-5), senza prefisso. Nomi come gp/claude-sonnet-5 o openai/... daranno 404
429	Troppe richieste