@agentmedia/schema 0.2.2 → 0.4.0

package/src/__tests__/parity.test.ts

@@ -27,6 +27,7 @@ import {
   PIP_ANIMATIONS,
   PIP_FRAME_STYLES,
 } from '../video.js';
+import { GENERATOR_IDS, GENERATORS } from '../generators.js';
 
 // ── Helper: check if Zod accepts a body ─────────────────────────────────────
 
@@ -327,6 +328,13 @@ describe('Parity: pip_options', () => {
 // ── Enum completeness: verify schema arrays match production ────────────────
 
 describe('Enum completeness: values match production', () => {
+  it('promotes saas_review and keeps product_review as an undocumented legacy alias', () => {
+    expect(GENERATOR_IDS).toContain('saas_review');
+    expect(GENERATOR_IDS).not.toContain('product_review');
+    expect(GENERATORS.product_review.legacy).toBe(true);
+    expect(GENERATORS.product_review.inputSchema).toBe(GENERATORS.saas_review.inputSchema);
+  });
+
   it('DURATIONS matches production', () => {
     expect([...DURATIONS]).toEqual([5, 10, 15]);
   });

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,11 +9,15 @@
  */
 
 import {
+  CharacterVideoSchema,
   CreateVideoSchema,
+  LaptopUgcSchema,
   ProductActingSchema,
   ProductReviewSchema,
+  SaasReviewSchema,
   ShowYourAppSchema,
   SubtitleSchema,
+  TextToVideoSchema,
 } from './video.js';
 
 export const GENERATORS = {
@@ -22,10 +26,16 @@ export const GENERATORS = {
     inputSchema: CreateVideoSchema,
     output: 'video_url' as const,
   },
+  saas_review: {
+    description: 'Generate a SaaS review video from a SaaS product URL',
+    inputSchema: SaasReviewSchema,
+    output: 'video_url' as const,
+  },
   product_review: {
-    description: 'Generate a product review video from a product URL',
+    description: 'Legacy alias for SaaS Review video generation',
     inputSchema: ProductReviewSchema,
     output: 'video_url' as const,
+    legacy: true,
   },
   subtitle: {
     description: 'Add styled subtitles to an existing video',
@@ -42,8 +52,25 @@ export const GENERATORS = {
     inputSchema: ProductActingSchema,
     output: 'video_url' as const,
   },
+  laptop_ugc: {
+    description: 'Generate a 3-scene laptop-UGC ad: actor holds laptop showing your app, scrolling B-roll, then a face-only selfie close',
+    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;
 
-export const GENERATOR_IDS = Object.keys(GENERATORS) as GeneratorId[];
+export const GENERATOR_IDS = Object.keys(GENERATORS).filter(
+  (id) => !(GENERATORS[id as GeneratorId] as { legacy?: boolean }).legacy,
+) as GeneratorId[];

package/src/v2/character.ts

@@ -0,0 +1,39 @@
+// 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({
+  // Source photo — single file, frontal-ish, daylight ideally.
+  photo_url: z.string().url(),
+
+  // 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;
+}

package/src/v2/index.ts

@@ -0,0 +1,15 @@
+// Copyright 2026 agent-media contributors. Apache-2.0 license.
+
+/**
+ * @agent-media/schema/v2 — v2 product line surface.
+ *
+ * Old code keeps importing from `@agent-media/schema`. New code
+ * (sdk-ts/v2, sdk-python.v2, MCP loop, CLI v2 commands, api-v2
+ * /v2/* routes, new dashboard, new docs, new SKILL.md) imports
+ * exclusively from `@agent-media/schema/v2`.
+ */
+
+export * from './selfie.js';
+export * from './character.js';
+export * from './subtitle.js';
+export * from './generators.js';

package/src/v2/selfie.ts

@@ -0,0 +1,103 @@
+// Copyright 2026 agent-media contributors. Apache-2.0 license.
+
+/**
+ * v2 · Selfie input schema.
+ *
+ * The v1 Selfie product. Generates a 9:16 vertical TikTok-style clip
+ * of an AI person talking to camera in a chosen "shot grammar" preset.
+ *
+ * Validated end-to-end by the 4-stage pipeline (gpt-image-2 portrait
+ * → sheet → wireframe → Seedance 2.0 ref-to-video), see
+ * services/media-worker-v2/src/v2/selfie-pipeline.js.
+ *
+ * Two character paths:
+ *   - Bring-your-own: pass `photo_url` + `description` (we synthesize
+ *     a portrait + sheet on the fly, throwaway).
+ *   - Saved character: pass `character_id` (we load the persisted
+ *     portrait + sheet + pinned seed + voice brief from the DB).
+ *
+ * One of `photo_url + description` OR `character_id` is required.
+ */
+
+import { z } from 'zod';
+
+// ── Shot-grammar presets (locked v1 list) ────────────────────────────────
+export const V2_SHOT_PRESETS = [
+  'bedroom-morning-ritual',
+  'getting-ready-mirror-edge',
+  'bathroom-skincare-routine',
+  'bedside-lamp-evening',
+  'kitchen-glow-up',
+  'backyard-morning-coffee',
+  'picnic-blanket-outdoor',
+  'car-quick-honest-review',
+  'car-passenger-honest',
+  'outdoor-walking-talking',
+  'couch-haul-show-off',
+  'closet-fit-check',
+  'studio-apartment-tour',
+  'balcony-evening-vibes',
+  'desk-wfh-quick-pitch',
+  'cafe-window-seat',
+  'office-bathroom-discreet',
+  'gym-post-workout',
+  'salon-mirror-result',
+  'travel-hotel-room-review',
+] as const;
+export type V2ShotPreset = (typeof V2_SHOT_PRESETS)[number];
+
+export const V2_VIBES = ['excited', 'calm', 'sassy', 'serious', 'curious'] as const;
+export type V2Vibe = (typeof V2_VIBES)[number];
+
+export const V2_DURATIONS = [5, 8, 12, 15] as const;
+export type V2Duration = (typeof V2_DURATIONS)[number];
+
+// ── Input schema ──────────────────────────────────────────────────────────
+export const SelfieSchema = z
+  .object({
+    // Character — one path or the other
+    character_id: z
+      .string()
+      .regex(/^char_[A-Za-z0-9]{10,}$/, 'character_id must look like char_XXXXXXXXXX')
+      .optional(),
+    photo_url: z.string().url().optional(),
+    description: z.string().min(8).max(400).optional(),
+
+    // The line being said
+    script: z.string().min(4).max(600),
+
+    // Composition
+    preset: z.enum(V2_SHOT_PRESETS).default('bedroom-morning-ritual'),
+    vibe: z.enum(V2_VIBES).default('excited'),
+    duration: z
+      .union([z.literal(5), z.literal(8), z.literal(12), z.literal(15)])
+      .default(8),
+
+    // Voice direction (one line, natural language). Pulled from the
+    // character record when character_id is used; user can still
+    // override per-job.
+    voice_brief: z.string().min(4).max(240).optional(),
+
+    // Subtitles
+    subtitles: z.boolean().default(true),
+  })
+  .superRefine((val, ctx) => {
+    const hasSavedCharacter = !!val.character_id;
+    const hasInlineCharacter = !!val.photo_url && !!val.description;
+    if (!hasSavedCharacter && !hasInlineCharacter) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message:
+          'Provide either character_id, OR both photo_url and description.',
+      });
+    }
+    if (hasSavedCharacter && (val.photo_url || val.description)) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message:
+          'Use character_id OR (photo_url + description) — not both.',
+      });
+    }
+  });
+
+export type SelfieInput = z.infer<typeof SelfieSchema>;

