Building an AI text wrapper is straightforward—you stream tokens over an HTTP response and call it a day.

Building an AI music generation platform is a different story. Generating a full track with vocals or extending an audio clip takes anywhere from 30 seconds to over 2 minutes. Handling that inside a synchronous serverless API route on Vercel or AWS Lambda will immediately hit timeout limits.

While building Alyven Music—an AI music production web app featuring a Music Generator, Song Extender, and AI Instrumental Generator—I had to solve three core engineering problems:

  1. Decoupling the UI from long-running inference jobs
  2. Deducting credits safely without double-charging on retries or failures
  3. Syncing job status to the client with minimal server overhead

Here is the exact Next.js + TypeScript architecture I use in production.

The High-Level Architecture

Instead of holding an HTTP connection open, split the request lifecycle into four stages:

  1. Reserve & Dispatch: Validate the user's balance, create a PENDING job, deduct credits atomically, and trigger the upstream AI API with a webhook callback URL.
  2. Immediate Response: Return a jobId to the frontend right away (< 200ms).
  3. Webhook Ingestion: When rendering finishes, the AI provider sends the audio URL and status to /api/webhooks/audio.
  4. Client Sync: The frontend polls a lightweight status endpoint until the job is COMPLETED or FAILED.

Step 1: Atomic Credit Deduction & Job Creation

The biggest pitfall in credit-based SaaS apps is a race condition: a user double-clicks "Generate," or the upstream API fails after you've already deducted credits.

Wrap the balance check, credit deduction, and job creation in a single database transaction, and roll back if the upstream request fails:

// app/api/generate/route.ts import { NextResponse } from "next/server"; import { db } from "@/lib/db"; // Prisma or Drizzle const GENERATION_COST = 12; export async function POST(req: Request) { const { userId, prompt, instrumental } = await req.json(); // 1. Atomic transaction: check balance, deduct credits, create job const job = await db.$transaction(async (tx) => { const user = await tx.user.findUnique({ where: { id: userId } }); if (!user || user.credits < GENERATION_COST) { throw new Error("INSUFFICIENT_CREDITS"); } await tx.user.update({ where: { id: userId }, data: { credits: { decrement: GENERATION_COST } }, }); return tx.audioJob.create({ data: { userId, prompt, status: "PENDING", cost: GENERATION_COST }, }); }); // 2. Dispatch to upstream AI audio engine try { await fetch(process.env.AUDIO_API_ENDPOINT!, { method: "POST", headers: { "Content-Type": "application/json", Authorization: `Bearer ${process.env.AUDIO_API_KEY}`, }, body: JSON.stringify({ prompt, instrumental, webhookUrl: `${process.env.NEXT_PUBLIC_APP_URL}/api/webhooks/audio?jobId=${job.id}`, }), }); return NextResponse.json({ jobId: job.id, status: "PENDING" }, { status: 202 }); } catch (error) { // 3. Rollback on dispatch failure await db.$transaction([ db.audioJob.update({ where: { id: job.id }, data: { status: "FAILED" } }), db.user.update({ where: { id: userId }, data: { credits: { increment: GENERATION_COST } } }), ]); return NextResponse.json({ error: "Failed to start generation" }, { status: 500 }); } } 

Step 2: Idempotent Webhook Handling

Upstream providers sometimes fire duplicate webhooks. Always guard your handler so a duplicate failure event doesn't refund credits twice:

// app/api/webhooks/audio/route.ts import { NextResponse } from "next/server"; import { db } from "@/lib/db"; export async function POST(req: Request) { const { searchParams } = new URL(req.url); const jobId = searchParams.get("jobId"); const payload = await req.json(); if (!jobId) return NextResponse.json({ error: "Missing jobId" }, { status: 400 }); const job = await db.audioJob.findUnique({ where: { id: jobId } }); // Idempotency guard: ignore if already processed if (!job || job.status !== "PENDING") { return NextResponse.json({ received: true }); } if (payload.status === "succeeded") { await db.audioJob.update({ where: { id: jobId }, data: { status: "COMPLETED", audioUrl: payload.audio_url, duration: payload.duration }, }); } else { await db.$transaction([ db.audioJob.update({ where: { id: jobId }, data: { status: "FAILED" } }), db.user.update({ where: { id: job.userId }, data: { credits: { increment: job.cost } } }), ]); } return NextResponse.json({ received: true }); } 

Step 3: Lightweight Client Polling in React

For jobs taking 45–90 seconds, WebSockets are usually overkill. A clean 3-second polling hook that automatically clears on completion keeps server load low and the UI responsive:

// hooks/useAudioJob.ts import { useEffect, useState } from "react"; interface JobState { status: "IDLE" | "PENDING" | "COMPLETED" | "FAILED"; audioUrl?: string; } export function useAudioJob(jobId: string | null) { const [job, setJob] = useState<JobState>({ status: "IDLE" }); useEffect(() => { if (!jobId) return; setJob({ status: "PENDING" }); let active = true; const interval = setInterval(async () => { try { const res = await fetch(`/api/jobs/${jobId}`); const data = await res.json(); if (!active) return; if (data.status === "COMPLETED" || data.status === "FAILED") { setJob(data); clearInterval(interval); } } catch (err) { console.error("Polling error:", err); } }, 3000); return () => { active = false; clearInterval(interval); }; }, [jobId]); return job; } 

Lessons Learned in Production

Running this pipeline on Alyven Music surfaced a few edge cases worth handling early:

  • Mirror generated audio to your own storage (R2/S3): Upstream AI providers often expire temporary audio URLs after 24–48 hours. Inside the webhook handler, upload the file to Cloudflare R2 or AWS S3 and store your own permanent CDN URL.
  • Add a stale-job cron: Webhooks occasionally get dropped. A cron job that checks PENDING jobs older than 10 minutes—querying the provider's status API to either finalize or refund them—prevents stuck states and support tickets.
  • Show clear progress states: Even when generation takes 60 seconds, displaying stages (Queued → Composing → Mastering) significantly reduces user page refreshes.

If you want to see how this async workflow feels in practice, you can try the live generator at alyvenmusic.com.

How are you handling long-running AI jobs in Next.js? Sticking with polling, or moving to background queues like Inngest or Trigger.dev? Let me know in the comments!