Como adicionar texto em imagem com Cloudflare Images

Como adicionar texto em imagem: o pipeline mais curto

Comece com um layout que possa ser reproduzido sempre da mesma forma. Este exemplo cria um card de produto de 1200 por 630, recebe o título por ?text=, usa uma fonte fixa da marca e devolve o resultado em WebP. Troque as duas URLs de ativos em example.com por endereços sob seu controle.

Adicione o binding do Images e habilite o Workers Cache na configuração do Wrangler:

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

Depois, use o binding no 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"
      }
    });
  }
};

Faça uma requisição a /card?text=Autumn%20Drop. O resultado será um WebP de 1200 por 630 com a frase informada a 72 pixels das bordas esquerda e inferior. Como o texto variável faz parte da URL da imagem, cada legenda ganha naturalmente um endereço próprio neste exemplo. Em produção, prefira IDs estáveis de campanha ou produto sempre que possível. Texto livre em uma query string pública pode gerar um número ilimitado de variantes, criando tanto um problema de custo quanto de abuso.

Mantenha as origens da imagem e da fonte fixas ou em uma allowlist. O exemplo não permite que o visitante escolha qualquer destino para o fetch. Essa barreira é essencial sempre que um Worker público pode buscar ativos remotos.

O que o Cloudflare realmente faz nos bastidores

Rasterizar texto significa converter letras em pixels. Pense em .text() como uma pequena máquina de composição tipográfica que imprime um adesivo transparente. .draw() coloca esse adesivo sobre a fotografia, e .output() sela os dois elementos no arquivo final.

Esse modelo mental explica a API. O texto não é um elemento HTML flutuando sobre uma imagem no navegador. Depois de renderizado, ele passa a fazer parte dos pixels da imagem.

A imagem base determina o tamanho final do canvas. Posicione o texto com deslocamentos em pixels definidos por top, left, bottom ou right. Sem posição explícita, ele fica centralizado. Não é possível usar left e right, nem top e bottom, ao mesmo tempo no mesmo overlay. A opacidade vai de 0 a 1, e o modo de composição padrão é over.

É possível encadear várias chamadas a .draw(). A ordem das chamadas define a ordem das camadas, portanto o último draw fica por cima. O Cloudflare também adicionou uma entrada text ao array cf.image.draw para transformações baseadas em URL. Ainda assim, o binding costuma ser mais adequado quando a imagem base já chega como bytes brutos do R2, do Cloudflare Images, do corpo de uma requisição ou de outro fetch.

O que faz falta é inteligência de layout. Hoje, o Cloudflare documenta font, size e color para estilizar texto. Não há documentação para caixas de texto, quebra de linha, ajuste automático, altura de linha, tracking, alinhamento, contorno, sombra ou fallback de fonte. Cabe à aplicação decidir onde quebrar linhas, quais são as áreas seguras e o que fazer quando o nome de um produto é longo demais.

Coloque o card pronto em cache, não apenas a imagem original

As respostas do binding do Images não entram em cache automaticamente. Sem o Workers Cache, uma requisição repetida executa o Worker e decodifica e codifica a imagem original novamente. Ao habilitar o cache e definir Cache-Control, o Cloudflare pode servir a resposta final sem repetir esse trabalho.

Cache e cobrança do Images resolvem problemas diferentes. O Cloudflare cobra o binding por transformações únicas: cada combinação exclusiva de imagem original e parâmetros conta uma vez por mês-calendário, e repetições da mesma transformação não aumentam o uso do Images naquele mês. Mesmo assim, os acertos de cache importam porque evitam novas execuções do Worker e a latência do processamento de imagem.

O Cloudflare não explica separadamente como as strings de texto são normalizadas no cálculo de exclusividade. Para planejar com segurança, considere cada combinação diferente de imagem base, legenda, estilo e saída como uma nova transformação até que seus próprios dados de uso mostrem o contrário. Assim, um catálogo com 2,000 produtos e cinco tamanhos de card pode se comportar como 10,000 variantes, mesmo que cada card receba milhares de visualizações.

A conta muda quando o layout já pertence à sua equipe

O plano Cloudflare Images Free inclui 5,000 transformações únicas por mês. No plano pago, as primeiras 5,000 continuam incluídas, e o restante custa $0.50 por 1,000. No exemplo do próprio Cloudflare com 10,000 transformações, a linha de transformação do Images fica em $2.50 no mês.

Atualmente, a Bannerbear informa $49 por mês no plano Automate, com 1,000 créditos de API, e $149 por mês no Scale, com 10,000 créditos. Uma renderização comum de imagem consome um crédito, antes de multiplicadores por formatos extras, escala ou camadas de IA.

A diferença de $146.50 não representa uma economia pronta para uso. A Bannerbear vende um produto de design funcional, com editor de templates, integrações e fluxo para equipes. O Cloudflare oferece primitivas de renderização que sua equipe precisa projetar, programar, validar, monitorar e manter. O armazenamento da origem e o tempo de engenharia podem se somar à cobrança pelas transformações do Images; armazenar dentro do Cloudflare Images tem preço próprio.

