Scrivere sulle foto con Cloudflare Images: overlay di testo nei Worker

Il flusso più rapido per scrivere sulle foto

Si parte da un layout ripetibile. Questo esempio crea una card di prodotto da 1200 × 630, ricava il titolo da ?text=, usa un font di brand fisso e restituisce un file WebP. I due URL degli asset su example.com vanno sostituiti con URL sotto il proprio controllo.

Nel file di configurazione Wrangler, aggiungere il binding Images e attivare Workers Cache:

{
  "images": {
    "binding": "IMAGES"
  },
  "cache": {
    "enabled": true
  }
}

Quindi usare il binding nel Worker:

const CARD_IMAGE = "https://assets.example.com/product-card.jpg";
const BRAND_FONT = "https://assets.example.com/fonts/Brand-Bold.woff2";

export default {
  async fetch(request, env) {
    const url = new URL(request.url);
    const headline = (url.searchParams.get("text") || "AUTUMN DROP").trim();

    // This is a layout limit for this card, not Cloudflare's 1,000-character ceiling.
    if (!headline || [...headline].length > 120) {
      return new Response("Text must contain 1 to 120 characters", { status: 400 });
    }

    const source = await fetch(CARD_IMAGE);
    if (!source.ok || !source.body) {
      return new Response("Source image unavailable", { status: 502 });
    }

    const textLayer = env.IMAGES.text(headline, {
      font: { url: BRAND_FONT },
      size: 72,
      color: "#FFFFFF"
    });

    const result = await env.IMAGES
      .input(source.body)
      .transform({ width: 1200, height: 630, fit: "cover" })
      .draw(textLayer, { left: 72, bottom: 72 })
      .output({ format: "image/webp" });

    return result.response({
      headers: {
        "Cache-Control": "public, max-age=86400, stale-while-revalidate=604800"
      }
    });
  }
};

Richiedendo /card?text=Autumn%20Drop si ottiene un WebP da 1200 × 630 con la frase indicata a 72 pixel dai bordi sinistro e inferiore. Poiché l’URL dell’immagine contiene il testo variabile, in questo esempio ogni didascalia ha naturalmente un URL distinto. In produzione conviene usare, quando possibile, ID stabili di campagne o prodotti. Accettare testo libero in una query string pubblica può generare un numero illimitato di varianti, con conseguenze sia sui costi sia sul rischio di abuso.

Le origini dell’immagine sorgente e del font devono rimanere fisse o essere incluse in una allowlist. L’esempio non consente al visitatore di scegliere una destinazione arbitraria da recuperare. È un confine essenziale ogni volta che un Worker pubblico può scaricare asset remoti.

Che cosa fa davvero Cloudflare

La rasterizzazione converte le lettere in pixel. Si può immaginare .text() come una piccola macchina tipografica che stampa un adesivo trasparente: .draw() applica l’adesivo alla fotografia, mentre .output() unisce i due elementi nel file finale.

Questo modello mentale chiarisce il funzionamento dell’API. Il testo non è un elemento HTML sospeso sopra l’immagine nel browser: una volta renderizzato, diventa parte dei pixel dell’immagine.

L’immagine di base determina le dimensioni finali della tela. Il testo si posiziona tramite offset in pixel con top, left, bottom o right; senza indicazioni viene centrato. Sullo stesso overlay non è possibile impostare contemporaneamente left e right, né top e bottom. L’opacità va da 0 a 1 e la modalità di compositing predefinita è over.

È possibile concatenare più chiamate .draw(). L’ordine delle chiamate stabilisce quello dei livelli, quindi l’ultimo elemento disegnato resta in primo piano. Cloudflare ha aggiunto anche una voce text all’array cf.image.draw per le trasformazioni basate su URL, ma il binding è più adatto quando l’immagine di base arriva già sotto forma di byte grezzi da R2, Cloudflare Images, dal corpo di una richiesta o da un altro fetch.

Il limite più importante riguarda l’intelligenza di layout. Per lo stile del testo, al momento Cloudflare documenta font, size e color. Non documenta caselle di testo, ritorno a capo, ridimensionamento automatico, interlinea, spaziatura, allineamento, contorno, ombra o fallback del font. Spetta all’applicazione stabilire le interruzioni di riga, le aree sicure e come gestire un nome di prodotto troppo lungo.

