L'URL di base dell'API
In questa pagina
Il punto di ingresso dell’API Grok
Ogni richiesta all’API xAI passa attraverso un unico URL di base. Comprendere questo URL e gli endpoint disponibili è essenziale prima di scrivere la tua prima riga di codice.
L’URL di base
L’API Grok si trova a questo indirizzo:
https://api.x.ai/v1
Questo URL è la radice per ogni endpoint. Ad esempio, per creare una risposta, l’URL completo è https://api.x.ai/v1/responses.
Perché /v1?
Il prefisso /v1 indica la versione dell’API. Il versioning permette a xAI di evolvere l’API senza interrompere le applicazioni esistenti. Se dovesse arrivare una versione 2, coesisterà con la v1 durante un periodo di transizione.
Compatibilità con l’ecosistema OpenAI
Una caratteristica fondamentale dell’API xAI è la sua compatibilità con il formato OpenAI. In pratica, se hai già del codice che funziona con l’API OpenAI, ti basta modificare due impostazioni per usare Grok:
- L’URL di base: sostituisci
https://api.openai.com/v1conhttps://api.x.ai/v1 - La chiave API: sostituisci la tua chiave OpenAI con la tua chiave xAI
Questa compatibilità si estende alla maggior parte degli strumenti e delle librerie dell’ecosistema OpenAI: LangChain, LlamaIndex, LiteLLM e molti altri funzionano con Grok senza modifiche al codice.
I principali endpoint
L’API espone diversi endpoint raggruppati per funzionalità.
Generazione di testo
POST /v1/responses: l’endpoint principale per generare risposte (formato moderno)POST /v1/chat/completions: l’endpoint compatibile con OpenAI (formato legacy, ancora supportato)
Generazione di media
POST /v1/images/generations: genera immaginiPOST /v1/images/edits: modifica immagini esistentiPOST /v1/videos/generations: genera videoPOST /v1/tts: sintesi vocale (text-to-speech)
Gestione dei file
POST /v1/files: carica un fileGET /v1/files: elenca i file caricati
Tempo reale
wss://api.x.ai/v1/realtime: agente vocale tramite WebSocket
Imposta l’URL nei tuoi SDK
Quando usi un SDK compatibile con OpenAI, devi specificare esplicitamente l’URL di base:
from openai import OpenAI
client = OpenAI(
api_key="xai-your-key",
base_url="https://api.x.ai/v1"
)
Con l’SDK nativo xAI, l’URL è preconfigurato e non devi impostare nulla.
Testa la connettività
Prima di scrivere qualsiasi codice, una chiamata diretta valida l’intera catena (URL, chiave, rete):
curl https://api.x.ai/v1/models \
-H "Authorization: Bearer xai-your-key"
La risposta elenca i modelli disponibili con la tua chiave. È anche il modo più affidabile per conoscere gli ID esatti dei modelli disponibili sul tuo account, senza dipendere da una documentazione che potrebbe cambiare. Mantieni questa abitudine: valida ogni nuovo ambiente (macchina, CI, server) con questa stessa chiamata prima di qualsiasi deployment.
Limiti e quote
L’API applica limiti di frequenza (rate limits) per ogni team e per ogni modello. Se li superi, ricevi un errore HTTP 429. La console xAI mostra le tue quote attuali e il tuo utilizzo in tempo reale.
Punti chiave
- L’URL di base è
https://api.x.ai/v1per ogni endpoint - L’API è compatibile con il formato OpenAI: cambia l’URL e la chiave, ed è fatto
- L’endpoint principale di generazione è
POST /v1/responses - L’endpoint legacy
POST /v1/chat/completionsrimane disponibile per compatibilità