Ainda assim, a decisão é clara. Se a equipe já domina as regras de design e a requisição de imagem passa pelo Cloudflare, uma assinatura separada de renderização pode se tornar opcional. Se o marketing precisa reposicionar camadas visualmente toda semana, a assinatura paga pelo editor e pelo modelo operacional — não por pixels caros.

Os sete fluxos que mais se beneficiam, em ordem

1. Cards de merchandising para catálogos

Um varejista com centenas de SKUs pode manter um único layout de fundo aprovado e inserir em cada card o nome atual do produto, o preço, um aviso de estoque ou uma promoção. Dados de estoque ou campanha acionam o Worker, que devolve o ativo final para marketplace ou rede social. O ganho aparece porque uma mudança de preço deixa de criar uma fila de exportações manuais, e o mesmo layout aprovado pode ser regenerado sem alterar a foto original.

O cenário ideal usa textos com limites claros. Um nome de produto em duas linhas e um selo de preço são previsíveis; um parágrafo de texto promocional, não.

2. Cards sociais para publishers e CMSs

Uma publicação pode chamar um único endpoint quando um artigo entra no ar, enviando o título ou um ID estável do artigo. O Worker busca a imagem de destaque, renderiza o título e devolve o card de Open Graph ou de rede social. O resultado é menos imagens de compartilhamento ausentes ou desatualizadas, sem deixar um navegador de screenshots esperando no fluxo de publicação.

Esse caso é especialmente interessante quando o CMS já opera por trás do Cloudflare. A imagem pode ser gerada na mesma camada de edge que a entrega, com a URL final armazenada em cache para os compartilhamentos seguintes.

3. Imagens de status para marketplaces

Um marketplace pode aplicar NEW, RESERVED, SOLD, a condição ou a localização aos cards de anúncios. O serviço de anúncios altera um pequeno valor de texto, e o endpoint de imagem produz o novo estado visual. Os vendedores não precisam editar as fotos originais, enquanto os compradores enxergam o status dentro da imagem em qualquer lugar onde o card apareça.

O retorno comercial vem da precisão. Um card com status desatualizado gera chamados de suporte e cliques frustrados. Um overlay determinístico pode acompanhar a mudança no registro.

4. Criativos para franquias e ofertas locais

Uma franquia de restaurantes ou serviços pode manter a composição da marca e variar cidade, oferta, data ou preço conforme a unidade. Uma definição de campanha passa a gerar muitas versões locais. Isso reduz o trabalho repetitivo de produção e mantém os pontos mais arriscados — como fonte, cor e posicionamento — fora do controle do operador local.

Nomes de lugares longos são a armadilha. Para automatizar com segurança, o fluxo precisa medir a largura do texto e prever tamanhos alternativos ou abreviações aprovadas.

5. Cards de eventos e programação

Uma plataforma de eventos pode renderizar nomes de palestrantes, horários de sessões, números de salas ou um aviso de última hora como CANCELLED sobre um pôster fixo. A programação original continua sendo o registro oficial, e gerar os cards vira apenas uma etapa de saída. O benefício é a velocidade quando algo muda perto do evento, sem pedir a um designer que reabra dezenas de arquivos.

6. Imagens-resumo de relatórios para clientes

Um produto de relatórios pode inserir período, nome do cliente e principal métrica sobre uma imagem de gráfico com a identidade da marca para uso em e-mail ou mensageria. O Worker recebe o gráfico já renderizado como base, acrescenta os poucos rótulos variáveis e devolve um formato final compacto. Isso é útil quando o destino não consegue executar o dashboard.

Não use a camada de texto para desenhar um dashboard inteiro. Ela funciona melhor como a etapa final e determinística de rotulagem.

7. Etiquetas operacionais internas

Um armazém, uma equipe de atendimento em campo ou uma fila de moderação pode renderizar textos curtos de status sobre fotos de itens: etapa da inspeção, lote, rota ou resultado da análise. A informação visual circula bem mesmo em sistemas que removem os metadados ao redor. O benefício é reduzir consultas quando alguém recebe a imagem fora de contexto.

Trata-se de conveniência operacional, não de um substituto para o registro de origem. Mantenha o status no banco de dados e trate a imagem como uma visualização.

Três produtos que vale a pena criar

Melhor oportunidade: um endpoint especializado em cards sociais

Crie um serviço de cards protegido pelas regras da marca para publishers, agências ou empresas com várias unidades que já usam layouts fixos, mas não querem operar uma infraestrutura de renderização em navegador. O cliente fornece a imagem de destaque e os campos de texto aprovados; o serviço devolve URLs estáveis para um conjunto pequeno de proporções.

