Guida alla configurazione di ricerca web e caricamento file con le API di DeepSeek

Dal 13 novembre 2026, le funzioni dell'app DeepSeek sono accessibili tramite parametri API. La ricerca integrata viene gestita dal modello e fatturata per query con risultati; Search/Fetch separati sono controllati dal codice e fatturati per richiesta completata con successo; il caricamento dei file passa invece da una Files API dedicata e dal relativo file_id.

Una richiesta con thinking attivo può arrivare a circa 20 chiamate agli strumenti, conteggiate come query e fetch. In questa guida vediamo come attivare le funzioni, come gestire i file, come calcolare i costi per attività e quale approccio conviene scegliere.

Cosa abilita il rilascio del 13 novembre nelle DeepSeek App API

L'annuncio di DeepSeek, The full DeepSeek App experience, now via API, porta nella API la ricerca web, l'input da file e la lettura degli URL per il modello deepseek-flash (DeepSeek-V4.1-Flash).

Le stesse funzioni sono disponibili attraverso tre interfacce: Messages API, Responses API e Chat Completions API, come spiega la guida Build a Chatbot. Le chiamate agli strumenti e la composizione del contesto avvengono lato server: il client deve limitarsi a visualizzare i blocchi strutturati e a rimandarli indietro senza modificarli. Un demo open source per browser mostra il collegamento tra i vari componenti, ma DeepSeek lo definisce esplicitamente un esempio dimostrativo.

Attivare la ricerca web e la lettura degli URL

Nella richiesta, sull'istanza deepseek-flash, dichiarate questi due strumenti nell'array tools, come indicato nella guida Web Tools:

"tools": [{"type": "deepseek_web_search"}, {"type": "deepseek_read_url"}]

Con il thinking disattivato, deepseek_web_search si comporta come la ricerca nella chat: è il modello a decidere se cercare, una singola chiamata può contenere più query e la risposta include le citazioni. Attivando il thinking, lo stesso strumento diventa una ricerca più approfondita: open_page e find_in_page si alternano alla ricerca durante i passaggi di ragionamento, fino a circa 20 chiamate agli strumenti prima della risposta.

La guida Web Tools fissa quattro limiti da tenere presenti:

• Vengono considerati solo gli URL presenti nell'ultimo messaggio dell'utente, fino a un massimo di 10 URL distinti; sarà poi il modello a scegliere quali leggere.
• Non è possibile imporre uno strumento tramite tool_choice: indicarne uno restituisce HTTP 400, mentre "none" disattiva anche la lettura degli URL.
• Quando sono attivi gli strumenti web, il livello di sicurezza elevato o la generazione dei titoli, temperature, top_p e diversi campi di controllo degli strumenti vengono ignorati senza messaggi espliciti.
• Una risposta che ha usato gli strumenti web non può essere continuata: occorre inviare nuovamente la richiesta.

"A $0.75 per 1000 richieste, vorrei capire quante chiamate effettua in background un agente. Qualcuno ha calcolato il costo per una normale attività di ricerca?" — u/Glum-Guitar-5083 su r/DeepSeek

Il metodo di fatturazione cambia a seconda del percorso. La ricerca web integrata addebita ogni query che restituisce risultati: tre query nella stessa chiamata valgono quindi come tre query. Il fetch integrato viene addebitato per ogni pagina recuperata, comprese quelle che in seguito vengono sostituite da url_not_allowed o unavailable durante il controllo di sicurezza; i link che non possono essere recuperati non vengono invece fatturati. Le API Search/Fetch separate addebitano solo le richieste HTTP 200 con risultati non vuoti o contenuti restituiti. In entrambi i casi, ricerche fallite o senza risultati non comportano costi.

Caricare file senza scrivere un parser

La Files API permette di caricare un file una sola volta e richiamarlo in seguito tramite file_id. Il flusso minimo è questo:

curl https://api.deepseek.com/files \
  -H "Authorization: Bearer $DEEPSEEK_API_KEY" \
  -F purpose="rich_layout_recognition" \
  -F file="@report.pdf"
# -> {"id": "file-api-xxxxxxxxxxxxxxxx", ...}

# then reference it in chat (Chat Completions shape):
# {"model": "deepseek-flash", "messages": [{"role": "user",
#   "content": [{"type": "text", "text": "Compare this with today's numbers"},
#   {"type": "file", "file_id": "file-api-xxxxxxxxxxxxxxxx"}]}]}

Il campo purpose determina l'elaborazione e, per i documenti, deve essere inviato prima del campo file. user_data accetta immagini (JPEG, PNG, GIF, WebP), testo semplice, fogli di calcolo ed ebook; text_recognition estrae solo testo da PDF, Word, PowerPoint e immagini; rich_layout_recognition restituisce testo e figure, mantenendo anche le informazioni su tabelle e colonne. Caricare un PDF come user_data restituisce HTTP 400. Inoltre, i documenti elaborati non possono essere riutilizzati come immagini né scaricati in seguito.

I file appartengono all'account, non alla chiave API, e lo stesso ID funziona sia nelle famiglie compatibili con OpenAI sia in quelle compatibili con Anthropic; per queste ultime serve l'header anthropic-beta: files-api-2025-04-14. L'elaborazione avviene durante l'upload, quindi il file_id viene restituito solo al termine di un caricamento riuscito.

