Le DeepSeek API sono l’interfaccia con cui un’applicazione può interrogare i modelli DeepSeek attraverso una richiesta di rete. Un software invia istruzioni e dati, il servizio restituisce una risposta e l’applicazione decide come elaborarla. La documentazione offre formati compatibili con le API OpenAI e Anthropic (DeepSeek).
Nella guida a DeepSeek abbiamo presentato la piattaforma e i suoi modelli. Qui affronteremo invece l’integrazione: accesso, chiave API, prima richiesta, costo e controlli da prevedere prima di inserire l’output in un processo aziendale.
Dopotutto, una prima chiamata riuscita può verificare un collegamento tecnico, ma per capire se l’integrazione sia utile occorre osservarne il lavoro: quale attività semplifica, quali errori introduce e quanto tempo richiede la revisione. E il costo per token è solo una parte di questa valutazione.
Che cosa cambia usando le API DeepSeek
Con le API DeepSeek, la richiesta può essere preparata da un software invece che digitata ogni volta da una persona. Il programma può inviare un testo da classificare, ricevere una categoria e proporla all’operatore che gestisce il lavoro.
Un esempio è la preparazione di una bozza di risposta a una richiesta di assistenza. Il sistema raccoglie il messaggio, seleziona le informazioni autorizzate e chiede al modello un risultato in un formato definito. La bozza viene poi sottoposta alla persona incaricata della verifica.
Per noi però, questo passaggio va progettato insieme alla destinazione dell’output. Un suggerimento interno e un messaggio inviato al cliente hanno conseguenze diverse. L’integrazione deve sapere quando può proseguire, quando chiedere una verifica e quando fermarsi.
DeepSeek API key: che cosa serve prima della chiamata
Una DeepSeek API key è la credenziale usata dal software per autenticare la richiesta. La documentazione ufficiale rimanda alla piattaforma DeepSeek per ottenerla. Bisogna inoltre verificare il saldo disponibile e le condizioni applicabili al proprio account: l’accesso al chatbot non implica l’uso gratuito delle API (DeepSeek).
Prima della prova prepariamo un ambiente di sviluppo, una chiave autorizzata e un piccolo testo senza dati personali o informazioni riservate. L’esempio di questa guida usa una situazione inventata, e serve a comprendere la forma della richiesta.
La chiave va conservata in un ambiente controllato. Nel codice dimostrativo la leggiamo da una variabile d’ambiente, senza inserirla nel file. In un progetto pubblico, il browser dovrebbe chiamare il nostro server, che gestisce l’accesso al servizio: pubblicare la credenziale nel JavaScript consegnato agli utenti la renderebbe recuperabile.
La gestione delle credenziali richiede anche un responsabile. Occorre sapere chi può crearle, dove vengono usate e come revocarle. Queste informazioni diventano utili quando un fornitore cambia, un collaboratore lascia il progetto o viene rilevato un uso anomalo.
Quali modelli usare nelle DeepSeek API
Gli identificativi DeepSeek API vanno copiati dalla documentazione corrente. Al 16 ottobre 2026, la guida alla prima chiamata indica deepseek-flash e deepseek-v4-pro. Il primo corrisponde al servizio Flash attuale; la documentazione descrive anche la gestione di alcuni vecchi nomi del modello (DeepSeek).
Dall’identificativo della richiesta alla versione del listino
DeepSeek V4.1 Flash
DeepSeek V4 Pro 0813
Il nome scritto nella richiesta non coincide con quello del listino: prima di approvare una stima conviene verificare a quale versione corrisponde ogni identificativo.
Il nome utilizzato in una guida di mesi fa potrebbe rimandare a un servizio diverso o essere superato. In un’integrazione conviene conservare il modello in una configurazione modificabile e registrare quale identificativo sia stato usato nelle prove.
Per un confronto fra modelli prepariamo gli stessi dati e lo stesso risultato atteso. Se cambiano insieme prompt, versione e materiali, diventa difficile capire quale modifica abbia prodotto un miglioramento. Un passaggio a un nuovo modello deve quindi includere una nuova verifica del processo.
Come fare una prima chiamata alle DeepSeek API
Per usare DeepSeek API nell’esempio adottiamo il formato Chat Completions. L’endpoint è https://api.deepseek.com/chat/completions; la richiesta include l’autorizzazione e un corpo JSON. La variabile DEEPSEEK_API_KEY deve essere configurata nel proprio ambiente con una credenziale valida (DeepSeek).
curl –fail-with-body –max-time 30
https://api.deepseek.com/chat/completions
-H “Content-Type: application/json”
-H “Authorization: Bearer ${DEEPSEEK_API_KEY}”
-d ‘{
“model”: “deepseek-flash”,
“messages”: [
{
“role”: “system”,
“content”: “Scrivi una bozza fedele ai dati forniti.”
},
{
“role”: “user”,
“content”: “Riassumi: prototipo approvato; consegna venerdi.”
}
],
“thinking”: {“type”: “disabled”},
“max_tokens”: 400,
“stream”: false
}’
Il codice è un esempio dimostrativo controllato rispetto alla documentazione; non rappresenta una prova eseguita con una chiave reale. Richiede una versione di curl che supporti –fail-with-body. In caso di errore HTTP, questa opzione fa terminare il comando con un codice di errore mantenendo disponibile il corpo della risposta (curl project).
Nel corpo della richiesta, model identifica il servizio e messages contiene istruzioni e testo. stream: false richiede una risposta completa. max_tokens limita la generazione; per questo compito breve disattiviamo esplicitamente la modalità di ragionamento attraverso thinking (DeepSeek).
Il risultato testuale si trova nella prima scelta, nel campo message.content. Prima di usarlo controlliamo anche finish_reason: un’interruzione per limite di token può lasciare il contenuto incompleto. Il campo usage permette di osservare il consumo della richiesta (DeepSeek).
Un timeout lato client limita l’attesa dell’applicazione, ma non dimostra che il servizio abbia interrotto ogni elaborazione. Per un’integrazione reale bisogna gestire anche la possibilità di ricevere un errore dopo che una richiesta è stata presa in carico.
Come ottenere un risultato strutturato
Per un software è spesso utile ricevere un oggetto JSON da DeepSeek. La documentazione indica il parametro response_format con tipo json_object, insieme a un’istruzione che chieda esplicitamente JSON e mostri il formato desiderato (DeepSeek).
Nel nostro esempio possiamo chiedere di classificare una richiesta usando questi campi:
{
“categoria”: “assistenza”,
“priorita_proposta”: “da_verificare”,
“dati_mancanti”: [“numero ordine”]
}
L’oggetto mostra il formato atteso, non un risultato ottenuto dal servizio. Prima di inviarlo al processo successivo, l’applicazione deve verificare che i campi esistano, i valori appartengano alle categorie ammesse e il contenuto sia pertinente al testo originale.
La validità del JSON riguarda la struttura sintattica. Una categoria sbagliata o una priorità priva di riscontro possono trovarsi in un oggetto perfettamente leggibile dal software. La guida DeepSeek segnala inoltre che la modalità JSON può restituire contenuto vuoto: anche questo caso va gestito.
Nel primo progetto conviene mantenere un passaggio di conferma. L’operatore vede la richiesta e la classificazione proposta, la corregge se necessario e registra l’esito. Il confronto fra proposta e decisione approvata costruisce un campione utile per valutare l’integrazione.
DeepSeek API pricing: come leggere i costi
Il DeepSeek API pricing distingue token in ingresso, token in uscita e riuso della cache. Il listino attuale prevede anche fasce peak e off-peak. Le cifre della tabella sono in dollari per un milione di token e sono verificate al 12 ottobre 2026; per l’input mostriamo la tariffa senza riuso della cache (DeepSeek).
Il listino a fasce orarie
Prezzo per milione di token. Le due fasce raddoppiano il costo della stessa richiesta.
| Modello | Input off-peak |
Output off-peak |
Input peak |
Output peak |
|---|---|---|---|---|
| deepseek-flash | 0,15 USD | 0,60 USD | 0,30 USD | 1,20 USD |
| deepseek-v4-pro | 0,66 USD | 1,98 USD | 1,32 USD | 3,96 USD |
La fascia oraria va considerata nel budget quanto la scelta del modello: lo stesso lavoro, spostato fuori dalle ore di punta, dimezza il costo per token.
La fascia peak indicata dalla documentazione è dalle 01:00 alle 04:00 e dalle 06:00 alle 10:00 UTC, dal lunedì al venerdì, con le eccezioni previste per le festività cinesi. Per pianificare un consumo va considerato il fuso orario e ricontrollato il listino.
Proviamo un calcolo dimostrativo: 1.000 richieste da 2.000 token di input e 500 di output ciascuna. Con Flash, senza cache, il costo aritmetico sarebbe di 0,60 USD in off-peak e 1,20 USD in peak. Sono 2 milioni di token in ingresso e mezzo milione in uscita. La simulazione esclude ulteriori token di ragionamento, ripetizioni, servizi applicativi e altri costi; non è una previsione dei consumi reali.
Per leggere il costo di un progetto, possiamo dividere la spesa complessiva per il numero di risultati accettati. Se dieci richieste producono soltanto quattro output utilizzabili, il costo della singola chiamata nasconde una parte del problema. Devono entrare nel conto anche revisione, sviluppo e gestione.
Un’integrazione che costa poco per token può richiedere molte ore per essere mantenuta. Il budget deve prevedere chi interviene quando cambia un modello, il formato della risposta o una condizione del servizio.
Errori DeepSeek API: come preparare il processo
Gli errori DeepSeek API devono avere un esito leggibile anche per chi usa il prodotto. L’applicazione può conservare la bozza e informare l’operatore, evitando di sostituire una risposta mancante con un contenuto inventato.
I codici di errore e il controllo da predisporre
| Codice | Indicazione della documentazione | Controllo da predisporre |
|---|---|---|
| 400 o 422 | Formato o parametri non validi | Verificare corpo della richiesta e configurazione |
| 401 | Autenticazione fallita | Controllare credenziale e configurazione |
| 402 | Saldo insufficiente | Verificare il saldo e avvisare il responsabile |
| 429 | Richieste troppo frequenti | Ridurre il ritmo e applicare attese fra i tentativi |
| 500 o 503 | Errore del server o sovraccarico | Prevedere tentativi limitati e un percorso alternativo |
Ogni codice corrisponde a una decisione da prendere prima che l’errore si presenti: chi viene avvisato, quante volte si riprova, che cosa succede quando il servizio non risponde.
I significati dei codici provengono dalla documentazione ufficiale (DeepSeek). Le azioni vanno adattate al sistema. Una richiesta con credenziale errata richiede una correzione della configurazione; inviarla ripetutamente aggiunge traffico senza risolvere la causa.
I tentativi devono avere un limite. In particolare, se il risultato alimenta un invio, una registrazione o un altro effetto esterno, occorre evitare che una ripetizione produca due azioni. Possiamo assegnare al lavoro un identificativo e controllare nel nostro sistema se l’azione sia già stata eseguita.
API DeepSeek e uso dall’Italia
Per un progetto italiano, le API DeepSeek richiedono una verifica anche sul trattamento dei dati. Il 30 gennaio 2025 il Garante ha disposto nei confronti delle società DeepSeek la limitazione delle attività di trattamento dei dati personali di interessati che si trovano in Italia nell’ambito del servizio (Garante per la protezione dei dati personali).
Prima di un impiego aziendale bisogna verificare gli eventuali sviluppi del procedimento e le condizioni applicabili al servizio scelto. Una connessione tecnicamente funzionante non dimostra da sola che il trattamento progettato sia ammissibile. Un’implementazione locale di un modello e l’utilizzo del servizio API ospitato dal fornitore richiedono valutazioni distinte.
La policy aziendale sull’AI deve indicare quali informazioni possono essere inviate allo strumento autorizzato. L’esempio tecnico di questa guida usa dati inventati; per un progetto reale occorre coinvolgere chi gestisce privacy, sicurezza e autorizzazioni del processo.
Un caso aziendale: classificare senza inviare automaticamente
Una prima integrazione con le API DeepSeek può limitarsi a proporre una classificazione di messaggi. Usiamo inizialmente testi di prova, categorie esplicite e una destinazione interna. Il risultato rimane visibile a un operatore.
Immaginiamo tre categorie ordinarie, consegna, fatturazione e assistenza, più una voce «da verificare». Prepariamo un campione che comprenda messaggi ambigui, richieste incomplete e casi con più argomenti. Il sistema deve poter assegnare un caso alla verifica senza essere costretto a scegliere una delle tre categorie.
Per valutare il lavoro confrontiamo la proposta con la classificazione approvata dalle persone responsabili. Registriamo gli errori, il tempo di correzione e i casi che richiedono un intervento. Soltanto dopo queste prove possiamo decidere quali ulteriori passaggi automatizzare.
Il controllo umano dell’AI può essere progettato in questo punto: la persona vede il materiale originale, comprende la proposta e dispone del potere di correggerla o fermarla. Una conferma richiesta senza informazioni sufficienti rende il controllo meno efficace.
L’angolo Bliss
Decidere il processo prima di moltiplicare le richieste
Il valore delle DeepSeek API per un’impresa dipende dal lavoro che rendono possibile. Un progetto utile descrive l’attività, il risultato accettabile, i dati ammessi e il responsabile della verifica. Da questi elementi possiamo ricavare i requisiti tecnici e il budget.
La governance di investimenti, rischi e ROI nell’AI riguarda anche la decisione di procedere oltre il prototipo. Chi approva deve poter vedere risultati, correzioni e costo complessivo, insieme ai problemi ancora aperti.
Per noi un indicatore iniziale è il tempo necessario a ottenere un lavoro approvato. Se l’integrazione velocizza la generazione ma sposta molte correzioni sull’operatore, il beneficio va ricalcolato. Se invece riduce un’attività ripetitiva conservando i controlli richiesti, abbiamo una base concreta su cui ampliare il progetto.
La reputazione del brand entra nel processo quando l’output raggiunge clienti, partner o pubblico. In quel momento vanno verificati tono, promesse e condizioni, oltre al funzionamento della richiesta. Il collegamento API permette di produrre: il sistema di approvazione stabilisce che cosa può rappresentare l’azienda.
Il punto di vista di Bliss Agency
Domande frequenti
Le DeepSeek API sono gratuite?
Le API hanno un listino basato sul consumo di token. Eventuali crediti concessi all’account vanno verificati sulla piattaforma. L’accesso gratuito al chatbot e l’utilizzo delle API sono canali con condizioni distinte.
Dove si ottiene una DeepSeek API key?
La documentazione ufficiale rimanda alla piattaforma DeepSeek per creare la chiave. Dopo aver verificato accesso e condizioni applicabili, la credenziale va conservata nell’ambiente del server o dello sviluppo, evitando di pubblicarla nel codice distribuito agli utenti.
Posso usare un client compatibile con OpenAI?
La documentazione DeepSeek presenta un formato compatibile, con URL di base e credenziale propri. In una migrazione bisogna comunque verificare modelli, parametri, strumenti e forma delle risposte: la compatibilità del formato non garantisce l’equivalenza di ogni funzione.
Perché ricevo l’errore 402 dalle API DeepSeek?
Nella documentazione indica un saldo insufficiente. Verifica il saldo dell’account e le condizioni di fatturazione. In un prodotto aziendale, l’errore deve avvisare il responsabile e interrompere il lavoro in modo controllato.
Un risultato JSON può essere usato senza controlli?
Occorre validare formato e contenuto. La presenza di un JSON leggibile non dimostra che la classificazione o le informazioni siano corrette. Prima di attivare un’azione, controlla i campi, i valori ammessi e le condizioni di approvazione previste dal processo.