Tutoriale

Come utilizzare Claude Opus 4.8 tramite l'API hiapi

Sep 21, 2026

Cosa costruirai

Un'integrazione funzionante che chiama Claude Opus 4.8 tramite l'API Chat Completions compatibile con OpenAI di hiapi — il modello di punta dell'attuale serie Claude 4.8 di Anthropic. Una singola richiesta restituisce un completamento reale, insieme ai pattern di produzione di cui avrai bisogno una volta che la demo funziona (streaming, tool calling, pensiero adattivo).

Prerequisiti: una chiave API hiapi. Ottienila dalla console — è semplicemente una stringa sk-..., e la stessa chiave vale per tutti i modelli abilitati sul tuo account, non solo per questo modello.

Tutto quanto segue è stato eseguito realmente contro l'API live al momento della stesura.

Esempio minimo funzionante

Claude Opus 4.8 è un modello testuale sull'endpoint Chat Completions standard — non il flusso asincrono /v1/tasks che hiapi usa per i modelli di immagini/video/audio. Una richiesta, una risposta, nessun polling.

curl https://api.hiapi.ai/v1/chat/completions \
  -H "Authorization: Bearer sk-<your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-opus-4-8",
    "messages": [
      {"role": "user", "content": "Review this function for edge cases and suggest a fix."}
    ],
    "max_tokens": 1024
  }'

Risposta (abbreviata):

{
  "id": "msg_011CfFm8abLRcYtLVSky81As",
  "model": "claude-opus-4-8",
  "object": "chat.completion",
  "choices": [
    {
      "index": 0,
      "message": { "role": "assistant", "content": "..." },
      "finish_reason": "stop"
    }
  ],
  "usage": { "prompt_tokens": 10, "completion_tokens": 4, "total_tokens": 14 }
}

La stessa chiamata in Python, usando solo requests:

import requests

resp = requests.post(
    "https://api.hiapi.ai/v1/chat/completions",
    headers={"Authorization": "Bearer sk-<your-api-key>"},
    json={
        "model": "claude-opus-4-8",
        "messages": [
            {"role": "user", "content": "Review this function for edge cases and suggest a fix."}
        ],
        "max_tokens": 1024,
    },
    timeout=60,
)
resp.raise_for_status()
data = resp.json()
print(data["choices"][0]["message"]["content"])
print(data["usage"])  # prompt_tokens / completion_tokens / total_tokens

Invia direttamente l'ID nudo del modello claude-opus-4-8 — nessun prefisso di provider, nessun suffisso di routing. hiapi elenca due route backend per questo modello (default e aws) per ridondanza, ma condividono lo stesso ID modello; non devi scegliere tra le due.

Poiché il formato della richiesta è compatibile con OpenAI, funziona senza modifiche anche con gli SDK Python/JS ufficiali openai — basta puntare base_url su https://api.hiapi.ai/v1 e passare la tua chiave hiapi.

Pattern di produzione

Streaming

Imposta "stream": true e leggi i Server-Sent Events. Ogni chunk contiene un frammento delta.content; il flusso termina nell'ultimo chunk con finish_reason: "stop", seguito da una sentinella [DONE]:

curl https://api.hiapi.ai/v1/chat/completions \
  -H "Authorization: Bearer sk-<your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-opus-4-8",
    "messages": [{"role": "user", "content": "Count 1 to 3"}],
    "stream": true,
    "max_tokens": 20
  }'

data: {"choices":[{"delta":{"content":"","role":"assistant"},"finish_reason":null,"index":0}]}

data: {"choices":[{"delta":{"content":"1"},"finish_reason":null,"index":0}]}

data: {"choices":[{"delta":{"content":", 2, 3"},"finish_reason":null,"index":0}]}

data: {"choices":[{"delta":{},"finish_reason":"stop","index":0}]}

data: [DONE]

Accumula choices[0].delta.content tra i chunk per ricostruire il testo completo. L'evento dati finale (dopo finish_reason) trasporta i totali di usage, non un delta.

Tool calling

Dichiara le funzioni come faresti con OpenAI, poi al turno successivo ripeti il messaggio tool_calls dell'assistente e il messaggio con il risultato tool:

curl https://api.hiapi.ai/v1/chat/completions \
  -H "Authorization: Bearer sk-<your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-opus-4-8",
    "messages": [{"role": "user", "content": "What is the status of task demo-123?"}],
    "max_tokens": 200,
    "tools": [{
      "type": "function",
      "function": {
        "name": "get_task_status",
        "description": "Look up a task by ID.",
        "parameters": {
          "type": "object",
          "properties": {"task_id": {"type": "string"}},
          "required": ["task_id"],
          "additionalProperties": false
        }
      }
    }],
    "tool_choice": "auto"
  }'

La risposta arriva con finish_reason: "tool_calls" e include il nome della funzione e gli argomenti codificati in JSON in choices[0].message.tool_calls. Esegui la tua funzione localmente, poi nella richiesta successiva invia il risultato come messaggio con role: "tool" che porta il tool_call_id corrispondente — il modello continuerà da lì.