Strumenti integrati o Search e Fetch separati?

Scegliete gli strumenti integrati quando volete che sia il modello a decidere se cercare o leggere una pagina all'interno di una conversazione. Le API separate convengono invece quando il flusso è deciso dal codice: la guida Search & Fetch usa POST https://api.deepseek.com/v1/tools/search per trovare risultati ordinati per rilevanza (fino a 50 risultati, rerank_score da 0 a 3, con qualità elevata da 1.5 in su, e authority da 0 a 4) e POST https://api.deepseek.com/v1/tools/fetch per convertire un singolo URL in Markdown. La ricerca separata non supporta ancora la ricerca di immagini, mentre i web tools sì.

I limiti di velocità sono indipendenti e applicati a livello di account: 100 QPS per Search, 25 QPS per Fetch, oltre a un limite Fetch per dominio. Superata la quota arriva HTTP 429. Ritentate le richieste 408, 429 e 5xx; per gli altri errori 4xx è necessario correggere la richiesta. Nella Search separata funzionano gli operatori site:, -site:, "exact phrase", lang:, after:/before:.

Quanto costa davvero

I costi degli strumenti si sommano a quelli dei token: Search e Fetch costano $0.75 ogni 1.000 richieste completate con successo ciascuno; OCR, ASR e TTS hanno prezzi separati, con promozioni a tempo limitato descritte nell'annuncio. Modificare count cambia il numero di risultati, ma non il prezzo.

Le verifiche sui prezzi condivise dalla community collocano la ricerca di DeepSeek intorno a $0.75 ogni 1.000 richieste, contro circa $10 ogni 1.000 per la ricerca di OpenAI e Claude secondo quanto riportato dagli sviluppatori (@berryxia): una differenza di circa 13 volte limitandosi ai costi degli strumenti.

Una risposta con una sola query costa meno di un decimo di centesimo in strumenti. Un'esecuzione con thinking attivo che effettua 8 query e apre 6 pagine addebita circa 8 ricerche più 6 fetch, restando sotto i due centesimi prima del costo dei token. Il rischio è il volume: un agente che ripete decine di ricerche moltiplica rapidamente le unità da $0.75. Fate il budget in base alle chiamate completate con successo, fissate un limite alla profondità della ricerca e registrate tool_search e tool_fetch nell'oggetto usage finale; web_search_requests è solo informativo e non rappresenta il conteggio fatturato.

Checklist per la messa in produzione: citazioni, sicurezza e demo

Le citazioni arrivano come blocchi web_search_result_location con URL, titolo e testo citato, come spiega la guida Web Tools. Nei flussi streaming vengono inviate come eventi citations_delta, al massimo un URL per blocco di testo, e vengono ignorate se riproposte nelle richieste successive. Conservate senza modifiche i campi signature e i blocchi degli strumenti tra un turno e l'altro: le pagine lette vengono ripristinate dalla signature. Una signature non valida o assente non impedisce comunque l'esecuzione, ma fa perdere la pagina. Nell'esempio di traccia della guida per chatbot, il contesto passa da 40 token di input a 9.078 dopo l'uso degli strumenti, di cui 4.096 serviti dalla cache: progettate quindi il contesto tenendo conto della crescita dovuta alle ricerche.

Per le app pubbliche, DeepSeek richiede il controllo di sicurezza e lascia allo sviluppatore moderazione, registrazione del modello ed etichettatura dei contenuti generati dall'AI. Considerate la revisione integrata solo come un primo filtro, gestite esplicitamente i motivi di arresto refusal e prevedete il caso url_not_allowed quando una pagina non supera la revisione. Quei fetch bloccati vengono comunque fatturati. Il demo della chat mostra il collegamento tra i componenti, ma mantiene tutto nel browser: prima della produzione dovrete quindi usare un backend vostro.

Domande frequenti

Posso obbligare il modello a cercare a ogni richiesta?

No. È il modello a decidere quando attivare gli strumenti; indicare uno strumento web in tool_choice restituisce 400.

Quale modello e quali endpoint supportano ricerca web e caricamento file?

deepseek-flash nelle interfacce Messages, Responses e Chat Completions. I riferimenti ai file tramite file_id funzionano sia nelle famiglie compatibili con OpenAI sia in quelle compatibili con Anthropic.

È possibile combinare file caricati e ricerca web?

Sì. È il flusso documentato per i chatbot: contesto proveniente dal file, ricerca lato server e citazioni.

Quante ricerche attiva normalmente un'attività di un agente?

Per una risposta semplice basta una chiamata con poche query; una ricerca con thinking attivo può arrivare a circa 20 chiamate agli strumenti. Misurate tool_search e tool_fetch per ogni attività: gli strumenti integrati fatturano per query o pagina, mentre le API separate fatturano per richiesta completata con successo, in entrambi i casi a $0.75 ogni 1.000.

Per iniziare, provate una richiesta di ricerca integrata e un caricamento file nel demo. Leggete poi i contatori tool_search e tool_fetch dell'oggetto usage finale e solo a quel punto valutate se il costo degli strumenti per attività sia più conveniente rispetto alla gestione di un vostro livello Tavily o SearXNG.