API Claude Opus 5.5: guida rapida con curl e Python pronta all'uso

Claude Opus 5.5 è il più recente modello di Anthropic per la programmazione agentica e il ragionamento su contesti lunghi, e hiapi ha completato l'integrazione lo stesso giorno in cui è stato reso disponibile sulla piattaforma. A differenza dei modelli per immagini, video e audio di hiapi — che utilizzano tutti il pattern asincrono POST /v1/tasks → polling — Claude Opus 5.5 è un modello di conversazione puramente testuale, quindi è sufficiente inviare una richiesta sincrona a /v1/chat/completions per richiamarlo. Questa guida fornisce una chiamata curl pronta all'uso, la versione Python della stessa chiamata e i dettagli di produzione da conoscere prima del rilascio (intensità di ragionamento, output in streaming, gestione degli errori).

Preparazione

• Un account hiapi e una chiave API. Puoi crearle nella pagina API Keys — tutti i modelli hiapi, incluso Claude Opus 5.5, condividono la stessa chiave.
• Non è necessario installare alcun SDK. Claude Opus 5.5 utilizza il formato Chat Completions compatibile con OpenAI di hiapi, quindi qualsiasi client HTTP (curl, requests, fetch) funziona subito.

Richiesta minima funzionante (curl)

curl -X POST "https://api.hiapi.ai/v1/chat/completions" \
  -H "Authorization: Bearer sk-YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-opus-5-5",
    "messages": [
      { "role": "user", "content": "Give me three tips for reviewing a Python pull request." }
    ],
    "stream": false
  }'

Passa direttamente l'id del modello — non servono suffissi di routing né prefissi identificativi del fornitore. In caso di successo, la chiamata restituisce un oggetto standard di completamento chat:

{
  "id": "msg_...",
  "object": "chat.completion",
  "model": "claude-opus-5-5",
  "choices": [
    {
      "index": 0,
      "message": { "role": "assistant", "content": "1. ..." },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 13,
    "completion_tokens": 42,
    "total_tokens": 55,
    "usage_semantic": "openai",
    "usage_source": "anthropic"
  }
}

Leggi la risposta da choices[0].message.content — qui non c'è alcun output[0].url da interrogare, né alcun id di task da tenere traccia.

Lo stesso flusso in Python

import requests

response = requests.post(
    "https://api.hiapi.ai/v1/chat/completions",
    headers={
        "Authorization": "Bearer sk-YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={
        "model": "claude-opus-5-5",
        "messages": [
            {"role": "user", "content": "Give me three tips for reviewing a Python pull request."}
        ],
        "stream": False,
    },
)
response.raise_for_status()
data = response.json()
print(data["choices"][0]["message"]["content"])

Poiché l'endpoint utilizza il formato di trasporto di OpenAI Chat Completions, la stessa struttura del corpo della richiesta può essere riutilizzata così com'è in qualsiasi client HTTP di qualsiasi linguaggio — oltre all'URL di base e alla chiave Bearer, non c'è nulla di specifico di hiapi da imparare.

Intensità di ragionamento, thinking e output in streaming

Il pensiero esteso di Claude Opus 5.5 è sempre attivo — non puoi disabilitarlo, né specificare manualmente un budget di token. Ciò che puoi controllare è quanto il modello ragiona, tramite output_config.effort:

{
  "model": "claude-opus-5-5",
  "messages": [{ "role": "user", "content": "..." }],
  "output_config": { "effort": "medium" }
}

effort accetta low, medium (il valore predefinito quando il campo è omesso), high, xhigh o max — passando gradualmente da risposte rapide/economiche a risposte approfondite e ponderate. Il message nella risposta contiene un array reasoning_details che conserva la traccia del pensiero interno del modello; per semplici chiamate una tantum puoi tranquillamente ignorarlo e leggere solo message.content.

Per risposte lunghe, imposta "stream": true per ottenere l'output incrementale anziché attendere la risposta completa:

curl -N https://api.hiapi.ai/v1/chat/completions \
  -H "Authorization: Bearer sk-YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"claude-opus-5-5","messages":[{"role":"user","content":"..."}],"stream":true}'

Ogni blocco di dati è una riga data: {...} nel formato chat.completion.chunk, con il testo incrementale in choices[0].delta.content. Continua a leggere i blocchi finché non ne ricevi uno con finish_reason non vuoto (di solito "stop") — quello è la fine della risposta.

Claude Opus 5.5 supporta anche le chiamate a strumenti/funzioni, con una finestra di contesto di 1 milione di token e un output massimo di 128.000 token, quindi è adatto a codebase di grandi dimensioni o attività su documenti lunghi, non solo a brevi domande e risposte.

Considerazioni per la produzione

• Gli errori di autenticazione restituiscono 401, non 400. Quando la chiave è mancante o non valida viene restituito:

  { "error": { "code": "permission_denied", "message": "This API key is invalid...", "type": "hiapi_error", "request_id": "..." } }
  

  Controlla specificamente l'HTTP 401 e, se devi contattare il supporto, fornisci il request_id — per altre cause di questo errore, consulta la guida completa alla risoluzione dei problemi di chiave API non valida.

• Qui non c'è alcuna opzione callback/Webhook. Quel pattern si applica ai modelli hiapi basati su attività asincrone (immagini, video, audio); Chat Completions supporta solo richiesta/risposta, quindi stream: true è la tua unica alternativa alla singola chiamata bloccante.

• Questa chiamata è naturalmente idempotente — nessun id di task viene creato accidentalmente più volte, quindi i tentativi in caso di timeout sono sicuri purché tu possa accettare di rieseguire lo stesso prompt.

• Attenzione ai limiti di frequenza, soprattutto con carichi di lavoro ad alta concorrenza; per le strategie di backoff, consulta come gestire gli errori di limite di frequenza 429.

• Il prezzo dei token (token di input, output e cache fatturati separatamente) viene aggiornato costantemente sulla pagina del modello Claude Opus 5.5 e sulla pagina dei prezzi — non codificare valori numerici nella tua logica di fatturazione, leggili da queste pagine.

Letture consigliate

• Pagina del modello Claude Opus 5.5 — specifiche complete e prezzi in tempo reale
• Guida all'API Claude Sonnet 4.6 — un'opzione Claude più leggera e veloce con lo stesso formato Chat Completions
• Costruire un proxy compatibile con OpenAI in Python — utile se devi intermediare più modelli di chat dietro un'unica API interna
• Gestisci le tue chiavi API

Domande frequenti

L'API Claude Opus 5.5 supporta l'output in streaming? Sì — imposta "stream": true e leggi i blocchi data: {...} come descritto sopra.

È necessaria una chiave API per richiamare Claude Opus 5.5 in produzione? Sì. Ogni richiesta deve includere Authorization: Bearer sk-<your key>; l'API di produzione non offre accesso senza chiave o anonimo.

Posso disattivare il thinking di Claude Opus 5.5 per risparmiare token? No. Il thinking di questo modello è sempre attivo; l'unica cosa che puoi controllare è il livello di output_config.effort (da low a max), che bilancia velocità/costo e profondità.

Claude Opus 5.5 viene richiamato tramite /v1/tasks come i modelli per immagini di hiapi? No. Solo i modelli hiapi per immagini, video e audio utilizzano il pattern di attività asincrone con polling. Claude Opus 5.5 è un modello testuale, utilizza /v1/chat/completions e restituisce la risposta nella stessa risposta.

Quali sono la finestra di contesto e la lunghezza massima dell'output? Contesto di 1 milione di token e output fino a 128.000 token — sufficienti per prompt su interi repository o documenti lunghi.

Claude Opus 5.5 supporta le chiamate a strumenti/funzioni? Sì, con supporto sia per l'output in streaming sia per il formato dei messaggi compatibile con OpenAI.