Replicate AI Handler Skill

Replicate AI Handler Skill

This skill provides a production-ready pattern for integrating Replicate AI models. It handles long-running predictions using Inngest background jobs, stores results in S3, manages user credits, and updates database state.

Architecture

1. Trigger: User requests a generation via API (e.g., /api/app/ai-images).
2. Validation: Check/deduct user credits.
3. State: Create a database record with status: "processing".
4. Queue: Trigger an Inngest function to handle the Replicate API call.
5. Processing:
   • Call Replicate API.
   • Wait for completion (polling or webhook).
   • Download result and upload to S3 (server-side).
6. Completion: Update database record with S3 URL and status: "completed".
7. Failure: Refund credits if failed (optional) and update status to failed.

Prerequisites

• replicate package installed (npm install replicate).
• REPLICATE_API_TOKEN in .env.
• S3 and Inngest configured.

Implementation Steps

1. API Route (Trigger)

src/app/api/app/generate/route.ts

import withAuthRequired from "@/lib/auth/withAuthRequired";
import { db } from "@/db";
import { generations } from "@/db/schema";
import { inngest } from "@/lib/inngest/client";
import { checkCredits, deductCredits } from "@/lib/credits"; // Hypothetical helpers

export const POST = withAuthRequired(async (req, { session }) => {
  const body = await req.json();
  
  // 1. Check Credits
  const hasCredits = await checkCredits(session.user.id, "image_generation", 1);