Configuración de Cloudflare Images¶

Documento preexistente, migrado al estándar de documentación

Redactado antes de la adopción del estándar (última edición: 2025-11-24) y movido acá; el único cambio de contenido fue corregir pnpm dev por npm run dev. Los precios de Cloudflare Images son los vigentes a esa fecha: confirmar contra la tarifa actual antes de usarlos para presupuestar. El resto (credenciales, variantes, troubleshooting) coincide con lo que hace el código hoy.

Este documento te guiará en la obtención de las credenciales necesarias para integrar Cloudflare Images con PayloadCMS.

Paso 1: Obtener las Credenciales de Cloudflare¶

1.1 CLOUDFLARE_ACCOUNT_ID¶

Inicia sesión en Cloudflare Dashboard
En el panel lateral izquierdo, ve a Images
En la URL verás algo como: https://dash.cloudflare.com/{ACCOUNT_ID}/images
Copia el ACCOUNT_ID de la URL

Alternativa: - Ve a cualquier sitio en tu dashboard - Haz scroll hacia abajo en el panel derecho - Verás "Account ID" en la sección de información de la cuenta

1.2 CLOUDFLARE_IMAGES_TOKEN (API Token)¶

Ve a API Tokens
Click en "Create Token"
Busca la plantilla "Cloudflare Images" y haz click en "Use template"
Configura los permisos:
Account → Cloudflare Images → Edit
En "Account Resources":
Selecciona "Include" → "All accounts" (o el account específico)
Click en "Continue to summary"
Click en "Create Token"
IMPORTANTE: Copia el token inmediatamente (solo se muestra una vez)

1.3 CLOUDFLARE_ACCOUNT_HASH (Delivery Hash)¶

Ve a Images Dashboard
Sube cualquier imagen de prueba (o usa una existente)
Click en la imagen para ver los detalles

Verás una URL de ejemplo como:

https://imagedelivery.net/{ACCOUNT_HASH}/{IMAGE_ID}/public

El ACCOUNT_HASH es el string entre imagedelivery.net/ y el siguiente /
Copia este hash (tiene formato de UUID)

Alternativa: - En el dashboard de Images, busca "Image Delivery URL" - El hash aparecerá en el formato de ejemplo de URL

Paso 2: Configurar Variables de Entorno¶

Abre tu archivo .env en la raíz del proyecto
Agrega las siguientes variables con tus valores reales:

# Cloudflare Images Configuration
CLOUDFLARE_ACCOUNT_ID=tu_account_id_aqui
CLOUDFLARE_IMAGES_TOKEN=tu_token_api_aqui
CLOUDFLARE_ACCOUNT_HASH=tu_account_hash_aqui

Paso 3: Configurar Variantes de Imagen¶

Las variantes definen los diferentes tamaños de imagen que Cloudflare generará automáticamente.

Ve a Images Dashboard
Click en la pestaña "Variants"
Crea las siguientes variantes (click en "Create Variant" para cada una):

Nombre	Fit	Width	Height	Descripción
thumbnail	scale-down	300	-	Miniaturas admin
square	cover	500	500	Imágenes cuadradas
small	scale-down	600	-	Móviles
medium	scale-down	900	-	Tablets
large	scale-down	1400	-	Desktop
xlarge	scale-down	1920	-	Full HD
og	cover	1200	630	Open Graph/Social

Configuración recomendada para cada variante: - Fit: - scale-down para mantener aspect ratio y no agrandar - cover para recortar y llenar dimensiones exactas - Metadata: Strip all (para optimizar tamaño) - Format: Auto (Cloudflare elegirá WebP/AVIF automáticamente)

Paso 4: Verificar la Configuración¶

Una vez configuradas las variables de entorno y variantes, reinicia tu servidor de desarrollo:

npm run dev

Límites y Precios de Cloudflare Images¶

Almacenamiento: $5 USD por 100,000 imágenes/mes
Entregas: Ilimitadas (sin costo adicional)
Transformaciones: Ilimitadas (sin costo adicional)
Plan gratuito: Hasta 100,000 entregas/mes con 1,000 imágenes almacenadas

Recursos Adicionales¶

Troubleshooting¶

Error: "Authentication error"¶

Verifica que el CLOUDFLARE_IMAGES_TOKEN sea correcto
Asegúrate de que el token tenga permisos de "Edit" para Cloudflare Images

Error: "Account not found"¶

Verifica el CLOUDFLARE_ACCOUNT_ID
Asegúrate de tener Cloudflare Images habilitado en tu cuenta

Las imágenes no cargan¶

Verifica el CLOUDFLARE_ACCOUNT_HASH
Asegúrate de que las variantes estén configuradas en el dashboard
Revisa que las imágenes se hayan subido correctamente (busca el cfImageId en la DB)