@hypit/hypit 0.2.8 → 0.2.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hypit/hypit",
-  "version": "0.2.8",
+  "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-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

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/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();