Dados de palavras-chave nos EUA estimam 480 buscas mensais por social media post maker, com custo por clique de $19.95. A expressão exata é mais ampla do que o perfil de quem compra uma API, mas o CPC incomumente alto mostra que fornecedores disputam esse trabalho de produção. Os planos mensais de $49 e $149 da Bannerbear oferecem uma referência atual de orçamento para equipes que já pagam por renderização automatizada.

A menor versão que já pode ser vendida reúne um Worker, três layouts de card bloqueados, uma prévia administrativa, um webhook de CMS, allowlists rígidas para as origens, chaves de cache estáveis e uma fila de falhas para textos que não cabem. Venda a confiabilidade da integração com a publicação, não a chamada .text() em si.

O ponto delicado é a responsabilidade pelos templates. O Cloudflare não entrega um editor visual ao cliente, e cada novo layout pode virar trabalho de serviço. Ainda é a oportunidade mais forte porque a nova primitiva elimina o renderizador de um fluxo recorrente com valor comercial, enquanto integração e governança de marca permanecem como o produto.

Um mecanismo de etiquetas promocionais para catálogos

Crie um compositor alimentado por feed para equipes de ecommerce que insere preços, estados de promoção, promessas de entrega ou nomes de coleções nas imagens dos produtos. Um CSV, PIM ou webhook da plataforma de comércio atualiza os dados; o serviço regenera apenas as variantes alteradas.

Product label maker recebe uma estimativa de 320 buscas mensais nos EUA, tem intenção comercial e CPC de $6.03, com alta concorrência entre anunciantes. Isso indica demanda paga em torno da criação de etiquetas, embora boa parte da consulta se refira a etiquetas impressas, e não a imagens de catálogo.

Um MVP precisa de um conector para feed de produtos, alguns selos fixos, presets de proporção, uma prévia e regras para nomes longos e preços ausentes. O risco é o escopo. Embalagens físicas envolvem resolução para impressão, sangria, códigos de barras e análise regulatória — problemas que esse overlay rasterizado, sozinho, não resolve. Fique nas etiquetas promocionais para imagens, a menos que esses sistemas também façam parte do produto.

Uma ferramenta integrada para adicionar texto

Crie um pequeno componente de edição para um produto existente de criação, marketplace ou comunidade: o usuário escolhe uma imagem, digita um texto curto, seleciona entre fontes e cores aprovadas, posiciona o conteúdo em uma área segura e exporta. O Cloudflare cuida da rasterização final por trás da interface do próprio produto.

Add text to image recebe uma estimativa de 6,600 buscas mensais nos EUA. A consulta mais transacional add text to image app registra cerca de 320 buscas e cresceu 23 por cento em relação ao ano anterior no mesmo conjunto de dados. A demanda existe, mas boa parte do público espera um editor genérico gratuito.

O MVP é formado por uma prévia com limites, de quatro a seis presets de texto, um endpoint de exportação e armazenamento da URL final. O problema é a baixa diferenciação. Uma ferramenta genérica independente disputa espaço com editores gratuitos e maduros. Ela faz mais sentido como recurso pago dentro de um produto que já concentra a imagem, o usuário e o destino de publicação.

Quando esta é a ferramenta errada

O Cloudflare Images consegue renderizar e compor texto. Ele não decide o que escrever, não torna a tipografia responsiva, não aprova um layout de marca nem oferece um editor de templates para profissionais de marketing. Se essas forem as partes difíceis do trabalho, um produto completo de automação de design ainda pode sair mais barato do que mantê-las internamente. Para uma análise mais ampla sobre mudanças em sistemas de marca inteiros, veja o teste de renovação de marca com o Canva AI 2.0.

Há cinco sinais práticos de que é melhor parar:

• O texto exige quebra de linha sofisticada, ajuste automático, rich text ou shaping específico de um sistema de escrita que ainda não foi testado com a fonte escolhida.
• Editores precisam mover camadas visualmente e publicar novos templates sem depender de uma pessoa desenvolvedora.
• Um endpoint público aceitaria URLs arbitrárias de imagem original ou fonte sem uma allowlist.
• Não é possível limitar a criação de variantes, então query strings aleatórias poderiam consumir a franquia Free de 5,000 transformações e fazer novas requisições falharem com o erro 9422.
• O teste local depende da renderização de texto. A implementação local de baixa fidelidade do Images aceita apenas largura, altura, rotação e formato; para este recurso, use npx wrangler dev --remote.

Os limites de fonte e texto são rígidos: uma fonte personalizada não pode ultrapassar 20 MB, o conteúdo renderizado não pode ter mais de 1,000 caracteres, e sua camada rasterizada não pode exceder 4096 por 4096 pixels. Esses tetos são generosos para etiquetas e títulos. Eles não são um convite para transformar a API de imagens em um mecanismo de layout de página.

Se você quer um endpoint de imagens confiável e integrado ao seu catálogo ou sistema de publicação, sistemas de produção com IA são o melhor ponto de partida.