package/src/v2/subtitle.ts

@@ -0,0 +1,62 @@
+// Copyright 2026 agent-media contributors. Apache-2.0 license.
+
+/**
+ * v2 · Subtitle input schema.
+ *
+ * Burns styled subtitles onto an existing video. Takes a public video
+ * URL, transcribes via Whisper (or accepts a caller-supplied transcript
+ * to skip transcription), generates an ASS subtitle file in the chosen
+ * style, and burns it into a new mp4 via ffmpeg.
+ *
+ * Output: a new mp4 URL on R2.
+ */
+
+import { z } from 'zod';
+
+// The 17 styles the ASS generator already supports (mirrors the legacy
+// SUBTITLE_STYLES list in packages/schema/src/video.ts).
+export const V2_SUBTITLE_STYLES = [
+  'hormozi',
+  'minimal',
+  'bold',
+  'karaoke',
+  'clean',
+  'tiktok',
+  'neon',
+  'fire',
+  'glow',
+  'pop',
+  'aesthetic',
+  'impact',
+  'pastel',
+  'electric',
+  'boxed',
+  'gradient',
+  'spotlight',
+] as const;
+export type V2SubtitleStyle = (typeof V2_SUBTITLE_STYLES)[number];
+
+export const SubtitleSchema = z.object({
+  // The video to subtitle. Must be a publicly-fetchable URL — R2, S3,
+  // any CDN. We download, transcribe, burn, re-host.
+  video_url: z.string().url(),
+
+  // Visual style. Defaults to hormozi because that's what most users
+  // want for short-form vertical content.
+  style: z.enum(V2_SUBTITLE_STYLES).default('hormozi'),
+
+  // Optional override. When set, we skip Whisper and use this text as
+  // the transcript. Useful when the caller already has the script
+  // (e.g. they just generated the video from a known script).
+  transcript: z.string().min(1).max(5000).optional(),
+
+  // Spoken language hint for Whisper. ISO 639-1 (`en`, `es`, `pt`,
+  // …) or null to let Whisper detect. Most callers pass null.
+  language: z
+    .string()
+    .length(2)
+    .regex(/^[a-z]{2}$/, 'language must be a lowercase ISO 639-1 code')
+    .optional(),
+});
+
+export type SubtitleInput = z.infer<typeof SubtitleSchema>;