Come usare l'API grok-4.6: cURL, Python e una richiesta funzionante

grok-4.6 è un modello di chat ottimizzato per il ragionamento, disponibile tramite l'API hiapi. A differenza dei modelli di immagini e video di hiapi, non utilizza la pipeline asincrona /v1/tasks: è un'interfaccia chat completions sincrona e compatibile con OpenAI, quindi ricevi direttamente una normale risposta HTTP (o uno stream SSE), senza polling. Questo articolo inizia con una richiesta minima funzionante, poi illustra ciò che ti serve davvero in produzione: output in streaming, chiamata di strumenti, modalità JSON e gestione degli errori.

Cosa ti serve

• Una chiave API hiapi. Se non ne hai una, ottienila dalla console: ogni richiesta seguente la richiede nell'header Authorization: Bearer sk-....
• Qualsiasi client HTTP. Gli esempi usano curl e requests di Python; la struttura JSON è identica indipendentemente dal linguaggio.
• Nessun SDK necessario. Il formato richiesta/risposta di grok-4.6 è molto vicino alla convenzione OpenAI chat completions, quindi gli strumenti compatibili con OpenAI di solito funzionano, ma hiapi espone il proprio endpoint chat completions anziché un endpoint proprietario: punta il client su https://api.hiapi.ai/v1/chat/completions e usa l'ID modello nudo grok-4.6.

Richiesta minima funzionante

curl https://api.hiapi.ai/v1/chat/completions \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-4.6",
    "messages": [
      {"role": "user", "content": "Spiega in una frase a cosa serve il filtro di Kalman."}
    ]
  }'

Una risposta riuscita è simile a questa:

{
  "id": "b6c018d3-218e-9b06-aa12-5afc02e21b5c",
  "object": "chat.completion",
  "model": "grok-4.6",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Il filtro di Kalman stima lo stato reale di un sistema che varia nel tempo combinando misurazioni rumorose con un modello predittivo, ponderandole in base alle rispettive incertezze."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 24,
    "completion_tokens": 31,
    "total_tokens": 55
  }
}

Il testo della risposta si trova in choices[0].message.content, come in qualsiasi API di chat in stile OpenAI.

Ecco la stessa chiamata in Python con requests:

import os
import requests

resp = requests.post(
    "https://api.hiapi.ai/v1/chat/completions",
    headers={"Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}"},
    json={
        "model": "grok-4.6",
        "messages": [
            {"role": "user", "content": "Spiega in una frase a cosa serve il filtro di Kalman."}
        ],
    },
    timeout=60,
)
resp.raise_for_status()
print(resp.json()["choices"][0]["message"]["content"])

I parametri di regolazione del ragionamento di grok-4.6

grok-4.6 è un modello di ragionamento: prima di scrivere la risposta finale spende token aggiuntivi per "pensare", e questi token di ragionamento vengono fatturati come token di output (le tariffe attuali sono nella pagina prezzi). Puoi controllare la quantità di pensiero tramite reasoning_effort, con valori low, medium, high o xhigh (se omesso, l'API usa high per impostazione predefinita):

curl https://api.hiapi.ai/v1/chat/completions \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-4.6",
    "messages": [{"role": "user", "content": "Salutami con cinque parole."}],
    "reasoning_effort": "low"
  }'

Le risposte non in streaming espongono la traccia di ragionamento del modello in message.reasoning_content, separatamente dal message.content finale. Per attività brevi e a bassa latenza, scendi a low o medium; per problemi a più passaggi, high o xhigh scambiano latenza e token con risposte migliori.

Risposte in streaming

Imposta "stream": true per leggere la risposta come Server-Sent Events invece di attendere il completamento completo:

curl -N https://api.hiapi.ai/v1/chat/completions \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-4.6",
    "messages": [{"role": "user", "content": "Conta da 1 a 5."}],
    "stream": true
  }'

Ogni riga è un blocco data: {...}. I token di ragionamento vengono trasmessi tramite choices[0].delta.reasoning_content, poi i token della risposta tramite choices[0].delta.content, e lo stream termina con il letterale data: [DONE]:

data: {"id":"...","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"reasoning_content":"Elenca"},"finish_reason":null}]}

data: {"id":"...","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":"1, 2"},"finish_reason":null}]}

data: {"id":"...","object":"chat.completion.chunk","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}

data: [DONE]

In Python, requests può iterare lo stream riga per riga:

import json
import requests

with requests.post(
    "https://api.hiapi.ai/v1/chat/completions",
    headers={"Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}"},
    json={
        "model": "grok-4.6",
        "messages": [{"role": "user", "content": "Conta da 1 a 5."}],
        "stream": True,
    },
    stream=True,
    timeout=60,
) as resp:
    for line in resp.iter_lines():
        if not line or not line.startswith(b"data: "):
            continue
        payload = line[len(b"data: "):]
        if payload == b"[DONE]":
            break
        chunk = json.loads(payload)
        delta = chunk["choices"][0]["delta"]
        if "content" in delta:
            print(delta["content"], end="", flush=True)

Chiamata di strumenti

grok-4.6 supporta la chiamata di funzioni in stile OpenAI: passa un array tools e, con tool_choice: "auto", lascia che il modello decida autonomamente quando chiamare uno strumento.

curl https://api.hiapi.ai/v1/chat/completions \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-4.6",
    "messages": [{"role": "user", "content": "Che tempo fa a Tokyo?"}],
    "tools": [
      {
        "type": "function",
        "function": {
          "name": "get_weather",
          "description": "Ottieni il meteo attuale di una città",
          "parameters": {
            "type": "object",
            "properties": {"city": {"type": "string"}},
            "required": ["city"]
          }
        }
      }
    ],
    "tool_choice": "auto"
  }'

