@agentmedia/schema 0.3.0 → 0.5.0

package/src/__tests__/character-pipeline.test.ts

@@ -0,0 +1,356 @@
+// Copyright 2026 agent-media contributors. Apache-2.0 license.
+
+/**
+ * Validation parity tests for the 3-step Content Machine character
+ * pipeline schemas:
+ *   - CharacterSheetSchema       (POST /v1/character/sheet-generate)
+ *   - CharacterStoryboardSchema  (POST /v1/character/storyboard-generate)
+ *   - StoryboardSuggestSchema    (POST /v1/character/storyboard-suggest)
+ *   - CharacterVideoSchema       (POST /v1/generate/character_video)
+ *
+ * These exercise mutually-exclusive sources, length bounds, enum and
+ * UUID validation, and default application — exactly the constraints
+ * the api-v2 routes also enforce. If a route's schema diverges from
+ * server-side validation in the future, this is where it gets caught
+ * before shipping.
+ */
+
+import { describe, it, expect } from 'vitest';
+import {
+  CharacterSheetSchema,
+  CharacterStoryboardSchema,
+  StoryboardSuggestSchema,
+  CharacterVideoSchema,
+} from '../video.js';
+
+const SHEET_URL = 'https://pub-16e2ed8f6be84691845e91436920ce0a.r2.dev/x/character-sheet.png';
+const STORYBOARD_URL = 'https://pub-16e2ed8f6be84691845e91436920ce0a.r2.dev/x/storyboard.png';
+const REF_URL = 'https://example.com/portrait.png';
+const SESSION = '00000000-0000-4000-8000-000000000000';
+
+// ── CharacterSheetSchema ─────────────────────────────────────────────────────
+
+describe('CharacterSheetSchema', () => {
+  it('accepts description-only', () => {
+    const r = CharacterSheetSchema.safeParse({ description: 'Marco the chef' });
+    expect(r.success).toBe(true);
+  });
+
+  it('accepts actor_slug-only', () => {
+    const r = CharacterSheetSchema.safeParse({ actor_slug: 'mei' });
+    expect(r.success).toBe(true);
+  });
+
+  it('accepts reference_image_url-only', () => {
+    const r = CharacterSheetSchema.safeParse({ reference_image_url: REF_URL });
+    expect(r.success).toBe(true);
+  });
+
+  it('accepts description + actor_slug (description adds context)', () => {
+    const r = CharacterSheetSchema.safeParse({
+      description: 'Marco the chef',
+      actor_slug: 'mei',
+    });
+    expect(r.success).toBe(true);
+  });
+
+  it('accepts description + reference_image_url', () => {
+    const r = CharacterSheetSchema.safeParse({
+      description: 'Marco the chef',
+      reference_image_url: REF_URL,
+    });
+    expect(r.success).toBe(true);
+  });
+
+  it('accepts session_id alongside any source', () => {
+    const r = CharacterSheetSchema.safeParse({
+      description: 'Marco',
+      session_id: SESSION,
+    });
+    expect(r.success).toBe(true);
+  });
+
+  it('rejects empty body (no source)', () => {
+    const r = CharacterSheetSchema.safeParse({});
+    expect(r.success).toBe(false);
+  });
+
+  it('rejects actor_slug + reference_image_url (mutex)', () => {
+    const r = CharacterSheetSchema.safeParse({
+      actor_slug: 'mei',
+      reference_image_url: REF_URL,
+    });
+    expect(r.success).toBe(false);
+    if (!r.success) {
+      expect(JSON.stringify(r.error.issues)).toMatch(/mutually exclusive/i);
+    }
+  });
+
+  it('rejects description shorter than 3 chars', () => {
+    const r = CharacterSheetSchema.safeParse({ description: 'ab' });
+    expect(r.success).toBe(false);
+  });
+
+  it('rejects description longer than 400 chars', () => {
+    const r = CharacterSheetSchema.safeParse({ description: 'x'.repeat(401) });
+    expect(r.success).toBe(false);
+  });
+
+  it('rejects non-URL reference_image_url', () => {
+    const r = CharacterSheetSchema.safeParse({ reference_image_url: 'not-a-url' });
+    expect(r.success).toBe(false);
+  });
+
+  it('rejects non-uuid session_id', () => {
+    const r = CharacterSheetSchema.safeParse({ description: 'Marco', session_id: 'nope' });
+    expect(r.success).toBe(false);
+  });
+});
+
+// ── CharacterStoryboardSchema ────────────────────────────────────────────────
+
+describe('CharacterStoryboardSchema', () => {
+  const ok = (extra: Record<string, unknown>) => ({
+    character_sheet_url: SHEET_URL,
+    ...extra,
+  });
+
+  it('accepts beats[]', () => {
+    const r = CharacterStoryboardSchema.safeParse(ok({
+      beats: ['walks in', 'takes a bite', 'thumbs up'],
+    }));
+    expect(r.success).toBe(true);
+  });
+
+  it('accepts script', () => {
+    const r = CharacterStoryboardSchema.safeParse(ok({
+      script: 'Marco walks in, takes a bite, gives a thumbs up.',
+    }));
+    expect(r.success).toBe(true);
+  });
+
+  it('applies default ratio 9:16', () => {
+    const r = CharacterStoryboardSchema.parse(ok({
+      beats: ['a', 'bb', 'ccc'].map((s) => s.repeat(3)),
+    }));
+    expect(r.ratio).toBe('9:16');
+  });
+
+  it('accepts ratio overrides', () => {
+    for (const ratio of ['9:16', '16:9', '1:1'] as const) {
+      const r = CharacterStoryboardSchema.safeParse(ok({
+        script: 'enough chars to pass min length',
+        ratio,
+      }));
+      expect(r.success).toBe(true);
+    }
+  });
+
+  it('rejects body with both beats and script (mutex)', () => {
+    const r = CharacterStoryboardSchema.safeParse(ok({
+      beats: ['walks in', 'takes a bite', 'thumbs up'],
+      script: 'a script over ten chars',
+    }));
+    expect(r.success).toBe(false);
+    if (!r.success) {
+      expect(JSON.stringify(r.error.issues)).toMatch(/exactly one/i);
+    }
+  });
+
+  it('rejects body with neither beats nor script', () => {
+    const r = CharacterStoryboardSchema.safeParse(ok({}));
+    expect(r.success).toBe(false);
+  });
+
+  it('rejects beats with fewer than 3 entries', () => {
+    const r = CharacterStoryboardSchema.safeParse(ok({ beats: ['a', 'bb'] }));
+    expect(r.success).toBe(false);
+  });
+
+  it('rejects beats with more than 10 entries', () => {
+    const r = CharacterStoryboardSchema.safeParse(ok({
+      beats: Array.from({ length: 11 }, (_, i) => `beat ${i}`),
+    }));
+    expect(r.success).toBe(false);
+  });
+
+  it('rejects beat shorter than 3 chars', () => {
+    const r = CharacterStoryboardSchema.safeParse(ok({
+      beats: ['ab', 'walks in', 'thumbs up'],
+    }));
+    expect(r.success).toBe(false);
+  });
+
+  it('rejects script shorter than 10 chars', () => {
+    const r = CharacterStoryboardSchema.safeParse(ok({ script: 'too short' }));
+    expect(r.success).toBe(false);
+  });
+
+  it('rejects script longer than 1500 chars', () => {
+    const r = CharacterStoryboardSchema.safeParse(ok({ script: 'x'.repeat(1501) }));
+    expect(r.success).toBe(false);
+  });
+
+  it('rejects bad ratio', () => {
+    const r = CharacterStoryboardSchema.safeParse(ok({
+      script: 'a script over ten chars',
+      ratio: '4:3',
+    }));
+    expect(r.success).toBe(false);
+  });
+
+  it('rejects missing character_sheet_url', () => {
+    const r = CharacterStoryboardSchema.safeParse({
+      script: 'a script over ten chars',
+    });
+    expect(r.success).toBe(false);
+  });
+
+  it('rejects non-uuid session_id', () => {
+    const r = CharacterStoryboardSchema.safeParse(ok({
+      script: 'a script over ten chars',
+      session_id: 'nope',
+    }));
+    expect(r.success).toBe(false);
+  });
+});
+
+// ── StoryboardSuggestSchema ──────────────────────────────────────────────────
+
+describe('StoryboardSuggestSchema', () => {
+  it('accepts actor_slug only', () => {
+    const r = StoryboardSuggestSchema.safeParse({ actor_slug: 'mei' });
+    expect(r.success).toBe(true);
+  });
+
+  it('accepts character_description only', () => {
+    const r = StoryboardSuggestSchema.safeParse({
+      character_description: 'Marco the Italian chef',
+    });
+    expect(r.success).toBe(true);
+  });
+
+  it('applies default duration=10 and n_panels=6', () => {
+    const r = StoryboardSuggestSchema.parse({ actor_slug: 'mei' });
+    expect(r.duration).toBe(10);
+    expect(r.n_panels).toBe(6);
+  });
+
+  it('accepts vibe + duration + n_panels overrides', () => {
+    const r = StoryboardSuggestSchema.safeParse({
+      actor_slug: 'mei', vibe: 'wholesome', duration: 5, n_panels: 4,
+    });
+    expect(r.success).toBe(true);
+  });
+
+  it('rejects both actor_slug and character_description (mutex)', () => {
+    const r = StoryboardSuggestSchema.safeParse({
+      actor_slug: 'mei', character_description: 'Marco',
+    });
+    expect(r.success).toBe(false);
+  });
+
+  it('rejects neither', () => {
+    const r = StoryboardSuggestSchema.safeParse({});
+    expect(r.success).toBe(false);
+  });
+
+  it('rejects character_description longer than 200 chars', () => {
+    const r = StoryboardSuggestSchema.safeParse({
+      character_description: 'x'.repeat(201),
+    });
+    expect(r.success).toBe(false);
+  });
+
+  it('rejects duration not in {5, 10}', () => {
+    const r = StoryboardSuggestSchema.safeParse({ actor_slug: 'mei', duration: 7 });
+    expect(r.success).toBe(false);
+  });
+
+  it('rejects n_panels < 4', () => {
+    const r = StoryboardSuggestSchema.safeParse({ actor_slug: 'mei', n_panels: 3 });
+    expect(r.success).toBe(false);
+  });
+
+  it('rejects n_panels > 10', () => {
+    const r = StoryboardSuggestSchema.safeParse({ actor_slug: 'mei', n_panels: 11 });
+    expect(r.success).toBe(false);
+  });
+});
+
+// ── CharacterVideoSchema ─────────────────────────────────────────────────────
+
+describe('CharacterVideoSchema', () => {
+  const minimal = {
+    character_sheet_url: SHEET_URL,
+    storyboard_url: STORYBOARD_URL,
+  };
+
+  it('accepts minimal body and applies defaults', () => {
+    const r = CharacterVideoSchema.parse(minimal);
+    expect(r.duration).toBe(10);
+    expect(r.aspect_ratio).toBe('9:16');
+    expect(r.generate_audio).toBe(true);
+  });
+
+  it('accepts full body', () => {
+    const r = CharacterVideoSchema.safeParse({
+      ...minimal,
+      action_prompt: 'Scene: Marco in his Brooklyn kitchen at golden hour',
+      duration: 5,
+      aspect_ratio: '16:9',
+      generate_audio: false,
+      session_id: SESSION,
+      webhook_url: 'https://hooks.example.com/cb',
+    });
+    expect(r.success).toBe(true);
+  });
+
+  it('rejects missing character_sheet_url', () => {
+    const r = CharacterVideoSchema.safeParse({ storyboard_url: STORYBOARD_URL });
+    expect(r.success).toBe(false);
+  });
+
+  it('rejects missing storyboard_url', () => {
+    const r = CharacterVideoSchema.safeParse({ character_sheet_url: SHEET_URL });
+    expect(r.success).toBe(false);
+  });
+
+  it('rejects non-URL character_sheet_url', () => {
+    const r = CharacterVideoSchema.safeParse({
+      character_sheet_url: 'not a url',
+      storyboard_url: STORYBOARD_URL,
+    });
+    expect(r.success).toBe(false);
+  });
+
+  it('rejects empty action_prompt', () => {
+    const r = CharacterVideoSchema.safeParse({ ...minimal, action_prompt: '' });
+    expect(r.success).toBe(false);
+  });
+
+  it('rejects action_prompt longer than 2000 chars', () => {
+    const r = CharacterVideoSchema.safeParse({ ...minimal, action_prompt: 'x'.repeat(2001) });
+    expect(r.success).toBe(false);
+  });
+
+  it('rejects duration not in {5, 10}', () => {
+    const r = CharacterVideoSchema.safeParse({ ...minimal, duration: 7 });
+    expect(r.success).toBe(false);
+  });
+
+  it('rejects bad aspect_ratio', () => {
+    const r = CharacterVideoSchema.safeParse({ ...minimal, aspect_ratio: '4:3' });
+    expect(r.success).toBe(false);
+  });
+
+  it('rejects non-uuid session_id', () => {
+    const r = CharacterVideoSchema.safeParse({ ...minimal, session_id: 'not-a-uuid' });
+    expect(r.success).toBe(false);
+  });
+
+  it('rejects non-https webhook_url style invalid URL', () => {
+    const r = CharacterVideoSchema.safeParse({ ...minimal, webhook_url: 'not a url' });
+    expect(r.success).toBe(false);
+  });
+});

