Come usare Claude Sonnet 4.6 tramite l'API hiapi

Cosa costruirai

Un esempio di integrazione funzionante: chiamare Claude Sonnet 4.6 tramite l'API Chat Completions compatibile con OpenAI di hiapi — una singola richiesta restituisce un risultato di completamento reale, e allo stesso tempo copre i pattern di livello produttivo che userai effettivamente una volta che la demo funziona (streaming, chiamata di strumenti, pensiero adattivo).

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

Tutto ciò che segue è stato verificato eseguendolo realmente sull'API live al momento della stesura di questo articolo.

Esempio minimo funzionante

Claude Sonnet 4.6 è un modello testuale sull'endpoint standard Chat Completions — 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-sonnet-4-6",
    "messages": [
      {"role": "user", "content": "Explain how an HTTP cache works in three short paragraphs."}
    ]
  }'

Risposta (troncata):

{
  "id": "msg_bdrk_011Cf8Bo25qCVFFQF5ETk8Wf",
  "model": "claude-sonnet-4-6",
  "object": "chat.completion",
  "choices": [
    {
      "index": 0,
      "message": { "role": "assistant", "content": "..." },
      "finish_reason": "stop"
    }
  ],
  "usage": { "prompt_tokens": 13, "completion_tokens": 4, "total_tokens": 17 }
}

La stessa chiamata in Python utilizzando solo requests:

import requests

resp = requests.post(
    "https://api.hiapi.ai/v1/chat/completions",
    headers={"Authorization": "Bearer sk-<your-api-key>"},
    json={
        "model": "claude-sonnet-4-6",
        "messages": [
            {"role": "user", "content": "Explain how an HTTP cache works in three short paragraphs."}
        ],
    },
    timeout=60,
)
resp.raise_for_status()
data = resp.json()
print(data["choices"][0]["message"]["content"])
print(data["usage"])  # prompt_tokens / completion_tokens / total_tokens

Poiché la struttura è compatibile con OpenAI, questo codice funziona senza modifiche anche con gli SDK Python/JS ufficiali openai — basta puntare base_url a https://api.hiapi.ai/v1 e passare la tua chiave hiapi.

Pattern di livello produttivo

Streaming

Imposta "stream": true e leggi i Server-Sent Events. Ogni blocco di dati trasporta un frammento delta.content; il flusso termina con l'ultimo blocco di dati con finish_reason: "stop", seguito dal 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-sonnet-4-6",
    "messages": [{"role": "user", "content": "Count 1 to 3"}],
    "stream": true
  }'

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

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

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

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

data: [DONE]

Accumulando choices[0].delta.content tra i blocchi di dati si ricostruisce il testo completo.

Chiamata di strumenti

Dichiara le funzioni come faresti con OpenAI, poi al turno successivo reinvia il messaggio tool_calls dell'assistente insieme a un messaggio di 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-sonnet-4-6",
    "messages": [{"role": "user", "content": "What is the status of task demo-123?"}],
    "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 restituisce finish_reason: "tool_calls", con 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 role: "tool" con il tool_call_id corrispondente — il modello riprende da lì.

Pensiero adattivo

Claude Sonnet 4.6 supporta una fase di ragionamento attivabile su richiesta. Aggiungi "thinking": {"type": "adaptive"} e scegli il livello di impegno tramite output_config.effort (low, medium, high o max):

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

La traccia di ragionamento leggibile viene restituita tramite choices[0].message.reasoning_content; l'array originale reasoning_details trasporta metadati di firma e, se vuoi continuare la conversazione ed entrare nella chiamata di strumenti, devi conservarlo così com'è — non analizzarlo, mostrarlo o inventarlo, ma passarlo direttamente nella richiesta successiva.

Gestione degli errori

Un errore di autenticazione restituisce HTTP 401 con una busta di errore 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 hai bisogno di escalare la questione, registra error.request_id — il team di supporto può usarlo per rintracciare la chiamata specifica.

Idempotenza e retry

Le chiamate a Chat Completions non sono idempotenti per ID di richiesta come i job /v1/tasks — una richiesta ritentata è un nuovo completamento. Per il traffico di produzione, avvolgi la chiamata in un tuo retry con backoff per gestire 5xx e timeout, e imposta un limite a max_tokens per evitare che una tempesta di retry generi una fattura senza limiti.

Letture correlate

• Riferimento del modello Claude Sonnet 4.6 — tabella completa dei parametri, schema delle risposte e altri esempi di richiesta direttamente dalla documentazione hiapi.
• Autenticazione — come funzionano le chiavi API hiapi e come ruotarle.
• Prezzi hiapi — tariffe per token in tempo reale per Claude Sonnet 4.6 e tutti gli altri modelli abilitati.

Domande frequenti

claude-sonnet-4-6 è l'ID esatto del modello che devo inviare? Sì — invia la stringa nuda claude-sonnet-4-6 nel campo model. hiapi la instrada a Claude Sonnet 4.6 di Anthropic dietro l'interfaccia compatibile con OpenAI, quindi non serve alcun prefisso specifico del provider.

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

Posso usare l'SDK OpenAI invece di curl/requests nativi? Sì. Poiché l'endpoint è compatibile con OpenAI, basta puntare base_url dell'SDK ufficiale openai a https://api.hiapi.ai/v1 e fornire la tua chiave hiapi come api_key — nessun'altra modifica al codice è necessaria per chat di base, streaming o chiamata di strumenti.

Claude Sonnet 4.6 supporta input di immagini? Sì, tramite blocchi di contenuto — imposta il content del messaggio a un array che contiene un blocco con type: "image_url", con image_url.url che punta a un URL pubblico di immagine, affiancato al tuo blocco di testo.

Cosa succede se ometto thinking? In base alla versione attuale, il pensiero adattivo è attivabile su richiesta — ometti il campo thinking (o imposta thinking.type a disabled) e il modello risponderà direttamente, senza reasoning_content nella risposta.

Dove vedo i prezzi correnti prima di lanciare attività su larga scala? La pagina dei prezzi di hiapi elenca le tariffe per token in tempo reale di Claude Sonnet 4.6 — controllale prima di fare un preventivo, poiché le tariffe possono cambiare e questo articolo non codifica una cifra che potrebbe essere obsoleta.