𝗕𝘂𝗶𝗹𝗱𝗶𝗻𝗴 𝗮𝗻 𝗔𝗜 𝗩𝗶𝗱𝗲𝗼 𝗝𝗼𝗯 𝗤𝘂𝗲𝘂𝗲 𝗶𝗻 𝗧𝘆𝗽𝗲𝗦𝗰𝗿𝗶𝗽𝘁

AI video generation is not a standard HTTP request. A user sends a prompt and settings. The result takes minutes to arrive.

Your backend must handle several steps:

  • Validate input.
  • Create a job record.
  • Submit the job to a provider.
  • Poll for results.
  • Handle failures.
  • Show status to the user.

You should use a queue and an adapter layer. This prevents provider-specific code from breaking your entire app.

Define a core job type to act as your product contract.

type JobStatus = "queued" | "validating" | "running" | "delayed" | "succeeded" | "failed";

type VideoJob = { id: string; userId: string; model: string; prompt: string; aspectRatio: "16:9" | "9:16" | "1:1"; durationSeconds: number; status: JobStatus; providerTaskId?: string; outputUrl?: string; errorCode?: VideoJobErrorCode; };

Use an interface for your providers. This keeps your worker logic clean.

interface VideoProvider { submit(job: VideoJob): Promise<{ providerTaskId: string }>; poll(providerTaskId: string): Promise< | { status: "running" } | { status: "succeeded"; outputUrl: string } | { status: "failed"; error: unknown }

; normalizeError(error: unknown): VideoJobErrorCode; }

Follow these best practices for your workflow:

  1. Do cheap checks first. Validate prompts and durations before calling expensive APIs.

  2. Use a polling strategy. Implement a loop with increasing delays.

  3. Handle delays. If a job takes too long, move it to a "delayed" status. Use a separate worker to check delayed jobs later.

  4. Normalize errors. Never show raw provider errors to your users. Map technical errors to human-readable messages.

Example user messages:

  • "queued": Your video is waiting to start.
  • "running": Your video is being generated.
  • "delayed": This is taking longer than usual.
  • "moderation_rejected": This request could not be processed.

Treat AI video as a job system. A stable queue and clear error taxonomy make your product easier to maintain and scale.

Source: https://dev.to/miao_cunhui_587ccddb6acc1/building-an-ai-video-job-queue-in-typescript-1349