Come usare DeepSeek V4 Flash tramite l'API hiapi: curl, Python ed esempi di richiesta eseguibili

DeepSeek V4 Flash è un modello di chat con ragionamento e su hiapi si integra in modo diverso dalla maggior parte dei modelli della piattaforma: non utilizza la coda asincrona POST /v1/tasks usata per la generazione di immagini e video, bensì un endpoint di chat completion compatibile con OpenAI — POST /v1/chat/completions, con supporto sincrono o in streaming, senza bisogno di polling. Questo tutorial ti guiderà nell'invio di una richiesta eseguibile con curl e Python, per poi illustrare due problemi che in produzione causano davvero spesso intoppi.

Cosa costruirai

Uno script minimo che invia un prompt a deepseek-v4-flash tramite hiapi e stampa la risposta del modello — oltre ai pattern che ti serviranno quando questo script diventerà un'integrazione reale: gestione del budget di token di ragionamento del modello, streaming, retry e la struttura degli errori descritta nella documentazione.

Prerequisiti: una chiave API hiapi. Ottienila dalla dashboard di hiapi — ogni richiesta riportata di seguito si autentica tramite Authorization: Bearer sk-<your-key>.

Esempio minimo eseguibile

curl

curl https://api.hiapi.ai/v1/chat/completions \
  -H "Authorization: Bearer $HIAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-v4-flash",
    "messages": [{"role": "user", "content": "Explain what a hash table is in two sentences."}],
    "max_tokens": 500
  }'

Una chiamata riuscita restituisce un oggetto chat completion standard:

{
  "id": "gen-...",
  "object": "chat.completion",
  "model": "deepseek/deepseek-v4-flash",
  "provider": "DeepInfra",
  "choices": [{
    "index": 0,
    "finish_reason": "stop",
    "message": {"role": "assistant", "content": "A hash table is ...", "reasoning": "..."}
  }],
  "usage": {
    "prompt_tokens": 14, "completion_tokens": 187, "total_tokens": 201,
    "completion_tokens_details": {"reasoning_tokens": 96}
  }
}

Ci sono due cose da notare: nella richiesta si usa l'ID del modello nudo deepseek-v4-flash — hiapi lo risolve internamente verso il provider upstream, mentre il campo model nella risposta restituisce un ID qualificato dal provider (deepseek/deepseek-v4-flash), da considerare come informazione di riferimento e non da reinviare come parametro della richiesta. Inoltre, il messaggio contiene, oltre a content, anche un campo reasoning — si tratta di un modello di ragionamento, e usage.completion_tokens_details.reasoning_tokens ti dice quanta parte della spesa di completion_tokens è stata impiegata per questa catena di pensiero e quanta per la risposta visibile.

Python

import os
import requests

resp = requests.post(
    "https://api.hiapi.ai/v1/chat/completions",
    headers={"Authorization": f"Bearer {os.environ['HIAPI_KEY']}"},
    json={
        "model": "deepseek-v4-flash",
        "messages": [{"role": "user", "content": "Explain what a hash table is in two sentences."}],
        "max_tokens": 500,
    },
    timeout=60,
)
resp.raise_for_status()
data = resp.json()
print(data["choices"][0]["message"]["content"])

Poiché l'endpoint è compatibile con OpenAI, questo codice funziona senza modifiche anche con l'SDK Python ufficiale openai — basta impostare base_url su https://api.hiapi.ai/v1 e passare la chiave hiapi come api_key.

Pattern d'uso in produzione

La trappola del budget di ragionamento: non impostare max_tokens troppo basso

max_tokens limita il costo complessivo di ragionamento più risposta, non solo la risposta visibile. Se il modello sta ancora ragionando quando raggiunge il limite, riceverai una risposta con finish_reason: "length" e content: null — token consumati e fatturati, ma nessun contenuto da mostrare. Per qualsiasi prompt non banale, lascia un vero margine alla richiesta (almeno qualche centinaio di token), invece di ridurre max_tokens alla quantità che ritieni necessaria per la risposta.

Disattivare il ragionamento per attività semplici e deterministiche

Se l'attività non richiede una catena di pensiero — classificazione, query brevi, conversione di formato — puoi sopprimere del tutto il ragionamento:

{
  "model": "deepseek-v4-flash",
  "messages": [{"role": "user", "content": "Say OK and nothing else."}],
  "max_tokens": 50,
  "reasoning": {"enabled": false}
}

Con reasoning.enabled: false, nella risposta message.reasoning restituisce null e completion_tokens_details.reasoning_tokens è 0 — paghi solo per l'output visibile e la latenza si riduce di conseguenza. Mantieni il comportamento predefinito (ragionamento attivo) solo per le attività in cui un pensiero aggiuntivo migliora davvero la risposta.

Streaming

Imposta "stream": true per ottenere eventi server-sent in stile OpenAI standard, senza attendere la risposta completa:

curl https://api.hiapi.ai/v1/chat/completions \
  -H "Authorization: Bearer $HIAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"deepseek-v4-flash","messages":[{"role":"user","content":"Count to 5."}],"stream":true}'

Ogni blocco di dati è una riga data: {...} che trasporta il choices[0].delta.content incrementale; l'ultimo blocco contiene usage e il flusso termina con la riga letterale data: [DONE]. Analizza i blocchi man mano che arrivano, invece di bufferizzare l'intera risposta lato client — è proprio questo il senso dell'uso dello streaming nelle UI di chat.

Idempotenza e retry

Qui le chat completion sono chiamate HTTP senza stato, non attività in coda — non c'è alcun ID attività da interrogare, né rischio di inviare accidentalmente contenuti duplicati in coda. I retry riguardano normali problemi HTTP: in caso di errori di trasporto o 5xx, riprova con una strategia di backoff; in caso di 429, rispetta l'header di risposta Retry-After prima di riprovare (vedi la documentazione sui limiti di frequenza). Non riprovare per errori 4xx che indicano una richiesta errata (ad esempio messages malformati) — correggi invece il corpo della richiesta.

Gestione degli errori

Una chiave non valida o mancante restituisce HTTP 401:

{
  "error": {
    "code": "permission_denied",
    "message": "...",
    "request_id": "...",
    "type": "hiapi_error"
  }
}

Nel gestore degli errori controlla error.code, invece di fare pattern matching sulla stringa del messaggio — permission_denied è l'identificatore stabile. Se ricevi questo errore con una chiave che ritieni valida, consulta la documentazione sull'autenticazione.

Letture correlate

• Documentazione sull'autenticazione hiapi — come funzionano l'header Authorization e gli scope delle chiavi su tutta la piattaforma.
• Documentazione sui limiti di frequenza hiapi — comportamento 429 e Retry-After.
• Pagina del modello deepseek-v4-flash — prezzi e capacità attuali.

FAQ

Devo interrogare i risultati come faccio con i modelli di immagini/video di hiapi? No. La generazione di immagini e video su hiapi passa per la coda asincrona /v1/tasks (creazione → polling o callback → download di output[0].url). I modelli di chat come deepseek-v4-flash sono semplici chiamate HTTP sincrone (o in streaming) a /v1/chat/completions — ottieni la risposta direttamente nella risposta.

Perché usage.completion_tokens sembra più alto di quanto dovrebbe costare la risposta visibile? Perché include i token di ragionamento. Controlla usage.completion_tokens_details.reasoning_tokens per vedere la suddivisione e usa "reasoning": {"enabled": false} quando non è necessario che il modello mostri il processo di pensiero.

La mia risposta ha "finish_reason": "length" e content vuoto — cosa è successo? Il modello ha esaurito max_tokens mentre era ancora nella fase di ragionamento, senza mai scrivere la risposta visibile. Aumenta max_tokens oppure disattiva il ragionamento per i prompt più semplici.

Posso usare l'SDK OpenAI ufficiale invece delle chiamate HTTP grezze? Sì — imposta base_url dell'SDK su https://api.hiapi.ai/v1 e api_key sulla tua chiave hiapi; la struttura di richiesta/risposta è identica.

Dove posso trovare i prezzi attuali del modello? Nella pagina del modello o nella pagina dei prezzi in tempo reale — il costo per token può variare leggermente in base al routing verso il provider upstream, quindi consultala lì invece di affidarti ai numeri riportati in questo articolo.