Memorizzare nella cache la card finita, non solo la sorgente

Le risposte del binding Images non vengono memorizzate automaticamente nella cache. Senza Workers Cache, ogni richiesta ripetuta esegue di nuovo il Worker e ripete la decodifica e la codifica della sorgente. Attivando la cache e impostando Cache-Control, Cloudflare può servire la risposta finita senza rifare il lavoro.

Cache e fatturazione di Images risolvono problemi diversi. Cloudflare addebita il binding in base alle trasformazioni univoche: ogni combinazione univoca di immagine sorgente e parametri viene conteggiata una volta per mese di calendario, mentre le ripetizioni della stessa trasformazione non aggiungono consumo Images nello stesso mese. Le risposte dalla cache restano importanti perché evitano di rieseguire il Worker e riducono la latenza dell’elaborazione delle immagini.

Cloudflare non spiega separatamente come vengano normalizzate le stringhe di testo nel calcolo dell’unicità. Per pianificare in sicurezza, è meglio considerare ogni combinazione distinta di immagine di base, didascalia, stile e output come una nuova trasformazione, finché i propri dati di utilizzo non dimostrano il contrario. Un catalogo con 2,000 prodotti e cinque formati di card può quindi comportarsi come 10,000 varianti, anche se ogni card viene visualizzata migliaia di volte.

I conti cambiano quando il layout è già definito internamente

Cloudflare Images Free include 5,000 trasformazioni univoche al mese. Nel piano a pagamento, le prime 5,000 restano incluse e le successive costano $0.50 ogni 1,000. Nell’esempio pubblicato da Cloudflare con 10,000 trasformazioni, la voce relativa alle trasformazioni Images ammonta a $2.50 per il mese.

Bannerbear indica attualmente il piano Automate a $49 al mese per 1,000 crediti API e il piano Scale a $149 al mese per 10,000 crediti. Il rendering di una normale immagine consuma un credito, prima di applicare eventuali moltiplicatori per formati aggiuntivi, scala o livelli AI.

La differenza di $146.50 non equivale a un risparmio chiavi in mano. Bannerbear vende un prodotto di design già operativo, completo di editor di template, integrazioni e flusso di lavoro per i team. Cloudflare mette a disposizione primitive di rendering che vanno progettate, programmate, validate, monitorate e mantenute. Al costo delle trasformazioni Images possono aggiungersi lo storage delle sorgenti e il tempo di sviluppo; anche lo storage all’interno di Cloudflare Images ha un prezzo proprio.

La scelta, però, resta netta. Se il team possiede già le regole grafiche e la richiesta dell’immagine passa da Cloudflare, un abbonamento separato per il rendering può diventare facoltativo. Se invece il marketing deve spostare visivamente i livelli ogni settimana, l’abbonamento paga l’editor e il modello operativo, non pixel costosi.

I sette flussi di lavoro che ne traggono più vantaggio, in ordine

1. Card merchandising per cataloghi

Un retailer con centinaia di SKU può mantenere un unico sfondo approvato e inserirvi il nome attuale del prodotto, il prezzo, un’indicazione sulle scorte o una promozione. I dati dell’inventario o della campagna attivano il Worker, che restituisce l’asset finale per il marketplace o i social. Il vantaggio nasce dal fatto che una variazione di prezzo non crea più una coda di esportazioni manuali e lo stesso layout approvato può essere rigenerato senza modificare la foto originale.

La soluzione funziona al meglio con testi dai limiti prevedibili. Un nome di prodotto su due righe e un badge con il prezzo sono gestibili; un paragrafo promozionale non lo è.

2. Social card per editori e CMS

Al momento della pubblicazione di un articolo, una testata può chiamare un unico endpoint passando il titolo o un ID articolo stabile. Il Worker recupera l’immagine hero, renderizza il titolo e restituisce la card Open Graph o social. Il risultato è un minor numero di immagini di condivisione mancanti o non aggiornate, senza dover attendere un browser per gli screenshot nel percorso di pubblicazione.

È una soluzione particolarmente interessante quando il CMS opera già dietro Cloudflare. L’immagine può essere generata sullo stesso livello edge che la distribuisce, memorizzando nella cache l’URL finale per le condivisioni successive.