package/src/__tests__/text-to-video.test.ts

@@ -0,0 +1,79 @@
+// Copyright 2026 agent-media contributors. Apache-2.0 license.
+
+/**
+ * Validation tests for TextToVideoSchema — the pure-prompt generator
+ * used by the "Use prompts" batch mode and the one-shot
+ * POST /v1/generate/text_to_video endpoint.
+ *
+ * The schema is intentionally simple: prompt (20-1000 chars), duration
+ * (5/10/15), aspect_ratio (9:16/16:9/1:1), generate_audio (default true).
+ */
+
+import { describe, it, expect } from 'vitest';
+import { TextToVideoSchema, TEXT_TO_VIDEO_DURATIONS, TEXT_TO_VIDEO_RATIOS } from '../video.js';
+
+const VALID_PROMPT = 'Handcrafted stylized stop-motion aesthetic with miniature practical sets, animation on 2s, warm magical lighting.';
+
+describe('TextToVideoSchema', () => {
+  it('accepts minimum valid input (prompt only — defaults fill in)', () => {
+    const r = TextToVideoSchema.safeParse({ prompt: VALID_PROMPT });
+    expect(r.success).toBe(true);
+    if (r.success) {
+      expect(r.data.duration).toBe(10);
+      expect(r.data.aspect_ratio).toBe('9:16');
+      expect(r.data.generate_audio).toBe(true);
+    }
+  });
+
+  it('rejects prompt shorter than 20 characters', () => {
+    const r = TextToVideoSchema.safeParse({ prompt: 'too short' });
+    expect(r.success).toBe(false);
+  });
+
+  it('rejects prompt longer than 1000 characters', () => {
+    const r = TextToVideoSchema.safeParse({ prompt: 'A'.repeat(1001) });
+    expect(r.success).toBe(false);
+  });
+
+  it('accepts each supported duration', () => {
+    for (const d of TEXT_TO_VIDEO_DURATIONS) {
+      const r = TextToVideoSchema.safeParse({ prompt: VALID_PROMPT, duration: d });
+      expect(r.success).toBe(true);
+    }
+  });
+
+  it('rejects duration outside the allowed set', () => {
+    const r = TextToVideoSchema.safeParse({ prompt: VALID_PROMPT, duration: 7 });
+    expect(r.success).toBe(false);
+  });
+
+  it('accepts each supported aspect_ratio', () => {
+    for (const a of TEXT_TO_VIDEO_RATIOS) {
+      const r = TextToVideoSchema.safeParse({ prompt: VALID_PROMPT, aspect_ratio: a });
+      expect(r.success).toBe(true);
+    }
+  });
+
+  it('rejects unsupported aspect_ratio', () => {
+    const r = TextToVideoSchema.safeParse({ prompt: VALID_PROMPT, aspect_ratio: '21:9' });
+    expect(r.success).toBe(false);
+  });
+
+  it('accepts generate_audio=false', () => {
+    const r = TextToVideoSchema.safeParse({ prompt: VALID_PROMPT, generate_audio: false });
+    expect(r.success).toBe(true);
+  });
+
+  it('accepts a webhook_url that is HTTPS', () => {
+    const r = TextToVideoSchema.safeParse({
+      prompt: VALID_PROMPT,
+      webhook_url: 'https://example.com/hook',
+    });
+    expect(r.success).toBe(true);
+  });
+
+  it('rejects an invalid webhook_url', () => {
+    const r = TextToVideoSchema.safeParse({ prompt: VALID_PROMPT, webhook_url: 'not-a-url' });
+    expect(r.success).toBe(false);
+  });
+});

