Vai al contenuto principale
Italiano— Scegli una lingua
Menu

L'URL di base dell'API

Lezione 4 di 14 Aggiornata il 30 luglio 2026 Sviluppatore
In questa pagina
  1. Il punto di ingresso dell’API Grok
  2. L’URL di base
  3. Compatibilità con l’ecosistema OpenAI
  4. I principali endpoint
  5. Imposta l’URL nei tuoi SDK
  6. Testa la connettività
  7. Limiti e quote
  8. Punti chiave

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/v1 con https://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 immagini
  • POST /v1/images/edits: modifica immagini esistenti
  • POST /v1/videos/generations: genera video
  • POST /v1/tts: sintesi vocale (text-to-speech)

Gestione dei file

  • POST /v1/files: carica un file
  • GET /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/v1 per 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/completions rimane disponibile per compatibilità