Text-to-Video Task Pattern

Starter source: e632762.

Both video and image examples use durable paid-task admission. They are development-only examples; cloning the starter does not enable a commercial generation provider.

Enable ENABLE_DEMO_FEATURES=true and ENABLE_TEXT2VIDEO_MOCK=true, run pnpm dev:seed -- --paid-examples, then start pnpm dev:all. The local fixture grants an idempotent manual entitlement without buying anything from Stripe. The mock returns the bundled eight-second /demo-video.mp4 clip, or TEXT2VIDEO_MOCK_URL; it does not synthesize the requested prompt, aspect, or duration.

POST /api/tasks/text-to-video requires authentication, an explicit organization, and an idempotency key in the body or Idempotency-Key header. Prompts are limited to 1,000 characters; duration is 1–60 whole seconds. The service resolves an existing request before new-operation entitlement checks. One transaction reserves monthly quota, debits pooled credits, creates the task, and persists its queue entry. Queue persistence failure rolls everything back.

Accepted work returns 202 with a queued task. The worker uses the task UUID as its provider identity, retries transient failures, and performs a deterministic credit refund before terminal failure. Poll GET /api/tasks/[uuid] for the result. The UI automatically retries transient reads and restores the task and draft settings on reload without another submission. “Generate another video” starts an explicit new intent.

Pricing remains in src/config/tasks.ts; entitlement decisions go through src/services/entitlements.ts. Execution lives in src/services/tasks/video.ts, and provider-specific code belongs in src/services/ai/video.ts. The default per-second price and plan allowances are examples to review for your own product.

Old synchronous tasks without a request fingerprint are not automatically resubmitted: reconcile their provider outcome before settling them. Deploy a worker that understands text_to_video before admitting that job type. Real adapters must preserve stable provider identities, cancellation, tenant scope, and compensation; a provider without idempotency needs outcome reconciliation before retry. Replacing the adapter alone does not enable production: replace the page, route, and service demo gates with reviewed production admission.

Related: Image workflow, Credit ledger, Plans, and Durable jobs.

An absent, empty, or whitespace-only TEXT2VIDEO_MOCK_URL uses /demo-video.mp4. Empty provider output is a failure, never a successful paid result; retries eventually compensate through the original ledger transaction.