Costruire i tuoi strumenti IA con le API

Panoramica

Il piu grande cambiamento nella costruzione di software e questo: quando lo strumento di cui hai bisogno non esiste, lo costruisci lo stesso giorno. Le API di modelli ti lasciano chiamare un LLM dal tuo codice, con il tuo prompt, e - cruciale - recuperare dati strutturati invece di un muro di prosa. Appena un modello puo trasformare in modo affidabile un'immagine o un documento in un pulito record JSON, tutta una classe di lavoro di inserimento manuale sparisce. Questa lezione insegna la chiamata di API diretta, il trucco di output strutturato che rende la risposta utilizzabile, e due veri strumenti che il fondatore di questa School ha costruito da questi stessi pezzi.

Cosa imparerai

Imparerai a chiamare Gemini e Claude direttamente con una richiesta fetch minimale, a forzare il modello a restituire del JSON conforme a uno schema perche l'output cada direttamente in database, a usare la vision perche una foto diventi dati strutturati, e a riconoscere quando costruire un piccolo strumento interno batte pagare del SaaS. I due studi di caso da fondatore rendono cio concreto: foto di una fattura in entrata, record attribuito in uscita; foto di una carta da collezione in entrata, record catalogato in uscita.

Prerequisiti

I Corsi da 1 a 3. Hai bisogno della lezione di scelta di modello del Corso 1 (il costo dello strumento dipende interamente dal modello che chiami), della disciplina dei segreti del Corso 3 (la chiave API non tocca mai il codice client) e di un database dove scrivere - Convex del Corso 3 e perfetto. La pagina dei fondamenti su cos'e una API copre le basi della richiesta, se serve.

Il problema

Le aziende pagano ogni mese per strumenti SaaS che fanno una cosa ristretta - leggere ricevute, taggare immagini, estrarre campi da PDF - e che comunque non si attengono del tutto al loro workflow. Eppure lo stesso job e a una sola chiamata di API. Il blocco non e mai stato la capacita; e che le persone non realizzano quanto poco codice c'e tra "ho una foto di una fattura" e "la fattura e nel mio sistema contabile, attribuita al giusto progetto". Questa lezione toglie questo blocco mostrando tutto il cammino end-to-end.

Le API come blocchi di costruzione

Chiamare una API di modello direttamente ti da un controllo totale: il tuo prompt, il tuo modello, il tuo formato di output, nessuna UI nel cammino. E anche meno codice di quanto le persone si aspettino. Una richiesta e un POST con la tua chiave API in un header e un body JSON che descrive cio che vuoi. Ecco una chiamata minimale verso Gemini e la stessa idea contro Claude, perche tu veda entrambe. Google offre una quota Gemini gratuita davvero generosa tramite AI Studio, il che ne fa il posto naturale per prototipare strumenti vision senza spendere niente.

// Chiamata Gemini minimale. La chiave vive in una env var, mai nel codice client.
const res = await fetch(
  'https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash:generateContent',
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'x-goog-api-key': process.env.GEMINI_API_KEY!,
    },
    body: JSON.stringify({
      contents: [{ parts: [{ text: 'Summarise this in one sentence: ...' }] }],
    }),
  },
)
const data = await res.json()
console.log(data.candidates[0].content.parts[0].text)

Claude funziona allo stesso modo: un POST verso l'endpoint Messages di Anthropic con la tua chiave in un header x-api-key e un array messages nel body. Il fornitore differisce, la forma e la stessa. Scegli il modello con la regola di scelta di modello del Corso 1 - un modello rapido ed economico per l'estrazione ad alto volume, uno piu potente solo quando il ragionamento e davvero duro.

Output strutturato: il trucco che lo rende utile

Un modello che risponde in prosa non e uno strumento - non puoi mettere un paragrafo in una colonna di database. Il trucco e chiedere un output strutturato: dai al modello uno schema JSON ed esigi che restituisca dati conformi esattamente a quello schema. Le API moderne lo supportano direttamente (un response schema o una modalita structured output), e il risultato e un oggetto a forma garantita che puoi validare e inserire. E cio che trasforma "il modello ha detto qualcosa sulla fattura" in "la riga di fattura ha un fornitore, un importo, una valuta, una data e un project_id". Valida sempre il JSON restituito contro il tuo schema (Zod del tuo stack e ideale) prima di fidartene, perche un modello puo ancora derivare occasionalmente.

import { z } from 'zod'

// La forma esatta che vuoi in ritorno - e QUESTO il tuo record di database.
const InvoiceSchema = z.object({
  supplier: z.string(),
  invoiceNumber: z.string(),
  amount: z.number(),
  currency: z.string(),
  issueDate: z.string(), // data ISO
  projectId: z.string().nullable(),
})

// Di' al modello di restituire SOLO del JSON conforme a questo schema, poi valida.
const parsed = InvoiceSchema.parse(JSON.parse(modelJsonString))
// parsed e ora un record tipizzato e validato, pronto a inserire. Nessuna prosa.

Vision: una foto in entrata, un record in uscita

La stessa API accetta immagini, non solo testo. I modelli vision come Gemini leggono un'immagine e, combinati con il trucco di output strutturato, restituiscono un pulito record che descrive cio che vedono. Invii i byte dell'immagine accanto alla tua istruzione e al tuo schema e recuperi dati strutturati. E la mossa che automatizza l'inserimento di dati dal mondo fisico: punta un telefono su un documento o un oggetto, e una riga di database appare. Il modello fa la lettura; il tuo schema fa la strutturazione; il tuo codice fa l'inserimento. Tre passi, e un compito che era una volta una persona che digitava per ore diventa una foto e un webhook.

Studio di caso da fondatore: attribuzione di fatture