3. Immagini di stato per marketplace

Un marketplace può imprimere NEW, RESERVED, SOLD, la condizione o la località sulle card degli annunci. Il servizio degli annunci modifica un piccolo valore testuale e l’endpoint dell’immagine produce il nuovo stato visivo. I venditori non devono ritoccare le foto originali, mentre gli acquirenti vedono lo stato direttamente nell’immagine ovunque venga incorporata la card.

Il ritorno commerciale sta nella precisione. Una card con uno stato non aggiornato genera richieste di assistenza e clic deludenti; un overlay deterministico può cambiare insieme al record.

4. Creatività per franchising e offerte locali

Un ristorante o una rete di servizi in franchising può mantenere invariata la composizione del brand e cambiare città, offerta, data o prezzo in base alla località. Una sola definizione di campagna produce molte varianti locali. Si riduce così il lavoro di produzione ripetitivo, lasciando gli elementi più delicati — come font, colore e posizione — fuori dal controllo del singolo operatore locale.

I nomi di località lunghi sono il punto critico. Prima di poter automatizzare il flusso in sicurezza servono larghezze del testo misurate, dimensioni alternative o abbreviazioni pre-approvate.

5. Card per eventi e programmi

Una piattaforma per eventi può renderizzare su un poster fisso i nomi degli speaker, gli orari delle sessioni, i numeri delle sale o uno stato CANCELLED inserito all’ultimo minuto. Il programma originale resta il dato di riferimento e la generazione delle card diventa una fase di output. Il vantaggio è la velocità quando i dettagli cambiano a ridosso dell’evento, senza chiedere a un designer di riaprire decine di file.

6. Snapshot dei report per i clienti

Un prodotto di reporting può aggiungere a un grafico brandizzato il periodo, il nome del cliente e la metrica principale, così da usarlo in email o messaggi. Il Worker riceve come base il grafico già renderizzato, aggiunge le poche etichette variabili e restituisce un formato finale compatto. È utile quando la destinazione non può eseguire direttamente la dashboard.

Il livello di testo non va usato per disegnare un’intera dashboard. Rende al meglio come ultimo passaggio deterministico di etichettatura.

7. Etichette operative interne

Un magazzino, un team di assistenza sul campo o una coda di moderazione può inserire brevi testi di stato sulle foto degli articoli: esito dell’ispezione, lotto, percorso o risultato della revisione. L’indicazione visiva si conserva anche nel passaggio attraverso sistemi che eliminano i metadati circostanti. Il vantaggio è dover effettuare meno ricerche quando qualcuno riceve l’immagine fuori contesto.

È una comodità operativa, non un sostituto del record sottostante. Lo stato deve rimanere nel database e l’immagine va considerata come una sua vista.

Tre prodotti che vale la pena costruire

L’opportunità migliore: un endpoint verticale per social card

Si può realizzare un servizio di card conforme al brand per editori, agenzie o aziende con più sedi che usano già layout fissi, ma non vogliono gestire uno stack di rendering basato sul browser. Il cliente fornisce un’immagine hero e campi di testo approvati; il servizio restituisce URL stabili per un piccolo insieme di proporzioni.

I dati sulle keyword negli Stati Uniti stimano 480 ricerche mensili per social media post maker, con un costo per clic di $19.95. La frase esatta è più ampia dell’intento di chi cerca un’API, ma il CPC insolitamente alto dimostra che i fornitori competono per questo lavoro di produzione. I piani mensili da $49 e $149 di Bannerbear offrono un riferimento di budget attuale per i team che già pagano il rendering automatizzato.

La versione minima vendibile comprende un Worker, tre layout di card bloccati, un’anteprima amministrativa, un webhook per il CMS, allowlist rigorose per le sorgenti, chiavi cache stabili e una coda di errore per i testi che non rientrano. Ciò che si vende è l’affidabilità del collegamento con il sistema editoriale, non la semplice chiamata .text().

Il punto critico è la proprietà dei template. Cloudflare non offre al cliente un editor visuale e ogni nuovo layout può trasformarsi in lavoro di servizio. Resta comunque l’opportunità più solida: la nuova primitiva elimina il renderer da un flusso ricorrente e di valore commerciale, lasciando come prodotto l’integrazione e la governance del brand.

