Come usare deepseek-v4-flash-vision-exp tramite l'API hiapi: curl, Python e una richiesta funzionante

deepseek-v4-flash-vision-exp è un modello testuale e visivo con capacità di ragionamento disponibile su hiapi, accessibile tramite l'endpoint standard compatibile con OpenAI: POST /v1/chat/completions. È in grado di leggere contemporaneamente immagini e testo, supporta la modalità JSON e le chiamate a funzioni/strumenti, e supporta l'output in streaming — tutto attraverso la stessa struttura di richiesta utilizzata con qualsiasi altro modello chat di hiapi. Questa guida ti accompagna attraverso una richiesta funzionante, un comportamento che può facilmente trarre in inganno (il modello ragiona prima di rispondere, e il processo di ragionamento consuma il tuo budget di token) e alcune pratiche di produzione che vale la pena conoscere prima di andare in produzione.

Cosa costruirai

Uno script che invia un prompt a deepseek-v4-flash-vision-exp — opzionalmente con un'immagine allegata — e legge la risposta effettiva, non solo la sua traccia di ragionamento interna.

Prerequisiti: una chiave API hiapi. Ottienila dalla console — ogni richiesta sottostante deve includerla nell'header Authorization.

Esempio minimo funzionante

curl

curl -s -X POST "https://api.hiapi.ai/v1/chat/completions" \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-v4-flash-vision-exp",
    "messages": [
      { "role": "user", "content": "Say OK and nothing else." }
    ],
    "max_tokens": 200
  }'

La risposta ridotta appare così:

{
  "choices": [
    {
      "finish_reason": "stop",
      "message": {
        "role": "assistant",
        "content": "OK",
        "reasoning_content": "We need to respond exactly \"OK\" and nothing else. ..."
      }
    }
  ],
  "usage": {
    "completion_tokens": 37,
    "completion_tokens_details": { "reasoning_tokens": 34 },
    "prompt_tokens": 89,
    "total_tokens": 126
  }
}

Qui due campi sono importanti: message.content è la risposta effettiva, mentre message.reasoning_content è la catena di pensiero interna del modello prima di determinare tale risposta. usage.completion_tokens_details.reasoning_tokens ti dice quanti token del budget max_tokens ha consumato il processo di ragionamento — in questo semplice esempio, 34 dei 37 token di completion sono stati usati per il ragionamento prima che il modello scrivesse "OK".

Ecco la trappola: impostando max_tokens troppo basso, il modello potrebbe spendere l'intero budget nel ragionamento, facendo sì che content sia null e finish_reason sia "length". La stessa richiesta con max_tokens: 10 restituisce content: null — il modello stava ancora pensando quando ha raggiunto il limite. Lascia spazio sufficiente a questo modello: almeno 150–300 token per risposte brevi, e di più per contenuti che richiedono una vera profondità di ragionamento.

Python

import requests

resp = requests.post(
    "https://api.hiapi.ai/v1/chat/completions",
    headers={
        "Authorization": "Bearer sk-your-api-key",
        "Content-Type": "application/json",
    },
    json={
        "model": "deepseek-v4-flash-vision-exp",
        "messages": [
            {"role": "user", "content": "Say OK and nothing else."},
        ],
        "max_tokens": 200,
    },
    timeout=60,
)
resp.raise_for_status()
message = resp.json()["choices"][0]["message"]
print(message["content"])

Input visivo

Puoi passare immagini accanto al testo impostando content come un array di segmenti tipizzati — image_url accetta qualsiasi URL di immagine accessibile pubblicamente:

curl -s -X POST "https://api.hiapi.ai/v1/chat/completions" \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-v4-flash-vision-exp",
    "messages": [
      {
        "role": "user",
        "content": [
          { "type": "text", "text": "What color is the dominant background color of this image? One word." },
          { "type": "image_url", "image_url": { "url": "https://example.com/photo.jpg" } }
        ]
      }
    ],
    "max_tokens": 200
  }'

Con un'immagine di test reale, il modello ha restituito "Beige", mentre reasoning_content mostrava che aveva prima percorso una descrizione visiva prima di dare la risposta di una parola — lo stesso schema di ragionamento prima della risposta delle richieste di solo testo, ma basato sull'immagine.

Modalità JSON e chiamata a strumenti

Output JSON strutturato — aggiungi response_format: {"type": "json_object"} e menziona JSON nel prompt:

{
  "model": "deepseek-v4-flash-vision-exp",
  "messages": [
    { "role": "user", "content": "Return a JSON object with keys name and age for a fictional person." }
  ],
  "response_format": { "type": "json_object" },
  "max_tokens": 300
}

