How to Use Cloudflare Workers AI for Text Summarization in Next.js API Routes

The repository ifindev/fullstack-next-cloudflare implements a secure, server-side API route that leverages Cloudflare Workers AI bindings to summarize text using the @cf/meta/llama-3.2-1b-instruct model, with request validation through Zod and authentication via Better-Auth.

This guide demonstrates how to use Cloudflare Workers AI for text summarization in API routes within a Next.js application deployed on Cloudflare Pages. By utilizing the Cloudflare runtime bindings available through @opennextjs/cloudflare, you can execute AI models at the edge without external API calls, reducing latency and simplifying architecture.

Setting Up the API Route

Route Location and Request Handling

The summarization endpoint resides in the Next.js App Router at src/app/api/summarize/route.ts. The POST handler receives JSON payloads and validates them against summarizeRequestSchema imported from src/services/summarizer.service.ts. This schema enforcement ensures type safety and consistent data structures before any AI processing begins.

Authentication with Better-Auth

Before executing AI operations, the route enforces authentication using Better-Auth sessions. The handler obtains the current session via getAuthInstance() from src/modules/auth/utils/auth-utils.ts. If no valid user session exists, the route immediately returns a 401 response, preventing unauthorized consumption of AI resources.

Accessing Cloudflare Workers AI Bindings

Cloudflare's runtime injects the AI binding directly into the request context through getCloudflareContext() from @opennextjs/cloudflare. The route accesses the binding as follows:

const { env } = await getCloudflareContext();
if (!env.AI) {
  // Handle missing binding error
}

The env.AI object serves as the entry point for running machine learning models on Cloudflare's global edge network.

Implementing the Summarization Service

The core AI logic is encapsulated in src/services/summarizer.service.ts, which handles prompt engineering, model execution, and response formatting.

Building System Prompts

The service constructs dynamic system prompts based on three configuration parameters: maxLength (target word count), style (concise, detailed, or bullet-points), and language (output language). This contextual tailoring ensures the summary matches specific user requirements without requiring model retraining.

Model Selection and Execution

The implementation invokes the Cloudflare-hosted model @cf/meta/llama-3.2-1b-instruct through the AI binding:

this.ai.run("@cf/meta/llama-3.2-1b-instruct", { messages: [...] })

This model is a quantized variant of Meta's LLaMA 3.2 optimized for instruction-following tasks.

Token Estimation and Response Formatting

Before sending requests, the service estimates input tokens using approximately four characters per token to respect context limits. After receiving the model output, it wraps the summary with metadata including originalLength, summaryLength, and tokensUsed, providing transparency for quota management and performance monitoring.

Error Handling and Response Standards

Any uncaught exceptions are processed through handleApiError imported from src/lib/api-error.ts. This utility ensures consistent JSON error responses across the API, maintaining predictable client-side error handling and standardized error shapes for logging and debugging.

Usage Examples

Client-Side Implementation

Call the endpoint from browser applications or HTTP clients:

async function summarizeText(text: string) {
  const response = await fetch('/api/summarize', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      text,
      config: {
        maxLength: 250,
        style: 'concise',
        language: 'English',
      },
    }),
  });

  const result = await response.json();
  if (!result.success) throw new Error(result.error);
  return result.data;
}

Command Line Testing

Use curl with an authenticated session cookie:

curl -X POST https://<your-domain>/api/summarize \
  -H "Content-Type: application/json" \
  -b "next-auth.session-token=YOUR_SESSION_COOKIE" \
  -d '{
        "text":"Long article content …",
        "config":{"maxLength":300,"style":"bullet-points","language":"Spanish"}
      }'

Server Action Reuse

Import the service into other server components or actions:

import { SummarizerService } from '@/services/summarizer.service';
import { getCloudflareContext } from '@opennextjs/cloudflare';

export async function generateSummary(text: string) {
  const { env } = await getCloudflareContext();
  if (!env.AI) throw new Error('AI binding missing');

  const service = new SummarizerService(env.AI);
  return await service.summarize(text, { style: 'detailed' });
}

Summary

• Authentication Enforcement: The endpoint validates Better-Auth sessions via getAuthInstance() in src/modules/auth/utils/auth-utils.ts before processing requests.
• Type-Safe Validation: The summarizeRequestSchema Zod definition ensures all incoming requests contain valid text and configuration parameters.
• Edge AI Integration: The env.AI binding from @opennextjs/cloudflare provides direct access to Cloudflare Workers AI without external network calls.
• Model Implementation: Uses the @cf/meta/llama-3.2-1b-instruct model with custom system prompts for controllable summary generation.
• Centralized Error Handling: The handleApiError utility in src/lib/api-error.ts maintains consistent JSON error responses across the API surface.

Frequently Asked Questions

What AI model does this implementation use for summarization?

The service utilizes the @cf/meta/llama-3.2-1b-instruct model, a Cloudflare-hosted variant of Meta's LLaMA 3.2 instruction-tuned model. This model runs entirely on Cloudflare's edge network infrastructure, eliminating latency from external API calls and ensuring data remains within Cloudflare's secure environment.

How does the route protect against unauthorized access?

The implementation authenticates every request using Better-Auth session management. The handler in src/app/api/summarize/route.ts calls getAuthInstance() to verify the user session before accessing env.AI. Unauthenticated requests receive an immediate 401 response, ensuring only authorized users consume AI compute resources.

Can I reuse the summarization logic outside of API routes?

Yes, the SummarizerService class in src/services/summarizer.service.ts is designed for portability. You can instantiate it in server actions, background workers, or other API routes by passing the env.AI binding obtained from getCloudflareContext(). This modularity allows consistent AI behavior across different execution contexts in your Next.js application.

What configuration options are available for customizing summaries?

The endpoint accepts a configuration object with three parameters: maxLength (default 200) controls the target word count, style (concise, detailed, or bullet-points) adjusts the output format, and language (default English) specifies the desired output language. These parameters dynamically modify the system prompt sent to the LLaMA model.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}