Un motore per etichette promozionali di catalogo

Si può costruire un compositore basato sui feed per i team ecommerce, capace di aggiungere alle immagini di prodotto prezzi, stati di promozione, promesse di consegna o nomi di collezioni. Un CSV, un PIM o un webhook della piattaforma commerce aggiorna i dati; il servizio rigenera soltanto le varianti modificate.

Product label maker registra circa 320 ricerche mensili negli Stati Uniti, esprime un intento commerciale e ha un CPC di $6.03, con un’elevata concorrenza tra inserzionisti. È un segnale di domanda a pagamento per la creazione di etichette, anche se una parte consistente delle ricerche riguarda etichette stampabili anziché grafiche per cataloghi.

Per un MVP servono un connettore al feed dei prodotti, una manciata di badge fissi, preset per le proporzioni, un’anteprima e regole per nomi lunghi e prezzi mancanti. Il rischio è l’allargamento dello scope. Il packaging fisico richiede risoluzione di stampa, abbondanze, codici a barre e verifiche normative che questo solo overlay raster non può gestire. È meglio limitarsi alle etichette promozionali sulle immagini, a meno che tali sistemi non facciano parte del prodotto.

Uno strumento integrato per aggiungere testo alle immagini

Si può creare un piccolo componente di editing per un prodotto dedicato a creator, marketplace o community: si sceglie un’immagine, si inserisce un testo breve, si selezionano font e colori approvati, lo si posiziona entro un’area sicura e infine si esporta. Cloudflare gestisce la rasterizzazione finale dietro l’interfaccia del prodotto.

Add text to image riceve circa 6,600 ricerche mensili negli Stati Uniti. La query più transazionale add text to image app registra circa 320 ricerche ed è cresciuta del 23 percento su base annua nello stesso dataset. La domanda esiste, ma gran parte del pubblico si aspetta un editor generalista gratuito.

L’MVP comprende un’anteprima vincolata, da quattro a sei preset di testo, un endpoint di esportazione e lo storage dell’URL finale. Il limite è una difendibilità ridotta. Uno strumento generico standalone compete con editor gratuiti maturi; ha più senso come funzionalità a pagamento dentro un prodotto che possiede già l’immagine, l’utente e la destinazione di pubblicazione.

Quando questo non è lo strumento giusto

Cloudflare Images può renderizzare e comporre il testo. Non decide che cosa debba dire, non rende la tipografia responsive, non approva il layout del brand e non offre un editor di template rivolto al marketing. Se sono questi gli aspetti più complessi, un prodotto completo di design automation può ancora costare meno della loro manutenzione interna. Per una panoramica più ampia su come cambiare interi sistemi di brand, si veda il test di Canva AI 2.0 per il rinnovamento del brand.

Ci sono cinque segnali concreti che indicano quando fermarsi:

• Il testo richiede ritorni a capo avanzati, ridimensionamento automatico, testo formattato o una gestione specifica della scrittura che non è stata verificata con il font scelto.
• Gli editor devono poter spostare visivamente i livelli e pubblicare nuovi template senza l’intervento di uno sviluppatore.
• Un endpoint pubblico accetterebbe URL arbitrari per la sorgente o il font senza una allowlist.
• Non è possibile limitare la creazione delle varianti, quindi query string casuali potrebbero consumare la quota Free di 5,000 trasformazioni e far fallire le nuove richieste con l’errore 9422.
• Il test locale dipende dal rendering del testo. L’implementazione locale a bassa fedeltà di Images supporta soltanto larghezza, altezza, rotazione e formato, quindi per questa funzionalità va usato npx wrangler dev --remote.

I limiti relativi a font e testo sono vincoli rigidi: un font personalizzato non può superare 20 MB, il contenuto renderizzato non può eccedere 1,000 caratteri e il relativo livello raster non può superare 4096 × 4096 pixel. Sono soglie generose per etichette e titoli, ma non autorizzano a trasformare l’API per immagini in un motore di impaginazione.

Per realizzare un endpoint di immagini affidabile intorno al proprio catalogo o sistema editoriale, il punto di partenza sono i sistemi di produzione AI.