Skip to content

armgit / hypit

Public Imported from GitHub
0

Clone any viral video with AI agents. Not just a script, the whole workflow: swap the face, the words, the B-roll, ship 100 variants in one command, and get your 100M views.

feat(pixverse): add the C1 model and reference modes, and serve PixVerse on HypiHub (#326)

Sharky Wang8f1b91a8c74d
diff --git a/packages/pixverse/README.md b/packages/pixverse/README.md
index 50929101..f78c9b71 100644
--- a/packages/pixverse/README.md
+++ b/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
diff --git a/packages/pixverse/src/activation.ts b/packages/pixverse/src/activation.ts
index 62fa59be..3951d271 100644
--- a/packages/pixverse/src/activation.ts
+++ b/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;
diff --git a/packages/pixverse/src/index.ts b/packages/pixverse/src/index.ts
index 821710dd..5a72d438 100644
--- a/packages/pixverse/src/index.ts
+++ b/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,
diff --git a/packages/pixverse/src/surface.ts b/packages/pixverse/src/surface.ts
index 4b5b388c..7a58a691 100644
--- a/packages/pixverse/src/surface.ts
+++ b/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),
+ });
+};
diff --git a/packages/pixverse/src/validation.ts b/packages/pixverse/src/validation.ts
new file mode 100644
index 00000000..cae60802
--- /dev/null
+++ b/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`);
+ };
+}
diff --git a/packages/provider-hypihub/README.md b/packages/provider-hypihub/README.md
index b9a00e93..c986cb77 100644
--- a/packages/provider-hypihub/README.md
+++ b/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
diff --git a/packages/provider-hypihub/src/mapping.ts b/packages/provider-hypihub/src/mapping.ts
index 039c954e..831e0cd8 100644
--- a/packages/provider-hypihub/src/mapping.ts
+++ b/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: {