Guida API DeepSeek V4 Flash Vision Exp: limiti ed esempi

L'endpoint deepseek-v4-flash-vision-exp porta l'input di immagini nella linea V4 Flash. C'è però un dettaglio da non trascurare: è classificato come experimental. Le evidenze disponibili al lancio non bastano a dimostrarne l'affidabilità in produzione, quindi conviene partire con un progetto pilota monitorato e un fallback pronto prima di eleggerlo a soluzione predefinita.

Quale integrazione scegliere in pochi secondi

DeepSeek V4 Flash Vision Exp è adatto a chi usa già V4 Flash e deve ora analizzare screenshot, grafici, documenti o altre immagini tramite un'interfaccia compatibile con l'API. Per decisioni visive legate all'identità o particolarmente sensibili, mantieni un fallback e valuta separatamente il caso d'uso.

La stringa esatta del modello è deepseek-v4-flash-vision-exp. DeepSeek lo indica come sperimentale e, nel suo change log ufficiale, ne dichiara la disponibilità sulla piattaforma API dal 21 agosto 2026. La nota di rilascio riporta parità con V4 Flash nelle funzionalità solo testuali e un netto miglioramento nei benchmark per agent che richiedono comprensione visiva.

Inviare un'immagine con Chat Completions

Nelle Chat Completions compatibili con OpenAI, testo e immagine vanno inseriti in un array content dentro un messaggio user. La guida Vision ufficiale descrive il comportamento specifico del modello: inviare un'immagine al normale deepseek-v4-flash restituisce un errore 400.

import base64
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["DEEPSEEK_API_KEY"],
    base_url="https://api.deepseek.com",
)

with open("chart.png", "rb") as image_file:
    encoded = base64.b64encode(image_file.read()).decode("utf-8")

response = client.chat.completions.create(
    model="deepseek-v4-flash-vision-exp",
    messages=[
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "Extract the three trends from this chart."},
                {
                    "type": "image_url",
                    "image_url": {
                        "url": f"data:image/png;base64,{encoded}",
                        "detail": "original",
                    },
                },
            ],
        }
    ],
)

print(response.choices[0].message.content)

Le immagini sono supportate nei messaggi utente delle Chat Completions. Inserisci istruzione e immagine nello stesso array di contenuto, così il modello riceve insieme il contesto visivo e il compito da svolgere.

Come inviare le immagini: Base64, URL o Files API

Base64 per piccoli file locali

Base64 è la strada più semplice per un'immagine locale da usare una sola volta. Evita di doverla ospitare pubblicamente, ma i dati codificati rientrano nel limite di 48 MiB del corpo della richiesta e l'immagine sorgente non può superare 32 MiB.

Usalo per upload estemporanei da utenti o worker, non per immagini da riutilizzare nell'ambito di un batch.

URL pubblici per asset già ospitati

Gli URL pubblici http o https mantengono leggere le richieste, ma devono essere raggiungibili, lunghi al massimo 8.192 caratteri, scaricabili entro 60 secondi e puntare a file non superiori a 32 MiB. URL privati, scaduti o accessibili solo internamente possono fallire prima che DeepSeek riesca a recuperare l'immagine.

Files API per riuso e file più grandi

Carica l'immagine tramite la Files API, quindi usa l'ID restituito nella richiesta vision:

{
  "type": "file",
  "file_id": "file-api-xxxxxxxxxxxxxxxx"
}

Ogni file referenziato può arrivare a 64 MiB per immagine ed evita di inviare gli stessi byte a ogni richiesta. In cambio devi gestire un upload aggiuntivo e il ciclo di vita del file: conserva l'ID restituito insieme alla chiave che l'ha creato, senza trattarlo come un link pubblico da condividere.

La Files API è la scelta pratica quando un file supera 32 MiB, la richiesta rischia di oltrepassare 48 MiB oppure più passaggi di un agent devono esaminare la stessa immagine.

Regolare il dettaglio visivo prima di incidere sui costi

Il campo detail è disponibile per gli input image_url e per le parti immagine della Responses API; il comportamento riportato qui segue la guida Vision ufficiale di DeepSeek.

DeepSeek ridimensiona le immagini prima dell'inferenza. La guida Vision indica un limite massimo di 384 image token per ogni immagine, conteggiata in modo indipendente. Un'immagine sorgente molto grande non consuma quindi necessariamente un numero proporzionalmente più alto di image token dopo il ridimensionamento, anche se file voluminosi possono comunque superare i limiti di upload e dimensione della richiesta.