package/src/generators.ts

@@ -9,6 +9,7 @@
  */
 
 import {
+  CharacterVideoSchema,
   CreateVideoSchema,
   LaptopUgcSchema,
   ProductActingSchema,
@@ -16,6 +17,7 @@ import {
   SaasReviewSchema,
   ShowYourAppSchema,
   SubtitleSchema,
+  TextToVideoSchema,
 } from './video.js';
 
 export const GENERATORS = {
@@ -55,6 +57,16 @@ export const GENERATORS = {
     inputSchema: LaptopUgcSchema,
     output: 'video_url' as const,
   },
+  character_video: {
+    description: 'Generate a video of a character. Pick an actor by slug, OR pass a short description and we generate a character sheet via gpt-image-2 behind the scenes. Then Seedance 2.0 animates the reference image with your storyboard text.',
+    inputSchema: CharacterVideoSchema,
+    output: 'video_url' as const,
+  },
+  text_to_video: {
+    description: 'Pure text-to-video via Seedance 2.0 — no character, no storyboard, no actor. The prompt IS the whole creative (style, subject, mood, composition). Best for stylistic / scene-driven content where you want the model to invent everything from the prompt text alone.',
+    inputSchema: TextToVideoSchema,
+    output: 'video_url' as const,
+  },
 } as const;
 
 export type GeneratorId = keyof typeof GENERATORS;

package/src/v2/character.ts

@@ -0,0 +1,41 @@
+// Copyright 2026 agent-media contributors. Apache-2.0 license.
+
+/**
+ * v2 · Character create input schema.
+ *
+ * Persists a reusable AI character. The user uploads a single photo;
+ * we generate a portrait + multi-pose character sheet (gpt-image-2),
+ * pin a Seedance seed, store everything in `user_characters`.
+ *
+ * Returns: { character_id: "char_xxxxxxxxxx" } that the user can pass
+ * to any v2 video generator (Selfie, then Product-in-hands, etc).
+ */
+
+import { z } from 'zod';
+import { V2_SHOT_PRESETS } from './selfie.js';
+
+export const CharacterCreateSchema = z.object({
+  // Optional source photo — if absent, agent-media generates the
+  // portrait from `description` alone. Pass a real person's photo
+  // ONLY when you want that exact person's likeness.
+  photo_url: z.string().url().optional(),
+
+  // Required identity
+  display_name: z
+    .string()
+    .trim()
+    .min(2)
+    .max(40)
+    .regex(
+      /^[A-Za-z0-9 _-]+$/,
+      'display_name may only contain letters, digits, spaces, underscores, or hyphens',
+    ),
+
+  description: z.string().min(8).max(400),
+
+  // Optional — defaults applied per-character if missing
+  voice_brief: z.string().min(4).max(240).optional(),
+  preset_default: z.enum(V2_SHOT_PRESETS).optional(),
+});
+
+export type CharacterCreateInput = z.infer<typeof CharacterCreateSchema>;

package/src/v2/generators.ts

@@ -0,0 +1,186 @@
+// Copyright 2026 agent-media contributors. Apache-2.0 license.
+
+/**
+ * v2 · Generator registry.
+ *
+ * Greenfield registry for the v2 product line. Lives alongside the
+ * legacy `GENERATORS` export in ../generators.ts but in its own file
+ * with a richer record shape — CLI / MCP / REST / pricing metadata
+ * baked in so the SDK, CLI, MCP server, docs and SKILL.md can all
+ * derive themselves from this one source.
+ *
+ * Old code keeps reading `GENERATORS` from ../generators.ts. New code
+ * imports `V2_GENERATORS` from here. Two surfaces, zero shared state.
+ *
+ * The new website + docs + SKILL.md only see v2.
+ */
+
+import type { z } from 'zod';
+import { SelfieSchema } from './selfie.js';
+import { CharacterCreateSchema } from './character.js';
+import { SubtitleSchema } from './subtitle.js';
+
+// ── Record shape ──────────────────────────────────────────────────────────
+
+/**
+ * Lifecycle. Two states only — by design.
+ *   `stable`: fully exposed, no warnings.
+ *   `beta`:   exposed, SDK/CLI print a one-time warning, MCP tool
+ *             description starts with "[beta]".
+ *
+ * Retired ops are deleted from the registry, not deprecated. There's
+ * no `deprecated` tier because old code stays in its own place.
+ */
+export type V2Status = 'stable' | 'beta';
+
+export interface V2GeneratorRecord {
+  id: string;
+  status: V2Status;
+
+  summary: string;       // single line, used in CLI help and tool listings
+  description: string;   // multi-line, used in docs and MCP tool registration
+
+  /** Zod schema. The contract. */
+  inputSchema: z.ZodTypeAny;
+
+  /** What the generator returns. Affects how the SDK types the response. */
+  output: 'video_url' | 'character_id' | 'subtitled_video_url';
+
+  /** CLI surface. Omit to hide from the CLI. */
+  cli?: {
+    command: string;         // e.g. "selfie", "character create"
+    fileFields?: string[];   // input fields that take --foo file.png and need upload coercion
+    examples?: string[];
+  };
+
+  /** MCP surface. Omit to hide from the MCP server. */
+  mcp?: {
+    toolName: string;        // e.g. "create_selfie"
+  };
+
+  /** REST surface. Omit to hide from the public API. */
+  rest?: {
+    method: 'POST' | 'GET';
+    path: string;            // e.g. "/v2/selfie"
+  };
+
+  /** Pricing. Single source so dashboard + CLI quoting + webhook agree. */
+  pricing?:
+    | { basis: 'per_clip'; baseCredits: number; perSecondCredits: number }
+    | { basis: 'one_shot'; baseCredits: number };
+}
+
+// ── The registry ──────────────────────────────────────────────────────────
+
+export const V2_GENERATORS: Record<string, V2GeneratorRecord> = {
+  selfie: {
+    id: 'selfie',
+    status: 'stable',
+    summary: 'AI person talking to camera, handheld iPhone-style.',
+    description:
+      'Generate a 9:16 vertical TikTok-style selfie clip. Pick a saved character (--character) ' +
+      'OR pass a photo + description inline. The pipeline composes a portrait → multi-pose ' +
+      'character sheet → per-scene wireframe, then Seedance 2.0 animates the scene with native ' +
+      'audio. Output: an mp4 hosted on R2.',
+    inputSchema: SelfieSchema,
+    output: 'video_url',
+
+    cli: {
+      command: 'selfie',
+      fileFields: ['photo_url'],
+      examples: [
+        'agent-media selfie --character char_8x2vqp --script "..."',
+        'agent-media selfie --photo me.png --description "25, ..." --script "..."',
+      ],
+    },
+    mcp: { toolName: 'create_selfie' },
+    rest: { method: 'POST', path: '/v2/selfie' },
+
+    // Cost math (list price, 70% margin floor):
+    //   5s   = $0.63 cost → 210 credits ($2.10)
+    //   8s   = $0.93 cost → 310 credits ($3.10)
+    //   12s  = $1.33 cost → 445 credits ($4.45)
+    //   15s  = $1.63 cost → 545 credits ($5.45)
+    // Linear in duration after a fixed prelude (~$0.13 of gpt-image-2 + R2)
+    // so we express as base + per-second.
+    pricing: { basis: 'per_clip', baseCredits: 75, perSecondCredits: 30 },
+  },
+
+  character_create: {
+    id: 'character_create',
+    status: 'stable',
+    summary: 'Create a reusable AI character from a single photo.',
+    description:
+      'Persists a character so subsequent video calls can reference it by id. Two gpt-image-2 ' +
+      'calls (portrait + multi-pose character sheet) are made at create time and cached in R2. ' +
+      'A pinned Seedance seed is stored on the row. Returns: { character_id }.',
+    inputSchema: CharacterCreateSchema,
+    output: 'character_id',
+
+    cli: {
+      command: 'character create',
+      fileFields: ['photo_url'],
+      examples: [
+        'agent-media character create --photo X.png --name "sofia" --description "..."',
+      ],
+    },
+    mcp: { toolName: 'create_character' },
+    rest: { method: 'POST', path: '/v2/characters' },
+
+    // ~$0.08 our cost → 27 credits at 70% margin.
+    pricing: { basis: 'one_shot', baseCredits: 27 },
+  },
+
+  subtitle: {
+    id: 'subtitle',
+    status: 'stable',
+    summary: 'Burn styled subtitles onto an existing video.',
+    description:
+      'Downloads the source video, transcribes it with Whisper (or accepts a caller-supplied ' +
+      'transcript), generates an ASS subtitle file in the chosen style (Hormozi by default; ' +
+      '17 styles available), and burns the subs into a new mp4 via ffmpeg. Output: a new ' +
+      'mp4 URL on R2. Source video is fetched once and discarded.',
+    inputSchema: SubtitleSchema,
+    output: 'video_url',
+
+    cli: {
+      // Command is `subs` (not `subtitle`) because `agent-media subtitle`
+      // is already registered by the legacy CLI surface. Both routes
+      // live in parallel: the legacy `subtitle` command calls the v1
+      // worker via /v1/generate/subtitle, the new `subs` command calls
+      // the v2 worker via /v2/subtitle.
+      command: 'subs',
+      examples: [
+        'agent-media subs --video https://r2/clip.mp4 --style hormozi',
+        'agent-media subs --video https://r2/clip.mp4 --transcript "exact script text" --style neon',
+      ],
+    },
+    mcp: { toolName: 'create_subtitle' },
+    rest: { method: 'POST', path: '/v2/subtitle' },
+
+    // Cost basis:
+    //   Whisper: $0.006 / minute of audio → trivial at < 60s
+    //   ffmpeg compute: a few cents at most for a short clip
+    //   R2 download + re-upload: rounding error
+    // Realistic our-cost for an 8s clip: < $0.01. For a 60s clip: ~$0.02.
+    // 70% margin floor → priced generously at 3 credits/sec so a casual
+    // 8s subtitle is 24 credits ($0.24) — small enough that users don't
+    // think twice.
+    pricing: { basis: 'per_clip', baseCredits: 0, perSecondCredits: 3 },
+  },
+} as const;
+
+export type V2GeneratorId = keyof typeof V2_GENERATORS;
+
+export const V2_GENERATOR_IDS = Object.keys(V2_GENERATORS) as V2GeneratorId[];
+
+/**
+ * Pricing helper. Single source for CLI quoting, webhook, dashboard.
+ */
+export function quoteV2Credits(id: V2GeneratorId, opts: { durationSeconds?: number } = {}): number {
+  const def = V2_GENERATORS[id];
+  if (!def?.pricing) return 0;
+  if (def.pricing.basis === 'one_shot') return def.pricing.baseCredits;
+  const seconds = opts.durationSeconds ?? 8;
+  return def.pricing.baseCredits + def.pricing.perSecondCredits * seconds;
+}