Pensiero adattivo

Claude Opus 4.8 supporta turni di ragionamento a partecipazione opzionale. Aggiungi "thinking": {"type": "adaptive"} e scegli il livello di impegno tramite output_config.effort (low, medium o high sono tutti confermati funzionanti):

{
  "model": "claude-opus-4-8",
  "messages": [{"role": "user", "content": "Compare two approaches and state the trade-offs."}],
  "thinking": {"type": "adaptive"},
  "output_config": {"effort": "high"}
}

Prima di costruire su questa funzionalità, ci sono due cose da sapere. Primo, "adattivo" significa che il modello decide da solo se un prompt merita di essere pensato — con livelli di impegno low o addirittura medium, una domanda semplice potrebbe non restituire affatto il campo reasoning_details, quindi non dare per scontato che ogni richiesta lo produca. Secondo, a differenza di alcuni altri modelli testuali su hiapi, Opus 4.8 non restituisce una traccia di ragionamento leggibile: le voci reasoning.text nell'array reasoning_details tornano vuote, solo le voci signature sono popolate. Tratta reasoning_details come uno stato di continuazione opaco — se devi portare la conversazione in successive chiamate di tool, passalo così com'è — e non analizzarlo né mostrarlo all'utente.

Gestione degli errori

Un errore di autenticazione restituisce HTTP 401 con un envelope hiapi_error:

{
  "error": {
    "code": "permission_denied",
    "message": "This API key is invalid. Check that it is correct or use another API key and try again.",
    "type": "hiapi_error"
  }
}

Controlla response.status_code prima di accedere a response.json()["choices"], e se devi escalare registra error.request_id — il team di supporto può usarlo per tracciare la chiamata specifica.

Idempotenza e retry

Le chiamate Chat Completions non sono idempotenti per ID di richiesta come i task /v1/tasks — una richiesta ritentata è un nuovo completamento e una nuova fatturazione. Per il traffico di produzione, avvolgi la logica di retry con backoff nel tuo codice per i casi 5xx/timeout, e limita max_tokens in modo che una tempesta di retry (o chiamate di pensiero adattivo di lunga durata) non causi costi illimitati.

Letture correlate

Claude Opus 4.8 su hiapi — prezzi attuali e model card.
Autenticazione — come funzionano le chiavi API hiapi e come ruotarle.
Come utilizzare Claude Sonnet 4.6 tramite l'API hiapi — lo stesso pattern di integrazione per il livello Claude bilanciato sui costi di hiapi, se il tuo carico di lavoro non richiede un modello potente come Opus 4.8.
Prezzi hiapi — tariffe per token in tempo reale per Claude Opus 4.8 e tutti gli altri modelli abilitati.

Domande frequenti

claude-opus-4-8 è l'ID modello esatto che devo inviare? Sì — invia la stringa nuda claude-opus-4-8 nel campo model. Nessun prefisso specifico del provider, nessun suffisso di routing; hiapi lo risolve internamente alla route backend corretta.

Questo usa lo stesso flusso /v1/tasks dei modelli di immagini e video di hiapi? No. I modelli testuali come Claude Opus 4.8 usano l'endpoint sincrono POST /v1/chat/completions — una richiesta, una risposta (o un flusso SSE). /v1/tasks si applica solo ai modelli media (immagini, video, audio), che funzionano in modo asincrono e restituiscono un URL o una callback da interrogare.

Posso usare l'SDK OpenAI invece di curl/requests grezzi? Sì. Poiché l'endpoint è compatibile con OpenAI, punta base_url dell'SDK ufficiale openai su https://api.hiapi.ai/v1 e usa la tua chiave hiapi come api_key — nessun'altra modifica al codice è necessaria per chat di base, streaming o tool calling.

Dovrei usare Opus 4.8 o Sonnet 4.6? Opus 4.8 è il livello più capace e più costoso — sceglilo per ragionamento, coding o compiti agentici più difficili, quando l'accuratezza conta più della latenza o del costo per token. Per traffico ad alto volume o sensibile alla latenza, Claude Sonnet 4.6 offre la stessa forma di API a un prezzo inferiore.

thinking restituisce sempre una traccia di ragionamento visibile? No su entrambi i fronti: il pensiero adattivo potrebbe saltare del tutto il ragionamento per richieste giudicate semplici, e quando effettivamente pensa, i campi di testo in reasoning_details di Opus 4.8 attualmente tornano vuoti — solo la signature è popolata. Non costruire UI che presuppongano la presenza costante di una traccia leggibile.

Dove posso vedere i prezzi attuali prima di lanciare grandi volumi? La pagina dei prezzi di hiapi elenca le tariffe per token in tempo reale di Claude Opus 4.8 — controllala prima di fare budget, poiché questo articolo non codifica cifre che potrebbero essere obsolete.