@agentmedia/schema 0.3.0 → 0.4.0

package/scripts/generate-v2-docs.ts

@@ -0,0 +1,328 @@
+#!/usr/bin/env tsx
+// Copyright 2026 agent-media contributors. Apache-2.0 license.
+
+/**
+ * Generate v2 docs + SKILL.md from V2_GENERATORS.
+ *
+ * Reads packages/schema/src/v2/generators.ts and emits:
+ *   - docs/v2/api-reference.md   — Markdown reference for the v2 REST surface
+ *   - skills/agent-media-v2/SKILL.md  — Claude skill file pointing only at v2
+ *
+ * Both files are derived. Hand edits get blown away on the next run — the
+ * single source of truth is the registry.
+ */
+
+import { writeFileSync, mkdirSync } from 'node:fs';
+import { resolve, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { zodToJsonSchema } from 'zod-to-json-schema';
+import {
+  V2_GENERATORS,
+  V2_SHOT_PRESETS,
+  V2_VIBES,
+  quoteV2Credits,
+  type V2GeneratorRecord,
+} from '../src/v2/index.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const repoRoot = resolve(__dirname, '../../..');
+
+const DOCS_OUT = resolve(repoRoot, 'docs/v2/api-reference.md');
+const SKILL_OUT = resolve(repoRoot, 'skills/agent-media-v2/SKILL.md');
+
+const GENERATED_NOTE = `<!--
+  AUTO-GENERATED — do not hand-edit.
+  Source: packages/schema/src/v2/generators.ts
+  Regenerate: pnpm --filter @agentmedia/schema gen:v2-docs
+-->`;
+
+// ── Markdown helpers ───────────────────────────────────────────────────────
+
+function fmtInputSchema(def: V2GeneratorRecord): string {
+  const schema = zodToJsonSchema(def.inputSchema, {
+    name: `${def.id}_input`,
+    $refStrategy: 'none',
+  }) as {
+    definitions?: Record<string, { properties?: Record<string, unknown>; required?: string[] }>;
+  };
+  const body = schema.definitions?.[`${def.id}_input`] ?? (schema as any);
+  return '```json\n' + JSON.stringify(body, null, 2) + '\n```';
+}
+
+function fmtPricing(def: V2GeneratorRecord): string {
+  if (!def.pricing) return '_Pricing not declared on this generator._';
+  if (def.pricing.basis === 'one_shot') {
+    const c = def.pricing.baseCredits;
+    return `One-shot: **${c} credits** ($${(c / 100).toFixed(2)})`;
+  }
+  // per_clip — show 5/8/12/15
+  const rows = [5, 8, 12, 15].map((s) => {
+    const c = quoteV2Credits(def.id as any, { durationSeconds: s });
+    return `| ${s}s | ${c} | $${(c / 100).toFixed(2)} |`;
+  });
+  return `Per-clip (base ${def.pricing.baseCredits} + ${def.pricing.perSecondCredits}/sec):\n\n| Duration | Credits | USD |\n|---|---:|---:|\n${rows.join('\n')}`;
+}
+
+// ── docs/v2/api-reference.md ──────────────────────────────────────────────
+
+function renderApiReference(): string {
+  const generators = Object.values(V2_GENERATORS);
+
+  const toc = generators
+    .map((g) => `- [\`${g.rest?.method ?? ''} ${g.rest?.path ?? '(internal)'}\` — ${g.summary}](#${g.id})`)
+    .join('\n');
+
+  const sections = generators
+    .map((g) => {
+      const status = g.status === 'beta' ? ' · _beta_' : '';
+      return [
+        `## ${g.id}${status}`,
+        '',
+        `\`${g.rest?.method ?? ''} ${g.rest?.path ?? '(internal)'}\``,
+        '',
+        g.description,
+        '',
+        '### Pricing',
+        '',
+        fmtPricing(g),
+        '',
+        '### Request body',
+        '',
+        fmtInputSchema(g),
+        '',
+        '### Response',
+        '',
+        g.output === 'video_url'
+          ? 'Returns a job submission. Poll `GET /v1/videos/{job_id}` until `status: "completed"`; the final row carries `video_url`.'
+          : 'Returns a job submission. Poll `GET /v1/videos/{job_id}` until `status: "completed"`; the final row carries the new `character_id` (`char_xxxxxxxxxx`).',
+        '',
+        '#### Submission (201)',
+        '',
+        '```json',
+        JSON.stringify(
+          {
+            job_id: '<uuid>',
+            status: 'submitted',
+            credits_deducted: g.pricing
+              ? g.pricing.basis === 'one_shot'
+                ? g.pricing.baseCredits
+                : g.pricing.baseCredits + g.pricing.perSecondCredits * 8
+              : 0,
+            generator: g.id,
+          },
+          null,
+          2,
+        ),
+        '```',
+        '',
+        ...(g.cli?.examples?.length
+          ? [
+              '### CLI examples',
+              '',
+              '```bash',
+              ...g.cli.examples,
+              '```',
+              '',
+            ]
+          : []),
+      ].join('\n');
+    })
+    .join('\n---\n\n');
+
+  return [
+    GENERATED_NOTE,
+    '',
+    '# agent-media v2 — API reference',
+    '',
+    '_Public REST surface for v2 generators (Selfie, Character). Auth is a Bearer API key (`ma_xxx`)._',
+    '',
+    '**Base URL:** `https://api.agent-media.ai`',
+    '',
+    '## Endpoints',
+    '',
+    toc,
+    '',
+    '---',
+    '',
+    sections,
+    '## Shared',
+    '',
+    '### Authentication',
+    '',
+    'Every v2 request sends `Authorization: Bearer ma_xxx`. Get a key via `agent-media login` (CLI) or the dashboard.',
+    '',
+    '### Polling',
+    '',
+    '`GET /v1/videos/{job_id}` returns the same shape for v1 and v2 jobs. v2-specific fields:',
+    '',
+    '- `character_id` — present on jobs that create a v2 character (`char_xxxxxxxxxx`).',
+    '- `video_url` — present on completed video jobs.',
+    '',
+    '### Shot grammar (Selfie)',
+    '',
+    `Selfie's \`preset\` field accepts one of:`,
+    '',
+    V2_SHOT_PRESETS.map((p) => `- \`${p}\``).join('\n'),
+    '',
+    `Or \`custom-scene:<text>\` to compose a new shot ad-hoc.`,
+    '',
+    '### Vibes (Selfie)',
+    '',
+    V2_VIBES.map((v) => `- \`${v}\``).join('\n'),
+    '',
+  ].join('\n');
+}
+
+// ── skills/agent-media-v2/SKILL.md ─────────────────────────────────────────
+
+function renderSkill(): string {
+  const generators = Object.values(V2_GENERATORS);
+  const generatorBlocks = generators
+    .map((g) => {
+      const cliExample = g.cli?.examples?.[0] ?? `agent-media ${g.cli?.command ?? g.id} …`;
+      const pricingLine = g.pricing
+        ? g.pricing.basis === 'one_shot'
+          ? `Cost: **${g.pricing.baseCredits} credits** ($${(g.pricing.baseCredits / 100).toFixed(2)}).`
+          : `Cost: **${g.pricing.baseCredits} + ${g.pricing.perSecondCredits}/sec** (8s ≈ ${quoteV2Credits(g.id as any, { durationSeconds: 8 })} credits ≈ $${(quoteV2Credits(g.id as any, { durationSeconds: 8 }) / 100).toFixed(2)}).`
+        : '';
+      return [
+        `### ${g.id}`,
+        '',
+        g.description,
+        '',
+        pricingLine,
+        '',
+        '**CLI:**',
+        '',
+        '```bash',
+        cliExample,
+        '```',
+        '',
+        '**MCP tool:** `' + (g.mcp?.toolName ?? '(none)') + '`',
+        '',
+        '**REST:** `' + (g.rest?.method ?? '') + ' ' + (g.rest?.path ?? '(internal)') + '`',
+        '',
+      ].join('\n');
+    })
+    .join('---\n\n');
+
+  return [
+    '---',
+    'name: agent-media-v2',
+    'description: AI UGC video production via agent-media v2 — Selfie videos and reusable Characters. Use this skill when the user wants to make TikTok-style "AI person talking to camera" clips or save a character for reuse across multiple generations.',
+    'homepage: https://agent-media.ai',
+    `version: 1.0.0`,
+    '---',
+    '',
+    GENERATED_NOTE,
+    '',
+    '# agent-media v2 — Selfie + Characters',
+    '',
+    'The v2 surface ships two generators today: **Selfie** (a 9:16 TikTok-style video of an AI person talking to camera) and **character_create** (persist an AI character so subsequent Selfies stay on-model). When the next v2 product lands (Product-in-hands), it appears here automatically — this file is generated from `packages/schema/src/v2/generators.ts`.',
+    '',
+    '## When to use this skill',
+    '',
+    'Trigger phrases:',
+    '- "make me a TikTok / Selfie / UGC video"',
+    '- "have an AI person say …"',
+    '- "create a character / actor / persona for reuse"',
+    '- "use the same person across multiple videos"',
+    '',
+    '## Setup',
+    '',
+    '```bash',
+    'npm install -g agent-media-cli',
+    'agent-media login            # opens browser; pastes ma_xxx into ~/.agent-media',
+    '```',
+    '',
+    'Or use the SDK directly:',
+    '',
+    '```ts',
+    "import { AgentMedia } from '@agentmedia/sdk';",
+    "const client = new AgentMedia({ apiKey: process.env.AGENT_MEDIA_API_KEY! });",
+    "const job = await client.v2.createCharacter({ photo_url: '…', display_name: 'sofia', description: '…' });",
+    "const done = await client.v2.runUntilDone(Promise.resolve(job));",
+    '```',
+    '',
+    '## Generators',
+    '',
+    generatorBlocks,
+    '## Recommended flow (multi-clip from one character)',
+    '',
+    '1. **Create the character once** with `character create`. Returns `char_xxxxxxxxxx`.',
+    '2. **Reuse that id** for every subsequent Selfie — same face, same voice, same seed.',
+    '3. If the user wants a different *look*, make a new character; don\'t mutate the existing one.',
+    '',
+    '```bash',
+    "ID=$(agent-media character create --photo me.png --name sofia \\",
+    '    --description "25, asian, long wavy dark hair, casual confident" --quiet)',
+    '',
+    'agent-media selfie --character $ID --script "Got my first 100 customers in 30 days." --preset desk-wfh-quick-pitch',
+    'agent-media selfie --character $ID --script "Here\'s how I did it."             --preset bedroom-morning-ritual',
+    '```',
+    '',
+    '## Shot grammar (Selfie)',
+    '',
+    '`--preset` accepts one of:',
+    '',
+    V2_SHOT_PRESETS.map((p) => `- \`${p}\``).join('\n'),
+    '',
+    'Or pass `--preset custom-scene:"<your scene description>"` for an ad-hoc setup.',
+    '',
+    '## Vibes',
+    '',
+    V2_VIBES.map((v) => `- \`${v}\``).join('\n'),
+    '',
+    '## Realism rubric',
+    '',
+    'Every Selfie clip is composed with these constraints baked into the prompt:',
+    '',
+    '1. Skin micro-detail visible — pores, freckles, oil sheen, baby hairs at hairline.',
+    '2. Hands always doing something — hair-touch, strap-fix, product hold.',
+    '3. Mouth caught mid-syllable when talking, not closed.',
+    '4. Eyes slightly off-center to camera, not a dead stare.',
+    '5. Single mixed light source (daylight + warm bulb).',
+    '6. Real setting (bedroom / kitchen / car / dresser-corner) — never plain wall / studio.',
+    '7. Outfit plain + matte or satin — never patterned or logo\'d.',
+    '8. Hair long, brushed, in motion.',
+    '9. Product (if any) held mid-chest, ~25° tilt.',
+    '',
+    'You don\'t need to repeat these in the script — they\'re always applied.',
+    '',
+    '## Error handling',
+    '',
+    '| Error code | What it means |',
+    '|---|---|',
+    '| `VALIDATION_ERROR` | Inputs failed Zod validation. Look at `error.issues`. |',
+    '| `INSUFFICIENT_CREDITS` | User\'s balance is below the quote. Tell them the exact amount needed. |',
+    '| `MISSING_CHARACTER_INPUT` | Selfie was called without either `--character` or `--photo + --description`. |',
+    '| `AMBIGUOUS_CHARACTER_INPUT` | Both `--character` and `--photo` were passed. Pick one. |',
+    '| `JOB_FAILED` | Worker reported failure. `error_message` carries the reason. |',
+    '| `POLL_TIMEOUT` | Job didn\'t complete within 30 minutes. Surface the job id; it may still finish. |',
+    '',
+    '## When NOT to use this skill',
+    '',
+    '- The user has an EXISTING legacy job they want to check or modify — use the v1 commands (`agent-media status`, `agent-media ugc`, etc.).',
+    '- The user wants a Show-Your-App / Product-Acting / Laptop-UGC clip — those products live in the v1 surface (separate generators, separate skill).',
+    '',
+  ].join('\n');
+}
+
+// ── Run ────────────────────────────────────────────────────────────────────
+
+function main() {
+  mkdirSync(dirname(DOCS_OUT), { recursive: true });
+  mkdirSync(dirname(SKILL_OUT), { recursive: true });
+
+  const docs = renderApiReference();
+  writeFileSync(DOCS_OUT, docs, 'utf8');
+
+  const skill = renderSkill();
+  writeFileSync(SKILL_OUT, skill, 'utf8');
+
+  console.log(`✓ wrote ${DOCS_OUT} (${docs.length} bytes)`);
+  console.log(`✓ wrote ${SKILL_OUT} (${skill.length} bytes)`);
+  console.log(`  generators emitted: ${Object.keys(V2_GENERATORS).length}`);
+}
+
+main();

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);
+  });
+});