message.content viene restituito come stringa JSON analizzabile ({"name": "Alex Doe", "age": 30}), mentre reasoning_content continua a contenere la bozza del modello — analizza solo content, mai reasoning_content.

Chiamata a funzioni/strumenti — passa un array tools standard in stile OpenAI:

{
  "model": "deepseek-v4-flash-vision-exp",
  "messages": [
    { "role": "user", "content": "What is the weather in Tokyo right now? Use the get_weather tool." }
  ],
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "get_weather",
        "description": "Get current weather for a city",
        "parameters": {
          "type": "object",
          "properties": { "city": { "type": "string" } },
          "required": ["city"]
        }
      }
    }
  ],
  "max_tokens": 300
}

Il modello risponde con finish_reason: "tool_calls" e un array tool_calls (contenente function.name, function.arguments come stringa JSON e call_id che rimandi nel turno successivo) — il ciclo standard di chiamata a funzioni di OpenAI funziona senza modifiche.

Considerazioni per la produzione

• Riserva un budget max_tokens per il ragionamento, non solo per la risposta. Questo è un modello di ragionamento — ogni risposta include un processo reasoning_content prima del content finale, ed entrambi consumano dallo stesso pool di max_tokens. Controlla usage.completion_tokens_details.reasoning_tokens durante i test iniziali, calibra un limite sicuro per i tuoi prompt e controlla sempre finish_reason — "length" con content null significa che sei stato troncato a metà del ragionamento, non che hai ottenuto una risposta reale.
• Lo streaming funziona tramite stream: true. A differenza di alcuni modelli di ragionamento su hiapi che forzano lo streaming, questo modello supporta entrambe le modalità. In modalità streaming, reasoning_content e content arrivano come campi delta separati sullo stesso flusso di chunk — se vuoi mostrare il "pensiero" e la "risposta" come stati UI distinti, bufferizzali separatamente.
• Gli errori di autenticazione restituiscono risposte esplicite. Una chiave errata o revocata restituisce HTTP 401, con un corpo di errore contenente "code": "permission_denied" e un request_id. Ramifica in base al campo code, non confrontando le stringhe dei messaggi, e includi il request_id quando contatti il supporto.
• Non mostrare reasoning_content all'utente finale come risposta. È una bozza non strutturata, non la risposta finale — soprattutto per la modalità JSON o le chiamate a strumenti, solo content (o tool_calls) è destinato al consumo automatico.
• L'input visivo accetta URL pubblici, non base64 inline. image_url.url deve essere raggiungibile dai server di hiapi; ospita l'immagine tu stesso o usa un URL che controlli prima di inviare la richiesta.

Letture correlate

• Pagina del modello deepseek-v4-flash-vision-exp — riferimento completo dei parametri e prezzi in tempo reale
• Documentazione API di hiapi — autenticazione, altre famiglie di modelli e elenco completo degli endpoint
• Prezzi di hiapi — tariffe per token di deepseek-v4-flash-vision-exp e di tutti gli altri modelli
• Guida all'API di gpt-6-astra — il secondo modello di ragionamento su hiapi, con una forma di integrazione diversa (solo streaming, Responses API), utile per un confronto

Domande frequenti

deepseek-v4-flash-vision-exp supporta l'input visivo? Sì. Invia un content sotto forma di array contenente un segmento text e uno o più segmenti image_url, ciascuno che punta a un URL di immagine accessibile pubblicamente. Il modello ragiona sull'immagine come sul testo prima di rispondere.

Perché message.content è null nella mia risposta? Il tuo max_tokens è troppo basso, il processo di ragionamento del modello ha esaurito l'intero budget prima di scrivere la risposta. Controlla finish_reason — "length" con content: null è questo il caso; aumenta max_tokens e riprova.

Supporta la modalità JSON? Sì, tramite response_format: {"type": "json_object"}. Il JSON viene inserito come stringa in message.content, da analizzare tu stesso; reasoning_content non fa parte dell'output strutturato e va ignorato in questo scenario.

Supporta le chiamate a funzioni/strumenti? Sì, utilizzando il formato standard dell'array tools di OpenAI. Una risposta che attiva uno strumento restituisce finish_reason: "tool_calls" e un array tool_calls contenente nome della funzione e argomenti.

Posso ricevere la risposta in streaming? Sì — imposta "stream": true e consuma gli eventi chat.completion.chunk. Sia content che reasoning_content vengono trasmessi in streaming come campi delta separati all'interno dello stesso chunk.

Come si presenta un errore di autenticazione? HTTP 401, con un corpo JSON che contiene "type": "hiapi_error", "code": "permission_denied", un message leggibile dall'uomo e un request_id da fornire al supporto (se il problema persiste).