Eccone una vera che abbiamo costruito. Un'azienda annegava sotto le fatture fornitori che dovevano ciascuna essere lette, i loro campi estratti e - la parte noiosa - attribuita al giusto progetto interno prima di entrare nel sistema contabile. Abbiamo costruito un piccolo strumento: butta una foto o un PDF di fattura, un modello vision estrae fornitore, numero, importo, valuta e data nello schema esatto qui sopra, e un secondo passo l'attribuisce al giusto progetto, a partire dalle righe e dalla cronologia fornitore. Un umano approva sempre i casi limite (piu su questo nella lezione human-in-the-loop), ma la lettura e l'attribuzione che divoravano una volta ore a settimana arrivano ora in secondi. Nessun abbonamento SaaS, nessun costo per documento, un controllo totale della logica, e si attiene esattamente all'azienda, perche l'azienda ha definito lo schema.

Studio di caso da fondatore: carte da collezione svizzere

Il secondo strumento e piu divertente e fa lo stesso punto. Avevamo una grande collezione di carte da collezione svizzere da catalogare - ognuna ha bisogno del suo giocatore o motivo, del set, dell'anno e dello stato inseriti, il che e sfiancante a mano. Lo strumento e quasi imbarazzante per la sua semplicita: fotografa una carta, un modello vision restituisce un record strutturato (nome, set, anno, stato stimato) conforme a uno schema, e cio atterra in un database con l'immagine allegata. Cio che sarebbe stato giorni di inserimento manuale e diventato un pomeriggio a scattare foto. La lezione non riguarda le carte da collezione; e che "immagine verso record di database strutturato" e un pattern universale. Fatture, carte, inventario, biglietti da visita, ricevute, targhette di apparecchi - gli stessi tre passi si applicano a tutte.

Costruire, non comprare

I due studi di caso hanno rimpiazzato un acquisto SaaS con uno strumento interno, ed e il punto strategico. Quando un job e ristretto e specifico alla tua azienda, un piccolo strumento che possiedi, alimentato da una API, batte generalmente un prodotto generico che affitti. Ottieni un adattamento esatto, nessun costo per posto o per documento, un controllo totale dei dati e la capacita di cambiare la logica appena il tuo processo cambia. Non e "costruisci tutto" - prendi eccellenti SaaS per i bisogni standard. E "per i job di dati ristretti, ripetitivi e specifici all'azienda, uno strumento di cinquanta righe sopra una API di modello vince spesso".

• Costruisci quando il job e ristretto, specifico alla tua azienda e a volume abbastanza alto perche i costi SaaS per unita si sommino.
• Compra quando il bisogno e generico, l'adattamento SaaS buono e reinventeresti un prodotto maturo.
• Possiedi i tuoi dati e il tuo schema. Uno strumento che hai costruito si piega al tuo processo; uno strumento che affitti fa piegare il tuo processo a lui.

Errori frequenti

I comuni: mettere la chiave API in codice lato client, dove chiunque puo rubarla (appartiene a una env var server, sempre); chiedere prosa poi parsarla con string-matching fragile invece di esigere JSON validato da schema; saltare la validazione e inserire un record difettoso nel tuo database; usare un modello di punta caro per un'estrazione semplice ad alto volume quando un modello rapido ed economico e ampiamente sufficiente; e comprare del SaaS per un job che uno strumento interno di cinquanta righe farebbe meglio e meno caro.

ROI business

E la lezione in cui l'IA smette di essere un giocattolo da chat e comincia a rimpiazzare righe sulla tua fattura e ore nel tuo calendario. Uno strumento immagine-verso-record puo eliminare un posto di inserimento di dati part-time, e poiche lo possiedi, il costo marginale per documento e frazioni di centesimo di uso di modello, non un abbonamento SaaS. Gli strumenti da fondatore qui sopra hanno preso ciascuno un pomeriggio da costruire e hanno risparmiato ore ricorrenti ogni settimana. Per una piccola azienda, la capacita di costruire lo strumento esatto di cui hai bisogno a richiesta e un vantaggio strutturale che concorrenti che comprano solo del SaaS non possono raggiungere.

Checklist

Sei pronto ad andare avanti quando ognuno di questi punti e vero, perche le prossime lezioni costruiscono funnel e loop di feedback sopra strumenti come questi.

• Fare una chiamata di API minimale verso Gemini o Claude, la chiave in sicurezza in una env var.
• Imporre un output JSON strutturato e validarlo con uno schema prima di usarlo.
• Trasformare una foto in un record di database strutturato con un modello vision.
• Decidere per un vero job se costruisci uno strumento interno o compri del SaaS.

Risorse

Prendi del credito Gemini gratuito in Google AI Studio per prototipare strumenti vision gratis, e tieni a portata la documentazione Anthropic e Google AI, perche i nomi di modello e la superficie di API di output strutturato cambiano. Zod del tuo stack esistente e il tuo strato di validazione. Gli studi di caso /builds sull'automazione di fatture e lo strumento di carte da collezione svizzere vanno oltre su ciascuno, se vuoi tutta la storia.

La tua missione

Scegli un compito di inserimento di dati ripetitivo del tuo lavoro che comincia con un'immagine o un documento. Costruisci un piccolissimo strumento: prendi l'immagine, inviala a Gemini con uno schema Zod, valida il JSON e logga il record. Non hai bisogno di UI - uno script che mostra il record strutturato e la prova. Nota quanto tempo ha preso contro cio che il compito manuale ti costa ogni settimana.

Prossima lezione

Gli strumenti e le automazioni hanno bisogno di gente per trovarli. La prossima lezione copre la plumbing marketing: lead magnet, form di cattura, funnel e le regole di double opt-in via e-mail che devi seguire nell'UE e in Svizzera.