La pagina ufficiale Models & Pricing riporta per deepseek-v4-flash-vision-exp gli stessi prezzi a token di V4 Flash: $0.007 per 1M token di input in cache e $0.22 per 1M token di input non presenti in cache nelle ore non di punta; nelle fasce di punta le tariffe sono $0.014 e $0.44. L'output costa $0.66 nelle ore non di punta e $1.32 nelle fasce di punta. Gli image token sono fatturati come token di input, quindi numero di immagini e impostazione del dettaglio vanno inclusi nella stima dei costi.

I limiti che generano davvero errori API

Ci sono due restrizioni che si dimenticano facilmente. Solo deepseek-v4-flash-vision-exp accetta immagini e, nelle Chat Completions, i blocchi immagine nei messaggi system o assistant non funzionano. Se un'immagine viene inviata a un modello non vision, DeepSeek documenta il messaggio di errore 400 come This model does not support image.

Lo stesso modello, tre interfacce API

DeepSeek documenta il modello su tre interfacce nella sua guida Vision:

Tutte e tre supportano Base64, URL pubblici e riferimenti della Files API, ma i tipi di contenuto cambiano. Non copiare senza modifiche il blocco delle Chat Completions nella Responses API.

Cosa dimostrano i dati di lancio — e cosa no

Nel change log del 21 agosto, DeepSeek riporta benchmark di lancio solidi, fra cui Terminal Bench 2.1 a 83.9 e Chartography a 64.3 con p0.95. Sono risultati dichiarati dal fornitore, non riproduzioni indipendenti; la nota segnala inoltre che V4 Flash solo testuale ignora gli elementi multimodali in due valutazioni visive.

I risultati dei benchmark di lancio sono dichiarati dal fornitore: prima di instradare traffico di produzione, verifica quindi le attività visive rilevanti per la tua applicazione.

È pronto per la produzione?

Usa DeepSeek V4 Flash Vision Exp in un pilota controllato se il tuo carico di lavoro riguarda analisi di screenshot, estrazione da grafici, triage di documenti o un agent che deve ispezionare uno stato visivo. I prezzi allineati a Flash e le tre modalità di input rendono la valutazione economica, mentre il tetto di 384 token per immagine offre un punto di partenza concreto per modellare i costi.

Finché il modello resta sperimentale e le evidenze di lancio citate non ne dimostrano l'affidabilità per questi casi, non renderlo l'unico backend per verifica dell'identità, decisioni di sicurezza, interpretazione medica o altri giudizi visivi ad alta conseguenza. Predisponi un fallback dietro la stessa interfaccia e registra fonte dell'immagine, impostazione detail, utilizzo di input e output, latenza, tentativi ripetuti e successo del task.

Prima di instradare traffico di produzione, prova almeno:

1. Testo piccolo negli screenshot con dettaglio low e original.
2. Grafici con etichette, legende e assi fitti.
3. Più immagini nella stessa richiesta.
4. URL di immagini private e lente.
5. Tool call successive a un'ispezione visiva.
6. Prompt di identità errati o ambigui.
7. Comportamento del fallback dopo un errore 400, un timeout o una risposta relativa a un'immagine malformata.

FAQ sull'API DeepSeek V4 Flash Vision Exp

Qual è il nome esatto del modello?

Usa deepseek-v4-flash-vision-exp. Il change log DeepSeek del 21 agosto 2026 lo identifica come modello multimodale sperimentale sulla piattaforma API.

Ha gli stessi prezzi di V4 Flash?

Sì. La pagina dei prezzi di DeepSeek indica per Vision Exp e V4 Flash le stesse tariffe per token cache hit, cache miss e output. Gli image token vengono fatturati come token di input, fino a 384 image token per immagine dopo il ridimensionamento.

Può generare immagini?

La guida Vision ufficiale documenta la comprensione delle immagini, non la loro generazione. Considera questo endpoint dedicato esclusivamente alla comprensione, salvo la pubblicazione da parte di DeepSeek di un supporto separato per la generazione.

Perché la mia richiesta restituisce un errore 400?

Controlla la stringa del modello, il ruolo del messaggio, il tipo di blocco contenuto, la dimensione del file e il formato dell'immagine. Immagini inviate a un modello non vision oppure inserite in ruoli messaggio non supportati possono attivare l'errore documentato This model does not support image.