Quando il modello decide di chiamare lo strumento, finish_reason restituisce "tool_calls" e gli argomenti arrivano come stringa JSON che devi analizzare tu stesso:

{
  "choices": [
    {
      "message": {
        "role": "assistant",
        "tool_calls": [
          {
            "id": "call_...",
            "type": "function",
            "function": {"name": "get_weather", "arguments": "{\"city\":\"Tokyo\"}"}
          }
        ]
      },
      "finish_reason": "tool_calls"
    }
  ]
}

Esegui la tua funzione, poi aggiungi a messages un messaggio con role: "tool" (contenente il risultato dell'esecuzione e il corrispondente tool_call_id), quindi invia di nuovo la conversazione per ottenere la risposta finale in linguaggio naturale.

Modalità JSON

Se vuoi analizzare la risposta senza il giro di chiamata degli strumenti, imposta response_format:

curl https://api.hiapi.ai/v1/chat/completions \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-4.6",
    "messages": [
      {"role": "system", "content": "Rispondi con un oggetto JSON contenente le due chiavi \"city\" e \"country\"."},
      {"role": "user", "content": "Dov'è la Torre Eiffel?"}
    ],
    "response_format": {"type": "json_object"}
  }'

message.content viene restituito come stringa JSON (sempre all'interno della normale busta chat completions), che puoi analizzare dalla tua parte con json.loads(...). Assicurati di indicare nel prompt al modello di generare effettivamente JSON: response_format vincola il formato dell'output, ma non costruisce lo schema al posto tuo.

Pratiche per la produzione

• Gestisci i codici di errore documentati. Una chiave errata o mancante restituisce HTTP 401, con corpo della risposta {"error":{"code":"permission_denied","message":"...","request_id":"...","type":"hiapi_error"}}. Saldo insufficiente restituisce 402; ID modello non valido o parametri malformati restituiscono 400. Controlla prima il codice di stato e registra il request_id dal corpo della risposta di errore: se devi segnalare un problema, è proprio questa l'informazione che ti servirà.
• Usa retry con backoff per 429 e 503. hiapi applica limiti di velocità per account; 429 indica che hai superato il limite, 503 che il modello è temporaneamente non disponibile. Entrambi si prestano a un retry con backoff esponenziale limitato (ad esempio 1 secondo, 2 secondi, 4 secondi, poi desisti dopo alcuni tentativi), anziché a un ciclo serrato.
• Imposta timeout delle richieste. Con intensità di ragionamento high o xhigh i tempi sono sensibilmente più lunghi rispetto a low; imposta il timeout del client in base al livello di intensità utilizzato, invece di usare un'unica costante globale.
• Preferisci lo streaming in ogni scenario rivolto all'utente. Le chiamate non in streaming si bloccano finché l'intera risposta (compresi tutti i token di ragionamento) non è pronta; lo streaming invia subito i primi token alla tua UI e ti consente di mostrare uno stato "sto pensando" quando gli incrementi di reasoning_content arrivano prima della risposta finale.
• Non codificare le chiavi nel codice. Caricale da variabili d'ambiente o da un gestore di segreti, mai dal controllo del codice sorgente: gli esempi sopra leggono proprio per questo da $HIAPI_API_KEY / os.environ["HIAPI_API_KEY"].

Per il riferimento completo dei parametri (inclusi tutti i campi accettati da grok-4.6), consulta la pagina del modello e la documentazione di grok-4.6.

Domande frequenti

grok-4.6 su hiapi è compatibile con l'SDK OpenAI? Le strutture di richiesta e risposta seguono la convenzione OpenAI chat completions (messages, choices[0].message.content, incrementi in streaming, chiamata di strumenti), quindi la maggior parte degli strumenti compatibili con OpenAI che consentono di sovrascrivere l'URL di base e l'ID modello dovrebbe funzionare. Imposta l'URL di base su https://api.hiapi.ai/v1 e usa grok-4.6 come ID modello.

Perché la mia risposta è più lenta rispetto ad altri modelli? grok-4.6 spende token per un ragionamento interno prima di rispondere, e questi token vengono fatturati come token di output. Per chiamate sensibili alla latenza, abbassa reasoning_effort a low o medium, oppure passa allo streaming, così non devi attendere l'intera risposta in un colpo solo.

Cosa significa reasoning_content e posso nasconderlo all'utente? È la traccia di ragionamento intermedia del modello, restituita separatamente da content (in streaming come delta.reasoning_content). Puoi assolutamente non renderizzarla nella UI: solo content è la risposta finale.

Ho ricevuto 401 e permission_denied: cosa è andato storto? Il tuo header Authorization è mancante, malformato, oppure la chiave non è valida o è stata revocata. Ricontrolla di aver inviato Authorization: Bearer sk-... e di usare una chiave valida presente nella console.

Posso usare insieme la chiamata di funzioni e la modalità JSON di grok-4.6 nella stessa richiesta? tools/tool_choice e response_format sono parametri indipendenti e possono essere impostati contemporaneamente, ma se il modello decide di chiamare uno strumento, il finish_reason di quel turno sarà "tool_calls" e message.content potrebbe essere vuoto: gestisci prima la chiamata di strumenti, poi richiedi la risposta finale in formato JSON nel turno successivo.

Come posso controllare i costi? I token di ragionamento contano come token di output, quindi il costo varia in base a reasoning_effort e alla lunghezza della risposta. Prima di eseguire attività ad alto carico, consulta le tariffe per token attuali nella pagina dei prezzi.