@hypit/hypit 0.2.7 → 0.2.9

package/examples/provider-package/README.md

@@ -68,7 +68,7 @@ differ from the image example, and each is the reason the video example exists.
 **The reference vocabulary is wider, and each role maps to its own field.** The Model declares
 `referenceImage`, `referenceVideo` and `referenceAudio` as separate ports precisely so each can map
 to one wire field — a service that mixes them into one array cannot tell the roles apart. An image
-reference also carries an optional `personReference` classification, which is why those ports use
+reference also requires a boolean `personReference` classification, which is why those ports use
 `itemObject` rather than `urlArray`: the item field travels with the URL it belongs to.
 
 ```json
@@ -76,7 +76,7 @@ reference also carries an optional `personReference` classification, which is wh
 ```
 
 `firstFrame` and `lastFrame` accept at most one item each, so their body fields are URLs.
-This illustrative service accepts their optional person classification on `POST /uploads` through
+This illustrative service accepts their required visual-reference person classification on `POST /uploads` through
 `x-person-reference: true` or `false`. Their mappings declare `resourceFields: ["personReference"]`,
 and the URL resolver sends that header when supplied. Replace this with the real service’s
 documented transport; a field that the service cannot carry must be refused, never discarded.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hypit/hypit",
-  "version": "0.2.7",
+  "version": "0.2.9",
   "homepage": "https://hypit.ai",
   "repository": {
     "type": "git",

package/packages/media-execution/src/execute.ts

@@ -802,6 +802,7 @@ export async function executeRenderStillVideo(
       "select=eq(n\\,0)",
       "loop=loop=-1:size=1:start=0",
       `trim=start_frame=0:end_frame=${frames}`,
+      `settb=expr=${denominator}/${numerator}`,
       `setpts=N*${denominator}/(${numerator}*TB)`,
     ].join(",");
     let argv: string[];
@@ -1278,7 +1279,6 @@ export async function executeMuxProgramMedia(
         "-y", "-i", visualPath, "-i", audioPath,
         "-map", `0:${visual.index}`, "-map", "1:0",
         "-c:v", "copy", "-c:a", "aac", "-ar", "48000", "-ac", "2",
-        "-frames:v", String(need.visual.frameCount),
         "-movflags", "+faststart", output,
       ],
       timeoutMs: env.processTimeoutMs,

package/packages/pixverse/README.md

@@ -1,16 +1,18 @@
 # `@hypit/pixverse`
 
-Exact author/compute contracts and a package-owned author Surface for PixVerse V6.
+Exact author/compute contracts and package-owned author Surfaces for PixVerse. The package carries
+two exact models, `pixverse-v6` and `pixverse-c1`, and selects no Provider, API key or network
+execution. The selected Provider implements the exact capability.
 
-The Surface projects the primary result to an ordinary video Artifact. The package contains no
-Provider selection, API key or network execution. The selected Provider implements its exact
-capability.
-
-Connect prompt and frames as ordinary graph edges:
+Both models render 1 to 15 seconds at `360p`, `540p`, `720p` or `1080p` from a prompt of up to
+5,000 characters. `<pix:Video>` generates from the prompt, from a first frame, or from a first and
+last frame; `<pix:ReferenceVideo>` generates from the image and video subjects its `Reference`
+children carry.
 
 ```xml
 <pix:Video
   id="opening"
+  model="v6"
   prompt={line}
   duration="5"
   quality="720p"
@@ -18,17 +20,24 @@ Connect prompt and frames as ordinary graph edges:
   generate-audio="true"
 />
 
-<pix:Video id="bridge" prompt={motion} duration="5" quality="720p"
+<pix:Video id="bridge" model="c1" prompt={motion} duration="5" quality="720p"
   first-frame={hero.image} last-frame={product.image}/>
+
+<pix:ReferenceVideo id="fusion" model="v6" prompt={outfit} duration="5" quality="720p" aspect-ratio="16:9">
+  <pix:Reference image={character.image}/>
+  <pix:Reference image={clothes.image}/>
+</pix:ReferenceVideo>
 ```
 
-The Surface only lowers this syntax into the package's exact model request. It does not select a
-Provider.
+The prompt addresses the references in the order they appear, as `@ref_1`, `@ref_2` and so on. V6
+takes up to ten image references and C1 up to seven. V6 also takes up to two video references
+totalling 15 seconds; those carry the length of the run, so that element states no `duration`, and
+`aspect-ratio="auto"` takes their shape.
 
-The model renders 1 to 15 seconds at `360p`, `540p`, `720p` or `1080p`. A prompt-only run states its
-`aspect-ratio`; a run that starts from a `first-frame` takes that frame's shape instead. A
-`last-frame` bridges from the first frame into one continuous shot, so it is not combined with
-`multi-clip`, which renders the prompt as several cuts.
+A prompt-only run states its `aspect-ratio`; a run that starts from a `first-frame` takes that
+frame's shape instead. A `last-frame` bridges from the first frame into one continuous shot, as do
+subject references, so neither is combined with V6's `multi-clip`, which renders the prompt as
+several cuts. `seed` and `multi-clip` are V6's own switches.
 
 `generate-audio` renders an audio track alongside the picture, including speech the prompt asks a
 character to say. The model exposes no separate voice, language or dialogue field, so a spoken line

package/packages/pixverse/src/activation.ts

@@ -2,10 +2,12 @@ import { createMarkupSurfaceHostFacet } from "@hypit/markup";
 import {
   pixverseComponent, pixverseDefinition, pixverseManifest, pixverseModuleRef, pixverseMarkupSurfaces,
 } from "./index.js";
-import { decodePixverseVideoSurface } from "./surface.js";
+import { decodePixverseReferenceVideoSurface, decodePixverseVideoSurface } from "./surface.js";
 export const hypitPackage = { format: "hypit.node-package@1" as const, modules: [{ manifest: pixverseManifest }], components: [pixverseComponent], hostFacets: [
   pixverseDefinition.hostFacet,
   createMarkupSurfaceHostFacet({ module: pixverseModuleRef,
     declaration: pixverseMarkupSurfaces.find((item) => item.name === "video")!, handler: decodePixverseVideoSurface }),
+  createMarkupSurfaceHostFacet({ module: pixverseModuleRef,
+    declaration: pixverseMarkupSurfaces.find((item) => item.name === "reference-video")!, handler: decodePixverseReferenceVideoSurface }),
 ] };
 export default hypitPackage;

package/packages/pixverse/src/index.ts

@@ -1,117 +1,231 @@
 import { artifactTypes } from "@hypit/artifact";
 import { sealGenerationPortRequest, sealGenerationPortTable } from "@hypit/generation";
-import type { GenerationPortTable, GenerationPortValue, GenerationRequest } from "@hypit/generation";
-import type { SurfaceAttributeVocabulary } from "@hypit/markup";
+import type {
+  GenerationPort,
+  GenerationPortRequirement,
+  GenerationPortTable,
+  GenerationPortValue,
+  GenerationRequest,
+} from "@hypit/generation";
+import type { SurfaceAttributeVocabulary, SurfacePortVocabulary } from "@hypit/markup";
 import { defineExactModelModule } from "@hypit/model-kit";
 import { textTypes } from "@hypit/text";
 
+import { pixverseRequestValidator } from "./validation.js";
+
 export const pixverseModuleRef = { name: "@hypit/pixverse", version: "1" } as const;
-export const pixverseModels = ["pixverse-v6"] as const;
+export const pixverseModels = ["pixverse-v6", "pixverse-c1"] as const;
 export type PixverseModel = typeof pixverseModels[number];
 
 const PIXVERSE_QUALITIES = ["360p", "540p", "720p", "1080p"] as const;
 const PIXVERSE_ASPECT_RATIOS = ["16:9", "4:3", "1:1", "3:4", "9:16", "2:3", "3:2", "21:9"] as const;
+/** V6 reads `auto` as the shape of the reference videos it generates from. */
+const PIXVERSE_V6_ASPECT_RATIOS = [...PIXVERSE_ASPECT_RATIOS, "auto"] as const;
 
-export const pixverseV6Ports: GenerationPortTable = sealGenerationPortTable({
-  model: "pixverse-v6",
-  result: "video",
-  ports: [
-    { name: "prompt", value: { kind: "text", maxChars: 5_000 }, minItems: 1, maxItems: 1 },
-    { name: "firstFrame", value: { kind: "media", accepts: ["image"] }, minItems: 0, maxItems: 1 },
-    { name: "lastFrame", value: { kind: "media", accepts: ["image"] }, minItems: 0, maxItems: 1 },
-    { name: "duration", value: { kind: "number", integer: true, minimum: 1, maximum: 15 }, minItems: 1, maxItems: 1 },
-    { name: "quality", value: { kind: "enum", values: [...PIXVERSE_QUALITIES] }, minItems: 1, maxItems: 1 },
-    { name: "aspectRatio", value: { kind: "enum", values: [...PIXVERSE_ASPECT_RATIOS] }, minItems: 0, maxItems: 1 },
-    { name: "generateAudio", value: { kind: "boolean" }, minItems: 0, maxItems: 1 },
-    { name: "multiClip", value: { kind: "boolean" }, minItems: 0, maxItems: 1 },
-    { name: "seed", value: { kind: "number", integer: true, minimum: 0, maximum: 2_147_483_647 }, minItems: 0, maxItems: 1 },
-  ],
-  requires: [
-    // A last frame states where a run that already has a first frame ends.
-    { kind: "requiresPresent", port: "lastFrame", needs: ["firstFrame"] },
-    // A run that starts from a frame inherits that frame's shape, and one that
-    // bridges two frames renders a single continuous shot.
-    { kind: "atMostOneOf", ports: ["aspectRatio", "firstFrame"] },
-    { kind: "atMostOneOf", ports: ["multiClip", "lastFrame"] },
-  ],
-});
+/**
+ * Exact PixVerse model inputs. V6 takes up to ten reference images and up to two reference videos,
+ * and carries the sampling seed and multi-clip switch its endpoints declare. C1 takes up to seven
+ * reference images and generates from a prompt, a frame or a pair of frames.
+ */
+function pixversePortTable(model: PixverseModel): GenerationPortTable {
+  const v6 = model === "pixverse-v6";
+  const referenceVideo: readonly GenerationPort[] = v6
+    ? [{ name: "referenceVideo", value: { kind: "media", accepts: ["video"] }, minItems: 0, maxItems: 2 }]
+    : [];
+  const v6Switches: readonly GenerationPort[] = v6
+    ? [
+        { name: "multiClip", value: { kind: "boolean" }, minItems: 0, maxItems: 1 },
+        { name: "seed", value: { kind: "number", integer: true, minimum: 0, maximum: 2_147_483_647 }, minItems: 0, maxItems: 1 },
+      ]
+    : [];
+  const v6Requires: readonly GenerationPortRequirement[] = v6
+    ? [
+        // A run that bridges two frames, and one that carries subject references, is a single
+        // continuous shot rather than several cuts.
+        { kind: "atMostOneOf", ports: ["multiClip", "lastFrame"] },
+        { kind: "atMostOneOf", ports: ["multiClip", "referenceImage"] },
+        // The reference videos carry the length of the generated run.
+        { kind: "atMostOneOf", ports: ["duration", "referenceVideo"] },
+      ]
+    : [];
+  return sealGenerationPortTable({
+    model,
+    result: "video",
+    ports: [
+      { name: "prompt", value: { kind: "text", maxChars: 5_000 }, minItems: 1, maxItems: 1 },
+      { name: "firstFrame", value: { kind: "media", accepts: ["image"] }, minItems: 0, maxItems: 1 },
+      { name: "lastFrame", value: { kind: "media", accepts: ["image"] }, minItems: 0, maxItems: 1 },
+      { name: "referenceImage", value: { kind: "media", accepts: ["image"] }, minItems: 0, maxItems: v6 ? 10 : 7 },
+      ...referenceVideo,
+      // Required except in the reference-video mode, which pixverseRequestValidator states.
+      { name: "duration", value: { kind: "number", integer: true, minimum: 1, maximum: 15 }, minItems: 0, maxItems: 1 },
+      { name: "quality", value: { kind: "enum", values: [...PIXVERSE_QUALITIES] }, minItems: 1, maxItems: 1 },
+      {
+        name: "aspectRatio",
+        value: { kind: "enum", values: v6 ? [...PIXVERSE_V6_ASPECT_RATIOS] : [...PIXVERSE_ASPECT_RATIOS] },
+        minItems: 0,
+        maxItems: 1,
+      },
+      { name: "generateAudio", value: { kind: "boolean" }, minItems: 0, maxItems: 1 },
+      ...v6Switches,
+    ],
+    requires: [
+      // A last frame states where a run that already has a first frame ends.
+      { kind: "requiresPresent", port: "lastFrame", needs: ["firstFrame"] },
+      // A run that starts from a frame inherits that frame's shape.
+      { kind: "atMostOneOf", ports: ["aspectRatio", "firstFrame"] },
+      // Frames and subject references are separate ways of placing an image in the run.
+      { kind: "atMostOneOf", ports: ["referenceImage", "firstFrame"] },
+      ...v6Requires,
+    ],
+  });
+}
 
 export const pixversePorts: Readonly<Record<PixverseModel, GenerationPortTable>> = {
-  "pixverse-v6": pixverseV6Ports,
+  "pixverse-v6": pixversePortTable("pixverse-v6"),
+  "pixverse-c1": pixversePortTable("pixverse-c1"),
 };
 
 export function sealPixverseRequest(
+  model: PixverseModel,
   ports: Readonly<Record<string, readonly GenerationPortValue[]>>,
 ): GenerationRequest {
-  return sealGenerationPortRequest(pixverseV6Ports, ports);
+  return sealGenerationPortRequest(pixversePorts[model], ports);
 }
 
 const pixverseBaseDefinition = defineExactModelModule({
   module: pixverseModuleRef,
-  endpoints: [{
-    key: "video",
-    requestTypeName: "PixverseV6Request",
-    producerName: "request-pixverse-v6",
-    ports: pixverseV6Ports,
-  }],
+  endpoints: ([["v6", "pixverse-v6"], ["c1", "pixverse-c1"]] as const).map(([key, model]) => ({
+    key,
+    requestTypeName: model === "pixverse-v6" ? "PixverseV6Request" : "PixverseC1Request",
+    producerName: `request-${model}`,
+    ports: pixversePorts[model],
+    validateRequest: pixverseRequestValidator(model),
+  })),
 });
 
 export const pixverseEndpoints = pixverseBaseDefinition.endpoints;
+export const pixverseEndpointsByModel = {
+  "pixverse-v6": pixverseEndpoints.v6!,
+  "pixverse-c1": pixverseEndpoints.c1!,
+} as const;
 export const pixverseComponent = pixverseBaseDefinition.component;
-const endpoint = pixverseEndpoints.video!;
 
-const pixverseAttributes: readonly SurfaceAttributeVocabulary[] = [
+const surfaceOutputs = Object.values(pixverseEndpoints).flatMap((endpoint) => [
+  endpoint.draftType,
+  ...Object.values(endpoint.mediaBindings).map((binding) => binding.type),
+]);
+
+const pixverseCommonAttributes: readonly SurfaceAttributeVocabulary[] = [
   { name: "id", kind: "identifier", required: true,
     summary: "Names this generation so its video Artifact can be referenced elsewhere in the Source." },
+  { name: "model", kind: "literal", required: true, values: ["v6", "pixverse-v6", "c1", "pixverse-c1"],
+    summary: "Chooses the exact PixVerse model that renders the video." },
   { name: "prompt", kind: "reference", required: true, accepts: [textTypes.text],
     summary: "The Text edge describing the shot, including any spoken line the model should voice." },
-  { name: "first-frame", kind: "reference", required: false, accepts: [artifactTypes.blob],
-    summary: "Starts the video from one image Artifact." },
-  { name: "last-frame", kind: "reference", required: false, accepts: [artifactTypes.blob],
-    summary: "Ends the video on one image Artifact, bridging from the first frame." },
-  { name: "duration", kind: "literal", required: true,
-    summary: "How many seconds of video to render, from 1 to 15." },
   { name: "quality", kind: "literal", required: true, values: [...PIXVERSE_QUALITIES],
     summary: "The size band the model renders at." },
-  { name: "aspect-ratio", kind: "literal", required: false, values: [...PIXVERSE_ASPECT_RATIOS],
-    summary: "The Frame shape of the generated video." },
   { name: "generate-audio", kind: "literal", required: false, values: ["true", "false"],
     summary: "Renders an audio track alongside the picture." },
-  { name: "multi-clip", kind: "literal", required: false, values: ["true", "false"],
-    summary: "Renders the prompt as several cuts instead of one continuous shot." },
   { name: "seed", kind: "literal", required: false,
-    summary: "Seeds the model's sampling so a rerun stays close to this one." },
+    summary: "Seeds V6's sampling so a rerun stays close to this one." },
 ];
 
-export const pixverseMarkupSurfaces = [{
+const pixverseAspectRatio: SurfaceAttributeVocabulary = {
+  name: "aspect-ratio", kind: "literal", required: false, values: [...PIXVERSE_V6_ASPECT_RATIOS],
+  summary: "The Frame shape of the generated video.",
+};
+
+const pixverseVideoPort: readonly SurfacePortVocabulary[] = [{
   name: "video",
-  tag: "Video",
-  mode: "structured" as const,
-  outputs: [endpoint.draftType, endpoint.mediaBindings.firstFrame!.type, endpoint.mediaBindings.lastFrame!.type],
-  vocabulary: {
-      summary: "Generates one video with the exact PixVerse V6 model from a Text prompt, optionally starting from a frame or bridging two.",
-    attributes: pixverseAttributes,
-    ports: [{
-      name: "video",
-      type: artifactTypes.blob,
-      summary: "The generated video, addressed as `<id>.video`.",
-    }],
-    example: `<pix:Video
+  type: artifactTypes.blob,
+  summary: "The generated video, addressed as `<id>.video`.",
+}];
+
+const pixverseQualityNote = "`quality` is `360p`, `540p`, `720p` or `1080p`, and `duration` is 1 to 15 seconds.";
+const pixversePromptNote = "A spoken line belongs in the prompt; the model exposes no separate voice, language or dialogue field.";
+const pixverseModelNote = "V6 accepts `seed` and up to ten references; C1 accepts up to seven references.";
+
+export const pixverseMarkupSurfaces = [
+  {
+    name: "video",
+    tag: "Video",
+    mode: "structured" as const,
+    outputs: surfaceOutputs,
+    vocabulary: {
+      summary: "Generates one video with an exact PixVerse model from a Text prompt, optionally starting from a frame or bridging two.",
+      attributes: [
+        ...pixverseCommonAttributes,
+        { name: "duration", kind: "literal" as const, required: true,
+          summary: "How many seconds of video to render, from 1 to 15." },
+        { name: "first-frame", kind: "reference" as const, required: false, accepts: [artifactTypes.blob],
+          summary: "Starts the video from one image Artifact." },
+        { name: "last-frame", kind: "reference" as const, required: false, accepts: [artifactTypes.blob],
+          summary: "Ends the video on one image Artifact, bridging from the first frame." },
+        pixverseAspectRatio,
+        { name: "multi-clip", kind: "literal" as const, required: false, values: ["true", "false"],
+          summary: "Renders the prompt as several cuts instead of one continuous shot, on V6." },
+      ],
+      ports: pixverseVideoPort,
+      example: `<pix:Video
   id="opening"
+  model="v6"
   prompt={line}
   duration="5"
   quality="720p"
   aspect-ratio="9:16"
   generate-audio="true"
 />`,
-    notes: [
-      "A run that starts from a frame takes its shape from that frame, so `aspect-ratio` states the shape only for a prompt-only run.",
-      "A `last-frame` bridges from the `first-frame` into one continuous shot, so it is not combined with `multi-clip`.",
-      "A spoken line belongs in the prompt; the model exposes no separate voice, language or dialogue field.",
-      "The Surface lowers the element into the package's exact model request and selects no Provider.",
-    ],
+      notes: [
+        pixverseQualityNote,
+        pixverseModelNote,
+        "A run that starts from a frame takes its shape from that frame, so `aspect-ratio` states the shape only for a prompt-only run.",
+        "A `last-frame` bridges from the `first-frame` into one continuous shot, so it is not combined with `multi-clip`.",
+        pixversePromptNote,
+        "The element accepts no children and no text content.",
+      ],
+    },
+  },
+  {
+    name: "reference-video",
+    tag: "ReferenceVideo",
+    mode: "structured" as const,
+    outputs: surfaceOutputs,
+    vocabulary: {
+      summary: "Generates one video with an exact PixVerse model from a Text prompt and the image or video subjects it carries.",
+      attributes: [
+        ...pixverseCommonAttributes,
+        { name: "duration", kind: "literal" as const, required: false,
+          summary: "How many seconds of video to render, from 1 to 15; video references carry their own length." },
+        pixverseAspectRatio,
+      ],
+      children: [{
+        tag: "Reference",
+        cardinality: "many" as const,
+        summary: "Attaches one subject Artifact the model generates from, chosen by an `image` or `video` reference.",
+        attributes: [
+          { name: "image", kind: "reference" as const, required: false, accepts: [artifactTypes.blob],
+            summary: "Selects the image Artifact whose subject the generated video carries." },
+          { name: "video", kind: "reference" as const, required: false, accepts: [artifactTypes.blob],
+            summary: "Selects the video Artifact whose motion and subject the generated video carries." },
+        ],
+      }],
+      ports: pixverseVideoPort,
+      example: `<pix:ReferenceVideo id="fusion" model="v6" prompt={outfit} duration="5" quality="720p" aspect-ratio="16:9">
+  <pix:Reference image={character.image}/>
+  <pix:Reference image={clothes.image}/>
+</pix:ReferenceVideo>`,
+      notes: [
+        pixverseQualityNote,
+        pixverseModelNote,
+        "The prompt addresses the references in order as `@ref_1`, `@ref_2` and so on.",
+        "`Reference` carries exactly one of `image` or `video`, and is empty.",
+        "V6 accepts up to two video references totalling 15 seconds, which carry the length of the run in place of `duration`; `aspect-ratio=\"auto\"` takes their shape.",
+        pixversePromptNote,
+      ],
+    },
   },
-}] as const;
+] as const;
 
 export const pixverseManifest = {
   ...pixverseBaseDefinition.manifest,

package/packages/pixverse/src/surface.ts

@@ -1,6 +1,6 @@
 import { artifactTypes } from "@hypit/artifact";
 import { generationPort, sealGenerationMediaBinding, sealGenerationRequestDraft } from "@hypit/generation";
-import type { GenerationMediaPort, GenerationPortValue } from "@hypit/generation";
+import type { GenerationMediaPort, GenerationMediaRole, GenerationPortValue } from "@hypit/generation";
 import {
   createExactModelPrimaryGenerationFragment,
   exactModelMediaInputNames,
@@ -16,23 +16,31 @@ import type {
 import type { CanonicalValue, TypeRef } from "@hypit/protocol";
 import { textTypes, verifyText } from "@hypit/text";
 
-import { pixverseEndpoints } from "./index.js";
+import { pixverseEndpointsByModel } from "./index.js";
+import type { PixverseModel } from "./index.js";
+
+type MediaInput = {
+  readonly port: "firstFrame" | "lastFrame" | "referenceImage" | "referenceVideo";
+  readonly role: GenerationMediaRole;
+  readonly source: SurfaceResolvedReference;
+};
 
 function assert(condition: unknown, message: string): asserts condition {
   if (!condition) throw new Error(message);
 }
 
+function localName(name: string): string {
+  return name.includes(":") ? name.slice(name.lastIndexOf(":") + 1) : name;
+}
+
 function sameType(left: TypeRef, right: TypeRef): boolean {
   return left.name === right.name && left.module.name === right.module.name && left.module.version === right.module.version;
 }
 
-const attributes = ["id", "prompt", "first-frame", "last-frame", "duration", "quality",
-  "aspect-ratio", "generate-audio", "multi-clip", "seed"] as const;
-
-function exact(element: StructuredElement): void {
-  const unknown = Object.keys(element.attributes).filter((name) => !attributes.includes(name as typeof attributes[number]));
+function exact(element: StructuredElement, allowed: readonly string[], required: readonly string[]): void {
+  const unknown = Object.keys(element.attributes).filter((name) => !allowed.includes(name));
   assert(unknown.length === 0, `${element.name} does not accept ${unknown[0]}`);
-  const missing = ["id", "prompt", "duration", "quality"].filter((name) => element.attributes[name] === undefined);
+  const missing = required.filter((name) => element.attributes[name] === undefined);
   assert(missing.length === 0, `${element.name} requires ${missing.join(", ")}`);
 }
 
@@ -60,6 +68,10 @@ function integer(element: StructuredElement, name: string): readonly GenerationP
   return [Number(value)];
 }
 
+function optionalInteger(element: StructuredElement, name: string): readonly GenerationPortValue[] | undefined {
+  return element.attributes[name] === undefined ? undefined : integer(element, name);
+}
+
 function ref(
   element: StructuredElement,
   name: string,
@@ -73,74 +85,171 @@ function ref(
   return result;
 }
 
-function frame(
+function media(
   element: StructuredElement,
   name: string,
+  role: GenerationMediaRole,
   resolve: (path: string) => SurfaceResolvedReference | undefined,
-): SurfaceResolvedReference | undefined {
-  if (element.attributes[name] === undefined) return undefined;
-  const image = ref(element, name, artifactTypes.blob, resolve);
-  if (image.record !== undefined) {
-    assert(image.record.value.kind === "blob" && image.record.value.mediaType.startsWith("image/"),
-      `${element.name}.${name} must reference image media`);
+): SurfaceResolvedReference {
+  const artifact = ref(element, name, artifactTypes.blob, resolve);
+  if (artifact.record !== undefined) {
+    assert(artifact.record.value.kind === "blob" && artifact.record.value.mediaType.startsWith(`${role}/`),
+      `${element.name}.${name} must reference ${role} media`);
   }
-  return image;
-}
-
-function decoder(endpoint: ExactModelEndpoint): StructuredSurfaceHandler {
-  return ({ element, resolveReference }) => {
-    exact(element);
-    assert(!element.children.some((item) => item.kind === "element" || item.value.trim()),
-      `${element.name} accepts no children`);
-    const id = text(element, "id");
-    const prompt = ref(element, "prompt", textTypes.text, resolveReference);
-    if (prompt.record !== undefined) {
-      assert(prompt.record.value.kind === "inline", `${element.name}.prompt must reference Text`);
-      verifyText(prompt.record.value.value);
-    }
-    const frames = ([["firstFrame", "first-frame"], ["lastFrame", "last-frame"]] as const)
-      .flatMap(([port, attribute]) => {
-        const image = frame(element, attribute, resolveReference);
-        return image === undefined ? [] : [{ port, image }];
-      });
-    const stated: Record<string, readonly GenerationPortValue[] | undefined> = {
-      duration: integer(element, "duration"),
-      quality: [text(element, "quality")],
-      aspectRatio: optionalText(element, "aspect-ratio"),
-      generateAudio: optionalFlag(element, "generate-audio"),
-      multiClip: optionalFlag(element, "multi-clip"),
-      seed: element.attributes["seed"] === undefined ? undefined : integer(element, "seed"),
-    };
-    const draft = sealGenerationRequestDraft(endpoint.ports, Object.fromEntries(
-      Object.entries(stated).filter((entry): entry is [string, readonly GenerationPortValue[]] => entry[1] !== undefined),
-    ));
-    const records: Array<{ id: string; type: TypeRef; value: { kind: "inline"; value: CanonicalValue }; range: StructuredElement["range"] }> = [{
-      id: `${id}.draft`, type: endpoint.draftType,
-      value: { kind: "inline", value: draft as unknown as CanonicalValue }, range: element.range,
-    }];
-    const inputs: Record<string, SurfaceResolvedReference["ref"] | { kind: "record"; id: string }> = {
-      draft: { kind: "record", id: `${id}.draft` }, [exactModelTextInputName("prompt")]: prompt.ref,
-    };
-    const media = frames.map(({ port, image }, index) => {
-      const name = `media-${String(index + 1).padStart(4, "0")}`;
-      const bindingId = `${id}.${name}.binding`;
-      const mediaPort = generationPort(endpoint.ports, port);
-      assert(mediaPort.value.kind === "media", `PixVerse port ${port} is not media`);
-      records.push({
-        id: bindingId, type: endpoint.mediaBindings[port]!.type,
-        value: { kind: "inline", value: sealGenerationMediaBinding(mediaPort as GenerationMediaPort, { role: "image" }) as unknown as CanonicalValue },
-        range: element.range,
-      });
-      const names = exactModelMediaInputNames(name);
-      inputs[names.binding] = { kind: "record", id: bindingId };
-      inputs[names.artifact] = image.ref;
-      return { name, port } as const;
-    });
-    const fragment = createExactModelPrimaryGenerationFragment(endpoint, media, [{ name: "prompt", port: "prompt" }]);
-    return { records, fragments: [fragment], components: [{
-      id, fragment: fragment.id, inputs, outputs: { video: `${id}.video` }, range: element.range,
-    }] };
+  return artifact;
+}
+
+function empty(element: StructuredElement): void {
+  assert(!element.children.some((item) => item.kind === "element" || item.value.trim()),
+    `${element.name} accepts no children`);
+}
+
+function selectModel(element: StructuredElement): { endpoint: ExactModelEndpoint; model: PixverseModel } {
+  const requested = text(element, "model");
+  if (requested === "v6" || requested === "pixverse-v6") {
+    return { endpoint: pixverseEndpointsByModel["pixverse-v6"], model: "pixverse-v6" };
+  }
+  if (requested === "c1" || requested === "pixverse-c1") {
+    return { endpoint: pixverseEndpointsByModel["pixverse-c1"], model: "pixverse-c1" };
+  }
+  throw new Error(`${element.name}.model must be v6 or c1`);
+}
+
+/** A switch one model carries and the other does not is refused where it was authored. */
+function modelScoped(
+  element: StructuredElement,
+  endpoint: ExactModelEndpoint,
+  attribute: string,
+  port: string,
+  read: (element: StructuredElement, name: string) => readonly GenerationPortValue[] | undefined,
+): readonly GenerationPortValue[] | undefined {
+  if (element.attributes[attribute] === undefined) return undefined;
+  assert(endpoint.ports.ports.some((item) => item.name === port),
+    `${element.name}.${attribute} is not accepted by ${endpoint.ports.model}`);
+  return read(element, attribute);
+}
+
+function capacity(element: StructuredElement, endpoint: ExactModelEndpoint, port: string, used: number): void {
+  if (used === 0) return;
+  const declared = endpoint.ports.ports.find((item) => item.name === port);
+  assert(declared !== undefined, `${element.name} references are not accepted by ${endpoint.ports.model}`);
+  assert(used <= declared.maxItems,
+    `${element.name} accepts at most ${declared.maxItems} ${port === "referenceVideo" ? "video" : "image"} references on ${endpoint.ports.model}`);
+}
+
+function assemble(
+  element: StructuredElement,
+  endpoint: ExactModelEndpoint,
+  prompt: SurfaceResolvedReference,
+  inputs: readonly MediaInput[],
+  stated: Readonly<Record<string, readonly GenerationPortValue[] | undefined>>,
+) {
+  const id = text(element, "id");
+  const draft = sealGenerationRequestDraft(endpoint.ports, Object.fromEntries(
+    Object.entries(stated).filter((entry): entry is [string, readonly GenerationPortValue[]] => entry[1] !== undefined),
+  ));
+  const records: Array<{ id: string; type: TypeRef; value: { kind: "inline"; value: CanonicalValue }; range: StructuredElement["range"] }> = [{
+    id: `${id}.draft`, type: endpoint.draftType,
+    value: { kind: "inline", value: draft as unknown as CanonicalValue }, range: element.range,
+  }];
+  const componentInputs: Record<string, SurfaceResolvedReference["ref"] | { kind: "record"; id: string }> = {
+    draft: { kind: "record", id: `${id}.draft` }, [exactModelTextInputName("prompt")]: prompt.ref,
   };
+  const attached = inputs.map(({ port, role, source }, index) => {
+    const name = `media-${String(index + 1).padStart(4, "0")}`;
+    const bindingId = `${id}.${name}.binding`;
+    const mediaPort = generationPort(endpoint.ports, port);
+    assert(mediaPort.value.kind === "media", `PixVerse port ${port} is not media`);
+    records.push({
+      id: bindingId, type: endpoint.mediaBindings[port]!.type,
+      value: { kind: "inline", value: sealGenerationMediaBinding(mediaPort as GenerationMediaPort, { role }) as unknown as CanonicalValue },
+      range: element.range,
+    });
+    const names = exactModelMediaInputNames(name);
+    componentInputs[names.binding] = { kind: "record", id: bindingId };
+    componentInputs[names.artifact] = source.ref;
+    return { name, port } as const;
+  });
+  const fragment = createExactModelPrimaryGenerationFragment(endpoint, attached, [{ name: "prompt", port: "prompt" }]);
+  return { records, fragments: [fragment], components: [{
+    id, fragment: fragment.id, inputs: componentInputs, outputs: { video: `${id}.video` }, range: element.range,
+  }] };
+}
+
+function promptReference(
+  element: StructuredElement,
+  resolveReference: (path: string) => SurfaceResolvedReference | undefined,
+): SurfaceResolvedReference {
+  const prompt = ref(element, "prompt", textTypes.text, resolveReference);
+  if (prompt.record !== undefined) {
+    assert(prompt.record.value.kind === "inline", `${element.name}.prompt must reference Text`);
+    verifyText(prompt.record.value.value);
+  }
+  return prompt;
 }
 
-export const decodePixverseVideoSurface = decoder(pixverseEndpoints.video!);
+const VIDEO_ATTRIBUTES = ["id", "model", "prompt", "first-frame", "last-frame", "duration", "quality",
+  "aspect-ratio", "generate-audio", "multi-clip", "seed"] as const;
+
+export const decodePixverseVideoSurface: StructuredSurfaceHandler = ({ element, resolveReference }) => {
+  exact(element, VIDEO_ATTRIBUTES, ["id", "model", "prompt", "duration", "quality"]);
+  empty(element);
+  const { endpoint } = selectModel(element);
+  const frames = ([["firstFrame", "first-frame"], ["lastFrame", "last-frame"]] as const)
+    .filter(([, attribute]) => element.attributes[attribute] !== undefined)
+    .map(([port, attribute]) => ({
+      port, role: "image" as const, source: media(element, attribute, "image", resolveReference),
+    }));
+  return assemble(element, endpoint, promptReference(element, resolveReference), frames, {
+    duration: integer(element, "duration"),
+    quality: [text(element, "quality")],
+    aspectRatio: optionalText(element, "aspect-ratio"),
+    generateAudio: optionalFlag(element, "generate-audio"),
+    multiClip: modelScoped(element, endpoint, "multi-clip", "multiClip", optionalFlag),
+    seed: modelScoped(element, endpoint, "seed", "seed", optionalInteger),
+  });
+};
+
+const REFERENCE_ATTRIBUTES = ["id", "model", "prompt", "duration", "quality",
+  "aspect-ratio", "generate-audio", "seed"] as const;
+
+export const decodePixverseReferenceVideoSurface: StructuredSurfaceHandler = ({ element, resolveReference }) => {
+  exact(element, REFERENCE_ATTRIBUTES, ["id", "model", "prompt", "quality"]);
+  const { endpoint } = selectModel(element);
+  const references: MediaInput[] = [];
+  for (const child of element.children) {
+    if (child.kind === "text") {
+      assert(child.value.trim().length === 0, `${element.name} accepts only Reference children`);
+      continue;
+    }
+    assert(localName(child.name) === "Reference", `${element.name} accepts only Reference children`);
+    empty(child);
+    const roles = (["image", "video"] as const).filter((role) => child.attributes[role] !== undefined);
+    exact(child, ["image", "video"], []);
+    assert(roles.length === 1, `${child.name} requires exactly one of image, video`);
+    const role = roles[0]!;
+    references.push({
+      port: role === "image" ? "referenceImage" : "referenceVideo",
+      role,
+      source: media(child, role, role, resolveReference),
+    });
+  }
+  assert(references.length > 0, `${element.name} requires at least one Reference`);
+  for (const port of ["referenceImage", "referenceVideo"] as const) {
+    capacity(element, endpoint, port, references.filter((item) => item.port === port).length);
+  }
+  const videos = references.some((item) => item.port === "referenceVideo");
+  if (videos) {
+    assert(element.attributes["duration"] === undefined,
+      `${element.name} takes no duration; its video references carry the length of the run`);
+  } else {
+    assert(element.attributes["duration"] !== undefined, `${element.name} requires duration`);
+  }
+  return assemble(element, endpoint, promptReference(element, resolveReference), references, {
+    duration: optionalInteger(element, "duration"),
+    quality: [text(element, "quality")],
+    aspectRatio: optionalText(element, "aspect-ratio"),
+    generateAudio: optionalFlag(element, "generate-audio"),
+    seed: modelScoped(element, endpoint, "seed", "seed", optionalInteger),
+  });
+};

package/packages/pixverse/src/validation.ts

@@ -0,0 +1,13 @@
+import type { GenerationRequest } from "@hypit/generation";
+import type { PixverseModel } from "./index.js";
+
+/**
+ * Reference videos carry the length of the run, so that mode states no duration.
+ * Every other mode states its own.
+ */
+export function pixverseRequestValidator(model: PixverseModel): (request: GenerationRequest) => void {
+  return (request) => {
+    if (request.ports.referenceVideo !== undefined || request.ports.duration !== undefined) return;
+    throw new Error(`${model} requires duration`);
+  };
+}

package/packages/provider-hiapi/README.md

@@ -37,7 +37,7 @@ Service limits this Provider reports as unsupported before submitting:
   `1:3`, `9:21`; 4K excludes `1:1`, `3:1`, `1:3`, `9:21`; image-to-image takes up to six references.
 - Grok Imagine renders 480p or 720p; `grok-imagine-1.5/image-to-video` animates exactly one image.
 
-Seedance visual references may carry `person-reference`; the Provider accepts the declaration and
+Seedance visual references require `person-reference`; the Provider accepts the declaration and
 transmits nothing for it, since HiAPI has no field for it. Seedance rejects reference images and
 videos that contain a real human face; HiAPI offers no way to register authorized portrait material,
 so such a request fails with the service's moderation error.

package/packages/provider-hypihub/README.md

@@ -20,6 +20,13 @@ Seedance 2.5 (`@hypit/seedance` model `2.5`) maps to `seedance-2.5` and supports
 `480p`, `720p` and `1080p`. The Provider passes the authored `resolution` to `POST /v1/videos`;
 omitting it in the Seedance Surface defaults to `720p`.
 
+`@hypit/pixverse` models `pixverse-v6` and `pixverse-c1` map to `pixverse/v6` and `pixverse/c1` on
+`POST /v1/videos`. The model's own `quality` band travels as `resolution` and its duration as
+`seconds`; frames use `first_frame` and `last_frame`, image references use `reference_image_urls`,
+and V6's video references use `reference_videos`. A reference-video request carries no `seconds`.
+This body has no field for V6's `seed` or `multi-clip`, so a request that states either is refused
+by name before any reference is uploaded.
+
 The current HypiHub GPT Image 2 route has these service-specific limits:
 
 | Resolution | Ratios unavailable at this Endpoint | `background` |
@@ -32,7 +39,8 @@ HypiHub owns this support check independently: it leaves the GPT Image model pac
 the model or another Provider.
 
 Model identity and input mode are separate. The mapping uses HypiHub's canonical model names:
-`gpt-image-2`, `seedream-5-lite`, `minimax-h3`, `grok-imagine-video` and the individual Seedance names.
+`gpt-image-2`, `seedream-5-lite`, `minimax-h3`, `grok-imagine-video`, `pixverse/v6`,
+`pixverse/c1` and the individual Seedance names.
 An image request without references uses `/images/generations`; image edits use `/images/edits`
 with the same model name. Video requests use `/videos`, preserving reference images, reference
 videos and first/last frames in their distinct fields. Old operation-specific names are not needed
@@ -123,12 +131,11 @@ size and part concurrency, retries a failed part with a fresh signed URL, comple
 one upload, and then passes the returned HTTPS URL to generation or transcription. Signing requests
 contain at most the service's 128-part limit; all batches belong to the same upload. One
 Resource identity with the same declared person-reference classification is uploaded once within one Runtime operation. Hypit keeps no upload catalog or
-cross-Build cache. Seedance visual references can carry `personReference` in their media fields;
+cross-Build cache. Seedance visual references require boolean `personReference` in their media fields;
 the mapping declares it as a resource-transport field and the upload session receives
-`is_person_reference`, preserving true, false and omission. It stays out of the generation body.
+`is_person_reference`, preserving true and false. It stays out of the generation body.
 This covers reference images, reference videos, and first/last frames for every declared Seedance
-variant. Omission remains absent on the wire; HypiHub's upload API currently defaults it to false,
-so omission does not enable detection or person-reference preparation.
+variant. Seedance rejects omission before upload; no automatic face detection is requested.
 HypiHub stores the authored classification and prepares the applicable upstream person reference;
 this Provider does not detect faces or select an upstream private-avatar group.
 

package/packages/provider-hypihub/src/mapping.ts

@@ -8,6 +8,7 @@ const NANO_BANANA: ModuleRef = { name: "@hypit/nano-banana", version: "1" };
 const SEEDREAM: ModuleRef = { name: "@hypit/seedream", version: "1" };
 const MINIMAX: ModuleRef = { name: "@hypit/minimax-h3", version: "1" };
 const GROK: ModuleRef = { name: "@hypit/grok-imagine", version: "1" };
+const PIXVERSE: ModuleRef = { name: "@hypit/pixverse", version: "1" };
 const MIMO_SPEECH: ModuleRef = { name: "@hypit/mimo-speech", version: "1" };
 const FISHAUDIO_SPEECH: ModuleRef = { name: "@hypit/fishaudio-speech", version: "1" };
 const ELEVENLABS_SPEECH: ModuleRef = { name: "@hypit/elevenlabs-speech", version: "1" };
@@ -29,6 +30,26 @@ const seedance = (name: string): GenerationWireMapping => ({
   },
 });
 
+/**
+ * PixVerse V6 and C1 on `POST /v1/videos`. Both take the same body; V6 additionally accepts
+ * reference videos, which carry the length of the run in place of `seconds`. The model's own
+ * `quality` band is HypiHub's `resolution`.
+ */
+const pixverse = (name: string, model: string): GenerationWireMapping => ({
+  capability: { module: PIXVERSE, name }, result: "video", routes: [{ model }],
+  fields: {
+    prompt: { as: "value", field: "prompt" },
+    firstFrame: { as: "url", field: "first_frame" },
+    lastFrame: { as: "url", field: "last_frame" },
+    referenceImage: { as: "urlArray", field: "reference_image_urls" },
+    ...(name === "pixverse-v6" ? { referenceVideo: { as: "urlArray" as const, field: "reference_videos" } } : {}),
+    duration: { as: "value", field: "seconds" },
+    quality: { as: "value", field: "resolution" },
+    aspectRatio: { as: "value", field: "aspect_ratio" },
+    generateAudio: { as: "value", field: "generate_audio" },
+  },
+});
+
 export const hypiHubMappings: readonly GenerationWireMapping[] = [
   {
     capability: { module: { name: "@hypit/volcengine-matting", version: "1" }, name: "matte-portrait-video" },
@@ -42,6 +63,8 @@ export const hypiHubMappings: readonly GenerationWireMapping[] = [
   seedance("seedance-2-fast"),
   seedance("seedance-2-mini"),
   seedance("seedance-2.5"),
+  pixverse("pixverse-v6", "pixverse/v6"),
+  pixverse("pixverse-c1", "pixverse/c1"),
   {
     capability: { module: GPT_IMAGE, name: "gpt-image-2" }, result: "image", routes: [{ model: "gpt-image-2" }],
     fields: {

package/packages/provider-monid/README.md

@@ -25,7 +25,7 @@ each media input as a typed item with its `role` (`first_frame`, `last_frame`, `
 
 The Seedance endpoints add `generate_audio`. Monid documents no web search field for them, so
 `web-search="true"` is unsupported, and Seedance 2.5 frame mode (`first-frame` present) requires
-`aspect-ratio="adaptive"`. Seedance visual references may carry `person-reference`; the Provider
+`aspect-ratio="adaptive"`. Seedance visual references require `person-reference`; the Provider
 accepts the declaration and transmits nothing for it, since the endpoint has no field for it.
 Seedance rejects reference images and videos that contain a real human face; Monid offers no way to
 register authorized portrait material, so such a request fails with the upstream moderation error.

package/packages/provider-tokendance/README.md

@@ -19,7 +19,7 @@ the models the Distribution already describes.
 Video requests write the prompt and each media input as one item of the protocol's `content`
 array with its `role` (`first_frame`, `last_frame`, `reference_image`, `reference_video`,
 `reference_audio`), then `resolution`, `ratio`, `duration` and, for Seedance, `generate_audio`;
-`web-search="true"` adds `tools: [{ "type": "web_search" }]`. Seedance visual references may carry
+`web-search="true"` adds `tools: [{ "type": "web_search" }]`. Seedance visual references require
 `person-reference`; the Provider accepts the declaration and transmits nothing for it, since the Ark
 protocol has no such field. Seedance 2.0 and 2.5 reject reference images and videos that contain a
 real human face; TokenDance offers no way to register authorized portrait material, so such a request

package/packages/seedance/README.md

@@ -34,22 +34,20 @@ responsible for any additional service-specific input limits.
 
 ## Visual reference metadata
 
-Declare whether each image or video contains a person/avatar reference, including an AI-generated
-human likeness. This describes the supplied material, independently of the prompt's requested action:
+Every supplied image or video must explicitly declare `person-reference`: `true` if it contains
+a person, `false` otherwise. Classify the supplied material, not the requested result.
 
 ```xml
-<seedance:ReferenceVideo id="dance" model="mini" prompt={direction} duration="8">
+<seedance:ReferenceVideo id="take" model="mini" prompt={direction} duration="8">
   <seedance:Reference image={presenter.image} person-reference="true"/>
-  <seedance:Reference video={motion.video} person-reference="true"/>
+  <seedance:Reference video={presenter.video} person-reference="true"/>
   <seedance:Reference image={room.image} person-reference="false"/>
 </seedance:ReferenceVideo>
 ```
 
-`person-reference` is optional, accepts literal `true` or `false`, and applies to image/video, not
-voice audio. Omission carries no classification; it is distinct from explicitly declaring false.
-Inspect the actual reference when deciding the value. For `FrameVideo`, use
-`first-frame-person-reference` and `last-frame-person-reference` beside their respective frame
-inputs. A last-frame classification requires a last-frame input.
+Missing or non-boolean declarations are rejected; there is no default or automatic face detection.
+Audio must omit this field. `FrameVideo` requires `first-frame-person-reference` and, when a last
+frame is supplied, `last-frame-person-reference`. A last-frame classification requires a last frame.
 
 | Supplied visual input | Authored attribute | Request port |
 | --- | --- | --- |
@@ -66,23 +64,18 @@ These forms apply to `standard`, `fast`, `mini` and `2.5`. For example:
   last-frame={empty-room.image} last-frame-person-reference="false"/>
 ```
 
-Classify the material supplied to this request, not the intended result. A dance video with a person
-still needs `true` when used only for motion, even if the prompt asks for a different performer.
-An empty room stays `false` when the prompt asks to add a person. Inspect video across the selected
-excerpt, not only its opening frame. This flag neither detects faces nor locks or names an identity.
-Identity and action direction remain in the prompt and references.
+Inspect the selected video excerpt, not only its opening frame. An empty room stays `false` when
+the prompt asks to add a person. The flag does not lock identity; direction and references own that.
 
 The SVML author declares this parameter on each reference input. Admitted files, generated
 images/videos and reused Results use the same attributes. For a future output, declare the intended
 reference classification explicitly; if its contents are uncertain, generate and inspect that
 material before using it downstream.
 
-The model's media ports carry this as `fields.personReference`. Providers interpret it through their
-service's media handling; it is not a prompt sentence or a Core-level identity. HypiHub sends it as
+Direct requests require the same boolean in `fields.personReference`. Providers interpret it through
+their service's media handling; it is not a prompt sentence or a Core-level identity. HypiHub sends it as
 `is_person_reference` when uploading the file, then uses the returned URL in the ordinary video
 request. A project Provider maps it according to its own API.
-Omission does not request automatic face detection. HypiHub currently treats omitted upload flags
-as unmarked (`false`); declare `true` explicitly for a person reference that needs its preparation.
 
 Video references can carry motion or camera behavior while image references carry the target
 appearance. Request duration and reference-clip duration are different limits. Check the selected

package/packages/seedance/src/index.ts

@@ -17,7 +17,7 @@ export type SeedanceModel = typeof seedanceModels[number];
 
 const ASPECT_RATIOS = ["1:1", "4:3", "3:4", "16:9", "9:16", "21:9", "adaptive"] as const;
 
-const PERSON_REFERENCE_FIELDS = [{ name: "personReference", value: { kind: "boolean" }, optional: true }] as const;
+const PERSON_REFERENCE_FIELDS = [{ name: "personReference", value: { kind: "boolean" } }] as const;
 
 const SEEDANCE_25_DURATIONS = [-1, ...Array.from({ length: 27 }, (_item, index) => index + 4)] as const;
 
@@ -175,9 +175,9 @@ const seedanceCommonAttributes: readonly SurfaceAttributeVocabulary[] = [
   },
 ];
 
-const personReferenceAttribute = (name: string): SurfaceAttributeVocabulary => ({
-  name, kind: "literal", required: false, values: ["true", "false"],
-  summary: "Declares whether this visual input contains a person/avatar reference, including an AI-generated human likeness. Omission leaves it unclassified.",
+const personReferenceAttribute = (name: string, required = false): SurfaceAttributeVocabulary => ({
+  name, kind: "literal", required, values: ["true", "false"],
+  summary: "Required for each supplied image/video, including first/last frames: true if it contains a person, false otherwise. Audio must omit it.",
 });
 
 const seedanceVideoPort: readonly SurfacePortVocabulary[] = [{
@@ -235,7 +235,7 @@ export const seedanceMarkupSurfaces = [
       summary: "Generates one video with an exact Seedance model from a Text prompt and the images the video opens and closes on.",
       attributes: [
         ...seedanceCommonAttributes,
-        personReferenceAttribute("first-frame-person-reference"),
+        personReferenceAttribute("first-frame-person-reference", true),
         personReferenceAttribute("last-frame-person-reference"),
         {
           name: "first-frame",
@@ -253,7 +253,7 @@ export const seedanceMarkupSurfaces = [
         },
       ],
       ports: seedanceVideoPort,
-      example: '<seedance:FrameVideo id="bridge" model="fast" prompt={direction} duration="5" first-frame={first.image} last-frame={last.image}/>',
+      example: '<seedance:FrameVideo id="bridge" model="fast" prompt={direction} duration="5" first-frame={first.image} first-frame-person-reference="true" last-frame={last.image} last-frame-person-reference="false"/>',
       notes: [
         ...seedanceSettingNotes,
         "Both frames are ordinary image Artifact edges; the Surface copies no runtime media into request metadata.",
@@ -316,7 +316,7 @@ export const seedanceMarkupSurfaces = [
       notes: [
         ...seedanceSettingNotes,
         "The element requires at least one `Reference` child, and the model's port limits cap how many of each role it accepts.",
-        "`person-reference` applies to image/video references; voice audio carries no visual classification. The Provider transports the declared fact according to its API.",
+        "Every image/video Reference requires `person-reference=\"true|false\"`. Classify the supplied material; audio must omit the field. The Provider transports it according to its API.",
         "A `Reference` carries exactly one of `image`, `video` or `audio`, and is empty.",
       ],
     },

package/packages/seedance/src/surface.ts

@@ -146,8 +146,10 @@ function booleanAttribute(element: StructuredElement, name: string, fallback: bo
 }
 
 function personReferenceFields(element: StructuredElement, name: string) {
-  return element.attributes[name] === undefined ? undefined
-    : { personReference: booleanAttribute(element, name, false) };
+  if (element.attributes[name] === undefined) {
+    throw new Error(`${element.name}.${name} is required for this visual reference; set true if it contains a person, false otherwise`);
+  }
+  return { personReference: booleanAttribute(element, name, false) };
 }
 
 function enumeratedPort(table: GenerationPortTable, name: string): readonly (string | number)[] {
@@ -217,8 +219,8 @@ function referenceInputs(
     const kinds = accepted.filter((kind) => child.attributes[kind] !== undefined);
     if (kinds.length !== 1) throw new Error(`${child.name} requires exactly one of ${accepted.join(", ")}`);
     const role = kinds[0]!;
-    const fields = personReferenceFields(child, "person-reference");
-    if (role === "audio" && fields !== undefined) throw new Error(`${child.name}.person-reference applies to image or video, not audio`);
+    if (role === "audio" && child.attributes["person-reference"] !== undefined) throw new Error(`${child.name}.person-reference applies to image or video, not audio`);
+    const fields = role === "audio" ? undefined : personReferenceFields(child, "person-reference");
     result.push({
       ...(fields === undefined ? {} : { fields }),
       role,
@@ -242,13 +244,12 @@ function frameInputs(
 ): MediaInput[] {
   const first = mediaReference(resolved(element, "first-frame", resolveReference), "image", `${element.name}.first-frame`);
   const firstFields = personReferenceFields(element, "first-frame-person-reference");
-  const result: MediaInput[] = [{ port: "firstFrame", role: "image", source: first, ...(firstFields === undefined ? {} : { fields: firstFields }) }];
-  const lastFields = personReferenceFields(element, "last-frame-person-reference");
-  if (lastFields !== undefined && element.attributes["last-frame"] === undefined) throw new Error(`${element.name}.last-frame-person-reference requires last-frame`);
+  const result: MediaInput[] = [{ port: "firstFrame", role: "image", source: first, fields: firstFields }];
+  if (element.attributes["last-frame-person-reference"] !== undefined && element.attributes["last-frame"] === undefined) throw new Error(`${element.name}.last-frame-person-reference requires last-frame`);
   if (element.attributes["last-frame"] !== undefined) {
     result.push({
       port: "lastFrame",
-      ...(lastFields === undefined ? {} : { fields: lastFields }),
+      fields: personReferenceFields(element, "last-frame-person-reference"),
       role: "image",
       source: mediaReference(resolved(element, "last-frame", resolveReference), "image", `${element.name}.last-frame`),
     });

package/packages/seedance-kits/README.md

@@ -23,8 +23,8 @@ ordinary explicit graph edges:
 
 <seedance:ReferenceVideo id="broll" model="mini" prompt={broll-prompt}
   duration="5" resolution="720p" aspect-ratio="9:16">
-  <seedance:Reference image={scene}/>
-  <seedance:Reference image={product}/>
+  <seedance:Reference image={scene} person-reference="false"/>
+  <seedance:Reference image={product} person-reference="false"/>
 </seedance:ReferenceVideo>
 ```
 
@@ -154,7 +154,8 @@ For a multi-scene B-roll montage, `story` can name the references in scene order
 action. Choose an edit language compatible with cuts. “Continuous within each scene” and “one
 continuous shot for the whole montage” ask for different results.
 
-Visual input classification belongs to the Seedance Reference, separately from Kit text. The
+Every Seedance image/video Reference requires `person-reference="true|false"`: true if the supplied
+material contains a person, false otherwise. Audio must omit it. The
 [Seedance author package](../seedance/README.md#visual-reference-metadata) explains `person-reference`
 and its frame variants. The Kit supplies direction; the actual reference edges supply media and
 metadata. For movement-led work, a reference video can carry the motion while the text explains what

package/packages/video-cli/src/snapshot.ts

@@ -23,7 +23,7 @@ const MEDIA_TYPES: Readonly<Record<string, string>> = {
 
 async function readProject(source: string, html: string, resources: FileResourceStore): Promise<HyperframesHtmlProject> {
   const assets = [];
-  const base = /^https?:/u.test(source) ? new URL(source) : pathToFileURL(source);
+  const base = isSnapshotHtmlUrl(source) ? new URL(source) : pathToFileURL(source);
   for (const url of hyperframesHtmlAssetUrls(html)) {
     const address = new URL(url, base);
     let mediaType: string | undefined;
@@ -52,6 +52,20 @@ async function readProject(source: string, html: string, resources: FileResource
 
 const OPTIONS = ["--studio", "--to", "--at-frame", "--start-frame", "--end-frame-exclusive", "--step-frames", "--grid", "--cell", "--runtime", "--workspace"];
 
+/** Capture already treats HTTP(S) case-insensitively; snapshot must not turn HTTPS:// into a local path. */
+export function isSnapshotHtmlUrl(value: string): boolean {
+  return /^https?:\/\//iu.test(value);
+}
+
+/** `--studio` is a base URL, not a host:port token. `new URL` otherwise throws TypeError. */
+export function studioDocumentUrl(studio: string): string {
+  try {
+    return new URL("/__studio/document", studio).href;
+  } catch {
+    throw new Error(`--studio needs an http(s) Studio URL, got ${studio}`);
+  }
+}
+
 export function writeSnapshotHelp(io: CliIo): void {
   io.write(`hypit snapshot\nCapture exact frames from an existing compiled HyperFrames HTML programme through the selected Runtime Profile.\n\n`
     + `  hypit snapshot --studio <studio-url> --at-frame <n[,n,…]> --to <directory>\n`
@@ -87,8 +101,8 @@ export async function runSnapshotCli(argv: readonly string[], io: CliIo, environ
     return Number(raw);
   };
   const source = studio === undefined
-    ? /^https?:\/\//u.test(positionals[0]!) ? positionals[0]! : resolve(environment.cwd, positionals[0]!)
-    : new URL("/__studio/document", studio).href;
+    ? isSnapshotHtmlUrl(positionals[0]!) ? positionals[0]! : resolve(environment.cwd, positionals[0]!)
+    : studioDocumentUrl(studio);
   let document: HyperframesDocument | undefined;
   let html: string;
   if (studio !== undefined) {
@@ -97,7 +111,7 @@ export async function runSnapshotCli(argv: readonly string[], io: CliIo, environ
     document = await response.json() as HyperframesDocument;
     assertHyperframesDocument(document);
     html = document.html;
-  } else if (/^https?:/u.test(source)) {
+  } else if (isSnapshotHtmlUrl(source)) {
     const response = await fetch(source);
     if (!response.ok) throw new Error(`Snapshot HTML: HTTP ${response.status} ${await response.text()}`);
     html = await response.text();