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(wan): add the Wan 2.7 image models and serve them on Monid (#301)

Sharky Wangc86239820dd7
diff --git a/docs/guide/service-partners.md b/docs/guide/service-partners.md
index a971f422..97b0fb4f 100644
--- a/docs/guide/service-partners.md
+++ b/docs/guide/service-partners.md
@@ -49,8 +49,8 @@ public URL only, so a request with reference media needs a URL the embedding cal
[Its documentation](https://monid.ai/docs) describes discovering tools, inspecting their inputs and
prices, and calling them through its interfaces.
[`@hypit/provider-monid`](https://github.com/hypit-ai/hypit/blob/main/packages/provider-monid/README.md)
-serves the Seedance 2.0 and 2.5 endpoints and MiniMax H3, and uploads reference media through
-Monid's workspace file system. For another Monid tool, its
+serves the Seedance 2.0 and 2.5 endpoints, MiniMax H3 and the Wan 2.7 image models, and uploads
+reference media through Monid's workspace file system. For another Monid tool, its
[HTTP API documentation](https://monid.ai/docs/api/overview) supplies the connection details, and
the Agent can implement the required request and result mapping in a project package.
diff --git a/docs/zh/guide/service-partners.md b/docs/zh/guide/service-partners.md
index cd24e1a0..92d6c4b0 100644
--- a/docs/zh/guide/service-partners.md
+++ b/docs/zh/guide/service-partners.md
@@ -42,7 +42,7 @@ Pollo 只接受公网 URL 形式的参考素材,带参考素材的请求需要
[Monid](https://monid.ai) 是 Hypit 的服务合作方。
[它的文档](https://monid.ai/docs)介绍了工具发现、输入与价格查询,以及调用方式。
[`@hypit/provider-monid`](https://github.com/hypit-ai/hypit/blob/main/packages/provider-monid/README.md)
-提供 Seedance 2.0、2.5 系列端点与 MiniMax H3,并通过 Monid 的工作区文件系统上传参考素材。
+提供 Seedance 2.0、2.5 系列端点、MiniMax H3 与 Wan 2.7 图像模型,并通过 Monid 的工作区文件系统上传参考素材。
使用 Monid 的其他工具时,[HTTP API 文档](https://monid.ai/docs/api/overview)提供接入依据,
Agent 可以在项目包中实现这次所需的请求与结果映射。
diff --git a/package.json b/package.json
index b2cdd457..1da0902d 100644
--- a/package.json
+++ b/package.json
@@ -279,6 +279,7 @@
"@hypit/typography-track-studio": "workspace:*",
"@hypit/visual-ir": "workspace:*",
"@hypit/volcengine-matting": "workspace:*",
+ "@hypit/wan": "workspace:*",
"@hypit/whisperx": "workspace:*",
"@types/node": "24.10.1",
"rollup": "4.62.4",
diff --git a/packages/provider-monid/README.md b/packages/provider-monid/README.md
index daceed14..45a2879f 100644
--- a/packages/provider-monid/README.md
+++ b/packages/provider-monid/README.md
@@ -2,7 +2,7 @@
Hypit Runtime Provider for a [Monid](https://monid.ai) workspace. It runs Monid's generation
endpoints through `POST /v1/run`, polls `GET /v1/runs/{runId}` until the run is terminal, downloads
-the returned video and stores it in the current Build.
+every returned file and stores it in the current Build.
| Capability | Monid endpoint |
| --- | --- |
@@ -11,16 +11,17 @@ the returned video and stores it in the current Build.
| `@hypit/seedance@1#seedance-2-mini` | `bytedance` `/v1/video/seedance-2.0-mini` |
| `@hypit/seedance@1#seedance-2.5` | `bytedance` `/v1/video/seedance-2.5` |
| `@hypit/minimax-h3@1#minimax-h3` | `minimax` `/v1/video/minimax-h3` |
+| `@hypit/wan@1#wan-2.7-image` | `alibaba` `/v1/image/wan2.7-image` |
+| `@hypit/wan@1#wan-2.7-image-pro` | `alibaba` `/v1/image/wan2.7-image-pro` |
Monid's catalogue lists further generation endpoints, including the H3 Fast, Max and Max Turbo
-variants and Hailuo 2.3; their models are not the ones the Distribution describes. Input schemas
-are published through the authenticated `inspect` operation, which is where the request bodies
-above come from.
+variants, Hailuo 2.3 and the Kling, Gemini and Qwen families; their models are not the ones the
+Distribution describes. Input schemas are published through the authenticated `inspect` operation,
+which is where the request bodies below come from.
-Every mapped endpoint relays a BytePlus ModelArk request: one `content` array holding the prompt
-and each media input as a typed item with its `role` (`first_frame`, `last_frame`,
-`reference_image`, `reference_video`, `reference_audio`), then `resolution`, `ratio` and
-`duration`.
+The video endpoints relay a BytePlus ModelArk request: one `content` array holding the prompt and
+each media input as a typed item with its `role` (`first_frame`, `last_frame`, `reference_image`,
+`reference_video`, `reference_audio`), then `resolution`, `ratio` and `duration`.
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
@@ -37,6 +38,17 @@ text-to-video request carrying no `aspect-ratio` is reported unsupported before
resolved, and the other two modes are sent as `adaptive`. H3 returns its video at `content.url`
rather than the ModelArk `video_url`.
+The Wan image endpoints take their fields directly: `prompt`, `images` as plain URLs, `size` for the
+band, `n`, `enable_sequential`, `thinking_mode`, `watermark` and `seed`. Both variants accept the
+same fields, and the Pro variant adds the `4K` band. Two service limits are reported before any
+reference is resolved: `4K` renders from a prompt alone, without reference images or an image set,
+and a request renders at most four pictures outside an image set. An image set returns several
+files, so collection downloads each one.
+
+The endpoints also document a custom colour palette and per-image bounding boxes. Neither has a
+representation in the model port vocabulary, which carries scalars and media rather than object
+arrays, so the Provider transmits neither.
+
Reference media are uploaded through the workspace file system Monid provides for this purpose
(`sfs`): `/put` signs an upload for `hypit/<resource>.<ext>`, the bytes are `PUT` to that URL, and
`/cat` mints a one-day download URL that the generation endpoint fetches. Uploaded files stay in the
diff --git a/packages/provider-monid/package.json b/packages/provider-monid/package.json
index 3fa4577c..482cec17 100644
--- a/packages/provider-monid/package.json
+++ b/packages/provider-monid/package.json
@@ -12,7 +12,8 @@
"@hypit/minimax-h3": "workspace:*",
"@hypit/protocol": "workspace:*",
"@hypit/runtime": "workspace:*",
- "@hypit/runtime-kit": "workspace:*"
+ "@hypit/runtime-kit": "workspace:*",
+ "@hypit/wan": "workspace:*"
},
"devDependencies": {
"@hypit/seedance": "workspace:*"
diff --git a/packages/provider-monid/src/mapping.ts b/packages/provider-monid/src/mapping.ts
index 99140967..a1649587 100644
--- a/packages/provider-monid/src/mapping.ts
+++ b/packages/provider-monid/src/mapping.ts
@@ -3,6 +3,7 @@ import type { GenerationWireMapping } from "@hypit/generation";
const SEEDANCE: ModuleRef = { name: "@hypit/seedance", version: "1" };
const MINIMAX_H3: ModuleRef = { name: "@hypit/minimax-h3", version: "1" };
+const WAN: ModuleRef = { name: "@hypit/wan", version: "1" };
/**
* One mapping plus the Monid provider that relays the endpoint. Monid addresses an endpoint by
@@ -57,10 +58,33 @@ const minimaxH3: MonidMapping = {
},
};
+/**
+ * Monid's `alibaba` Wan 2.7 image endpoints. Both variants take the same fields; the Pro variant
+ * adds a 4K band. Input images are plain public URLs rather than role-tagged items, and the model
+ * reads exclusions from the prompt, so it has no negative-prompt field.
+ */
+const wan = (name: string, endpoint: string): MonidMapping => ({
+ service: "alibaba",
+ capability: { module: WAN, name }, result: "image",
+ routes: [{ model: endpoint }],
+ fields: {
+ prompt: { as: "value", field: "prompt" },
+ images: { as: "urlArray", field: "images" },
+ resolution: { as: "value", field: "size" },
+ count: { as: "value", field: "n" },
+ imageSet: { as: "value", field: "enable_sequential" },
+ extendedReasoning: { as: "value", field: "thinking_mode" },
+ watermark: { as: "value", field: "watermark" },
+ seed: { as: "value", field: "seed" },
+ },
+});
+
export const monidMappings: readonly MonidMapping[] = [
seedance("seedance-2", "/v1/video/seedance-2.0"),
seedance("seedance-2-fast", "/v1/video/seedance-2.0-fast"),
seedance("seedance-2-mini", "/v1/video/seedance-2.0-mini"),
seedance("seedance-2.5", "/v1/video/seedance-2.5"),
minimaxH3,
+ wan("wan-2.7-image", "/v1/image/wan2.7-image"),
+ wan("wan-2.7-image-pro", "/v1/image/wan2.7-image-pro"),
];
diff --git a/packages/provider-monid/src/provider.ts b/packages/provider-monid/src/provider.ts
index 0d2ff5d6..023070a0 100644
--- a/packages/provider-monid/src/provider.ts
+++ b/packages/provider-monid/src/provider.ts
@@ -31,7 +31,7 @@ type Handle = {
readonly runId: string;
readonly route: string;
readonly startedAt: number;
- readonly url?: string;
+ readonly urls?: readonly string[];
};
function assert(condition: unknown, message: string): asserts condition { if (!condition) throw new Error(message); }
@@ -66,13 +66,21 @@ function httpsUrl(value: unknown, subject: string): string {
return value;
}
/**
- * The relayed result. The ModelArk endpoints return the task's `video_url`; MiniMax-H3 returns the
- * video at `content.url`. The link expires, so collection downloads it rather than storing it.
+ * The relayed result. The ModelArk endpoints return the task's `video_url` and MiniMax-H3 its
+ * `content.url`; an image endpoint returns one entry per rendered picture. Every link expires, so
+ * collection downloads them rather than storing the addresses.
*/
-function outputVideoUrl(run: Record<string, unknown>): string {
+function outputUrls(run: Record<string, unknown>): readonly string[] {
const output = object(run.output, "Monid run output");
const content = output.content === undefined ? undefined : object(output.content, "Monid run output content");
- return httpsUrl(output.video_url ?? content?.video_url ?? content?.url, "Monid run output");
+ const listed = [output.results, output.images, output.urls, content?.results, content?.images]
+ .find((value): value is readonly unknown[] => Array.isArray(value) && value.length > 0);
+ if (listed !== undefined) {
+ return listed.map((item, index) => httpsUrl(
+ typeof item === "string" ? item : object(item, `Monid run output ${index}`).url,
+ `Monid run output ${index}`));
+ }
+ return [httpsUrl(output.video_url ?? output.url ?? content?.video_url ?? content?.url, "Monid run output")];
}
const extensions: Readonly<Record<string, string>> = {
"image/jpeg": "jpg", "image/png": "png", "image/webp": "webp", "video/mp4": "mp4", "video/quicktime": "mov",
@@ -180,7 +188,7 @@ function endpoint(client: MonidClient, pollIntervalMs: number, maxOperationMs: n
if (!ended) return { ...wakeAfter(canonicalize(handle), pollIntervalMs, Date.now(), { phase: String(run.status) }), receipt };
const rejected = monidRunFailure(run, handle.runId);
if (rejected !== undefined) return { ...failure(rejected), receipt };
- return { status: "ready", handle: canonicalize({ ...handle, url: outputVideoUrl(run) }), receipt };
+ return { status: "ready", handle: canonicalize({ ...handle, urls: outputUrls(run) }), receipt };
} catch (error) {
return failure(error);
}
@@ -201,7 +209,7 @@ function endpoint(client: MonidClient, pollIntervalMs: number, maxOperationMs: n
}
const rejected = monidRunFailure(run, handle.runId);
if (rejected !== undefined) return { ...failure(rejected), receipt };
- return { status: "ready", handle: canonicalize({ ...handle, url: outputVideoUrl(run) }), receipt };
+ return { status: "ready", handle: canonicalize({ ...handle, urls: outputUrls(run) }), receipt };
} catch (error) {
return failure(error);
}
@@ -211,10 +219,15 @@ function endpoint(client: MonidClient, pollIntervalMs: number, maxOperationMs: n
const handle = object(context.handle, "Monid handle") as unknown as Handle;
const route = monidRouteForCapability(context.need.capability);
assert(route !== undefined && handle.route === route.key, "Monid collection route differs");
- await context.reportProgress?.({ phase: "Receiving generated video" });
- const downloaded = await client.download(httpsUrl(handle.url, "Monid handle"));
- const blob = await context.resources.put(downloaded.bytes, downloaded.mediaType);
- return { status: "completed", result: { value: route.packageResult([blob]) }, receipt: { id: handle.runId } };
+ const urls = handle.urls ?? [];
+ assert(urls.length > 0, "Monid handle carries no result");
+ await context.reportProgress?.({ phase: `Receiving ${urls.length} generated ${route.media}${urls.length === 1 ? "" : "s"}` });
+ const blobs: BlobRef[] = [];
+ for (const url of urls) {
+ const downloaded = await client.download(httpsUrl(url, "Monid handle"));
+ blobs.push(await context.resources.put(downloaded.bytes, downloaded.mediaType));
+ }
+ return { status: "completed", result: { value: route.packageResult(blobs) }, receipt: { id: handle.runId } };
} catch (error) {
return failure(error);
}
diff --git a/packages/provider-monid/src/routes.ts b/packages/provider-monid/src/routes.ts
index 99351764..72564b89 100644
--- a/packages/provider-monid/src/routes.ts
+++ b/packages/provider-monid/src/routes.ts
@@ -2,6 +2,7 @@ import {
compileWireRequest,
selectWireModelForRequest,
generationTypes,
+ sealGeneratedImageSet,
sealGeneratedVideoSet,
} from "@hypit/generation";
import type { GenerationArtifactUrlResolver, GenerationRequest } from "@hypit/generation";
@@ -22,6 +23,8 @@ export type MonidPreparedRequest = {
export type MonidRoute = MonidMapping & {
readonly key: string;
readonly returns: TypeRef;
+ /** What the run produces, which decides how many results collection expects. */
+ readonly media: "image" | "video";
readonly supports: (request: EndpointRequest) => EndpointSupport;
readonly prepare: (constraints: CanonicalValue) => MonidPreparedRequest;
readonly packageResult: (artifacts: readonly BlobRef[]) => StoredValue;
@@ -42,7 +45,20 @@ function referenceToVideo(request: GenerationRequest): boolean {
return present(request, "referenceImage") || present(request, "referenceVideo") || present(request, "referenceAudio");
}
+function wanRejection(mapping: MonidMapping, request: GenerationRequest): string | undefined {
+ const set = scalar(request, "imageSet") === true;
+ if (scalar(request, "resolution") === "4K" && (present(request, "images") || set)) {
+ return "Wan renders 4K from a prompt alone, without reference images or an image set";
+ }
+ const count = scalar(request, "count");
+ if (typeof count === "number" && count > 4 && !set) {
+ return `Wan renders at most 4 pictures outside an image set, not ${count}`;
+ }
+ return undefined;
+}
+
function rejection(mapping: MonidMapping, request: GenerationRequest): string | undefined {
+ if (mapping.capability.module.name === "@hypit/wan") return wanRejection(mapping, request);
if (mapping.capability.name === "minimax-h3") {
// MiniMax-H3 resolves the framing from the uploaded image in frame mode and defaults
// reference-to-video to adaptive. Text-to-video carries no such source, and the endpoint
@@ -103,7 +119,8 @@ function capabilityKey(capability: CapabilityRef): string {
export const monidRoutes: readonly MonidRoute[] = monidMappings.map((mapping) => ({
...mapping,
key: capabilityKey(mapping.capability),
- returns: generationTypes.videoSet,
+ returns: mapping.result === "image" ? generationTypes.imageSet : generationTypes.videoSet,
+ media: mapping.result === "image" ? "image" as const : "video" as const,
supports: (request) => {
const reason = rejection(mapping, request.constraints as unknown as GenerationRequest);
return reason === undefined ? { status: "supported" } : { status: "unsupported", reason };
@@ -112,7 +129,10 @@ export const monidRoutes: readonly MonidRoute[] = monidMappings.map((mapping) =>
const request = constraints as unknown as GenerationRequest;
const reason = rejection(mapping, request);
if (reason !== undefined) throw new Error(reason);
- const body = mapping.capability.name === "minimax-h3" ? minimaxH3Input : arkInput;
+ // The Wan endpoints take the compiled fields as their body; the ModelArk endpoints fold their
+ // media into one role-tagged `content` array first.
+ const body = mapping.capability.module.name === "@hypit/wan" ? (input: Record<string, unknown>) => input
+ : mapping.capability.name === "minimax-h3" ? minimaxH3Input : arkInput;
return {
service: mapping.service,
endpoint: selectWireModelForRequest(mapping, request),
@@ -121,7 +141,9 @@ export const monidRoutes: readonly MonidRoute[] = monidMappings.map((mapping) =>
},
packageResult: (artifacts) => ({
kind: "inline",
- value: canonicalize(sealGeneratedVideoSet({ videos: artifacts })),
+ value: canonicalize(mapping.result === "image"
+ ? sealGeneratedImageSet({ images: artifacts })
+ : sealGeneratedVideoSet({ videos: artifacts })),
}),
}));
diff --git a/packages/provider-monid/test/routes.test.ts b/packages/provider-monid/test/routes.test.ts
index e644dd1f..93c16c4a 100644
--- a/packages/provider-monid/test/routes.test.ts
+++ b/packages/provider-monid/test/routes.test.ts
@@ -4,6 +4,7 @@ import { assertMappingCoversPorts } from "@hypit/generation";
import type { BlobRef, CanonicalValue } from "@hypit/protocol";
import { minimaxH3Ports, sealMinimaxH3Request } from "@hypit/minimax-h3";
import { seedancePorts, sealSeedanceRequest } from "@hypit/seedance";
+import { wanPorts } from "@hypit/wan";
import { monidMappings } from "../src/mapping.js";
import { monidRouteForCapability } from "../src/routes.js";
@@ -15,7 +16,9 @@ test("every Monid mapping covers its model's ports", () => {
for (const mapping of monidMappings) {
const ports = mapping.capability.module.name === "@hypit/minimax-h3"
? minimaxH3Ports
- : seedancePorts[mapping.capability.name as keyof typeof seedancePorts];
+ : mapping.capability.module.name === "@hypit/wan"
+ ? wanPorts[mapping.capability.name as keyof typeof wanPorts]
+ : seedancePorts[mapping.capability.name as keyof typeof seedancePorts];
assertMappingCoversPorts(ports, mapping);
}
});
diff --git a/packages/wan/README.md b/packages/wan/README.md
new file mode 100644
index 00000000..4b54d227
--- /dev/null
+++ b/packages/wan/README.md
@@ -0,0 +1,31 @@
+# `@hypit/wan`
+
+Exact author/compute contracts and package-owned author Surfaces for Wan 2.7 Image and Wan 2.7 Image
+Pro.
+
+The model variants are separate endpoints with exact request validation. Their Surfaces project the
+primary result to an ordinary image Artifact. The package contains no Provider selection, API key or
+network execution. The selected Provider implements its exact capability.
+
+Import the model variant you mean and connect prompt and references as ordinary graph edges:
+
+```xml
+<wan:Image id="draft" prompt={prompt} resolution="2K">
+ <wan:Reference image={product.image}/>
+</wan:Image>
+
+<wan:ProImage id="hero" prompt={heroPrompt} resolution="4K"/>
+```
+
+The Surface only lowers this syntax into the package's exact model request. It does not select a
+Provider.
+
+Both variants accept prompts up to 5,000 characters and up to nine references, and render at `1K` or
+`2K`; the Pro variant adds `4K`. The model takes no aspect ratio: with references present the output
+takes the shape of the last one, and a prompt-only element renders at the band's own framing. There
+is no negative prompt either, so write exclusions into the prompt.
+
+`count` renders up to four pictures. Setting `image-set` renders one storyline across several
+pictures instead, where `count` names a ceiling of up to twelve and the model chooses how many it
+returns. An image set shapes a storyline the way `extended-reasoning` shapes a single picture, so the
+two are not stated together.
diff --git a/packages/wan/package.json b/packages/wan/package.json
new file mode 100644
index 00000000..1c0d7d6c
--- /dev/null
+++ b/packages/wan/package.json
@@ -0,0 +1,21 @@
+{
+ "name": "@hypit/wan",
+ "version": "0.0.0-dev",
+ "license": "SEE LICENSE IN LICENSE",
+ "private": true,
+ "type": "module",
+ "exports": {
+ ".": "./src/index.ts"
+ },
+ "hypit": {
+ "activation": "./src/activation.ts"
+ },
+ "dependencies": {
+ "@hypit/artifact": "workspace:*",
+ "@hypit/generation": "workspace:*",
+ "@hypit/markup": "workspace:*",
+ "@hypit/model-kit": "workspace:*",
+ "@hypit/protocol": "workspace:*",
+ "@hypit/text": "workspace:*"
+ }
+}
diff --git a/packages/wan/src/activation.ts b/packages/wan/src/activation.ts
new file mode 100644
index 00000000..d1370084
--- /dev/null
+++ b/packages/wan/src/activation.ts
@@ -0,0 +1,11 @@
+import { createMarkupSurfaceHostFacet } from "@hypit/markup";
+import { wanComponent, wanDefinition, wanManifest, wanModuleRef, wanMarkupSurfaces } from "./index.js";
+import { decodeWanImageSurface, decodeWanProImageSurface } from "./surface.js";
+export const hypitPackage = { format: "hypit.node-package@1" as const, modules: [{ manifest: wanManifest }], components: [wanComponent], hostFacets: [
+ wanDefinition.hostFacet,
+ createMarkupSurfaceHostFacet({ module: wanModuleRef,
+ declaration: wanMarkupSurfaces.find((item) => item.name === "image")!, handler: decodeWanImageSurface }),
+ createMarkupSurfaceHostFacet({ module: wanModuleRef,
+ declaration: wanMarkupSurfaces.find((item) => item.name === "pro-image")!, handler: decodeWanProImageSurface }),
+] };
+export default hypitPackage;
diff --git a/packages/wan/src/index.ts b/packages/wan/src/index.ts
new file mode 100644
index 00000000..f0fec42e
--- /dev/null
+++ b/packages/wan/src/index.ts
@@ -0,0 +1,160 @@
+import { artifactTypes } from "@hypit/artifact";
+import { sealGenerationPortRequest, sealGenerationPortTable } from "@hypit/generation";
+import type { GenerationPortTable, GenerationPortValue, GenerationRequest } from "@hypit/generation";
+import type { SurfaceAttributeVocabulary, SurfaceChildVocabulary } from "@hypit/markup";
+import { defineExactModelModule } from "@hypit/model-kit";
+import { textTypes } from "@hypit/text";
+
+export const wanModuleRef = { name: "@hypit/wan", version: "1" } as const;
+export const wanModels = ["wan-2.7-image", "wan-2.7-image-pro"] as const;
+export type WanModel = typeof wanModels[number];
+
+/**
+ * The model renders at one of these bands. It takes no aspect ratio: with input images the output
+ * follows the last one, and a prompt-only request renders at the band's own framing.
+ */
+const WAN_RESOLUTIONS = ["1K", "2K"] as const;
+const WAN_PRO_RESOLUTIONS = ["1K", "2K", "4K"] as const;
+
+function wanPortTable(model: WanModel): GenerationPortTable {
+ const pro = model === "wan-2.7-image-pro";
+ return sealGenerationPortTable({
+ model,
+ result: "image",
+ ports: [
+ { name: "prompt", value: { kind: "text", maxChars: 5_000 }, minItems: 1, maxItems: 1 },
+ { name: "images", value: { kind: "media", accepts: ["image"] }, minItems: 0, maxItems: 9 },
+ {
+ name: "resolution",
+ value: { kind: "enum", values: pro ? [...WAN_PRO_RESOLUTIONS] : [...WAN_RESOLUTIONS] },
+ minItems: 0,
+ maxItems: 1,
+ },
+ // One request renders up to four pictures, or up to twelve as a story-coherent set. The
+ // model chooses how many of an image set it returns, so this names a ceiling.
+ { name: "count", value: { kind: "number", integer: true, minimum: 1, maximum: 12 }, minItems: 0, maxItems: 1 },
+ { name: "imageSet", value: { kind: "boolean" }, minItems: 0, maxItems: 1 },
+ { name: "extendedReasoning", value: { kind: "boolean" }, minItems: 0, maxItems: 1 },
+ { name: "watermark", 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 },
+ ],
+ // An image set renders one storyline in several pictures, which is what extended reasoning
+ // would otherwise shape for a single picture.
+ requires: [{ kind: "atMostOneOf", ports: ["imageSet", "extendedReasoning"] }],
+ });
+}
+
+export const wanPorts: Readonly<Record<WanModel, GenerationPortTable>> = {
+ "wan-2.7-image": wanPortTable("wan-2.7-image"),
+ "wan-2.7-image-pro": wanPortTable("wan-2.7-image-pro"),
+};
+
+export function sealWanRequest(
+ model: WanModel,
+ ports: Readonly<Record<string, readonly GenerationPortValue[]>>,
+): GenerationRequest {
+ return sealGenerationPortRequest(wanPorts[model], ports);
+}
+
+const wanBaseDefinition = defineExactModelModule({
+ module: wanModuleRef,
+ endpoints: wanModels.map((model) => ({
+ key: model === "wan-2.7-image" ? "image" : "pro",
+ requestTypeName: model === "wan-2.7-image" ? "WanImageRequest" : "WanProImageRequest",
+ producerName: `request-${model}`,
+ ports: wanPorts[model],
+ })),
+});
+
+export const wanEndpoints = wanBaseDefinition.endpoints;
+export const wanComponent = wanBaseDefinition.component;
+
+function wanAttributes(pro: boolean): readonly SurfaceAttributeVocabulary[] {
+ return [
+ { name: "id", kind: "identifier", required: true,
+ summary: "Names this generation and prefixes the bindings it publishes." },
+ { name: "prompt", kind: "reference", required: true, accepts: [textTypes.text],
+ summary: "The Text edge describing the picture, the edit to make, or the storyline of an image set." },
+ { name: "resolution", kind: "literal", required: false,
+ values: pro ? [...WAN_PRO_RESOLUTIONS] : [...WAN_RESOLUTIONS],
+ summary: "The size band the model renders at." },
+ { name: "count", kind: "literal", required: false,
+ summary: "How many pictures to render, up to four, or the ceiling of an image set." },
+ { name: "image-set", kind: "literal", required: false, values: ["true", "false"],
+ summary: "Renders one storyline as several pictures instead of one picture." },
+ { name: "extended-reasoning", kind: "literal", required: false, values: ["true", "false"],
+ summary: "Spends longer shaping a single picture before rendering it." },
+ { name: "watermark", kind: "literal", required: false, values: ["true", "false"],
+ summary: "Marks the returned pictures as AI generated." },
+ { name: "seed", kind: "literal", required: false,
+ summary: "Seeds the model's sampling so a rerun stays close to this one." },
+ ];
+}
+
+const wanChildren: readonly SurfaceChildVocabulary[] = [
+ { tag: "Reference", cardinality: "many",
+ summary: "Attaches one image Artifact the model edits or draws on.",
+ attributes: [
+ { name: "image", kind: "reference", required: true, accepts: [artifactTypes.blob],
+ summary: "Selects the image Artifact this reference contributes." },
+ ] },
+];
+
+const surface = (
+ name: "image" | "pro-image",
+ tag: "Image" | "ProImage",
+ endpoint: (typeof wanEndpoints)["image" | "pro"],
+ pro: boolean,
+ summary: string,
+ example: string,
+) => ({
+ name,
+ tag,
+ mode: "structured" as const,
+ outputs: [endpoint!.draftType, endpoint!.mediaBindings.images!.type],
+ vocabulary: {
+ summary,
+ attributes: wanAttributes(pro),
+ children: wanChildren,
+ ports: [{
+ name: "image",
+ type: artifactTypes.blob,
+ summary: "The primary generated image, addressed as `<id>.image`.",
+ }],
+ example,
+ notes: [
+ "The element accepts at most 9 `Reference` children and no text content.",
+ "With references present the output takes the shape of the last one; a prompt-only element renders at the band's own framing.",
+ "The model reads exclusions from the prompt itself, so write them there.",
+ "Every `Reference` is an ordinary image Artifact edge; the Surface copies no runtime media into request metadata.",
+ "The Surface lowers the element into the package's exact model request and selects no Provider.",
+ ],
+ },
+});
+
+export const wanMarkupSurfaces = [
+ surface("image", "Image", wanEndpoints.image!, false,
+ "Generates pictures with the exact Wan 2.7 Image model from a Text prompt and optional reference images.",
+ `<wan:Image
+ id="draft"
+ prompt={prompt}
+ resolution="2K"
+>
+ <wan:Reference image={product.image}/>
+</wan:Image>`),
+ surface("pro-image", "ProImage", wanEndpoints.pro!, true,
+ "Generates pictures with the exact Wan 2.7 Image Pro model from a Text prompt and optional reference images.",
+ `<wan:ProImage
+ id="hero"
+ prompt={heroPrompt}
+ resolution="4K"
+/>`),
+] as const;
+
+export const wanManifest = {
+ ...wanBaseDefinition.manifest,
+};
+export const wanDefinition = {
+ ...wanBaseDefinition,
+ manifest: wanManifest,
+};
diff --git a/packages/wan/src/surface.ts b/packages/wan/src/surface.ts
new file mode 100644
index 00000000..1f6d9486
--- /dev/null
+++ b/packages/wan/src/surface.ts
@@ -0,0 +1,147 @@
+import { artifactTypes } from "@hypit/artifact";
+import { generationPort, sealGenerationMediaBinding, sealGenerationRequestDraft } from "@hypit/generation";
+import type { GenerationMediaPort, GenerationPortValue } from "@hypit/generation";
+import {
+ createExactModelPrimaryGenerationFragment,
+ exactModelMediaInputNames,
+ exactModelTextInputName,
+} from "@hypit/model-kit";
+import type { ExactModelEndpoint } from "@hypit/model-kit";
+import type {
+ MarkupAttributeValue,
+ StructuredElement,
+ StructuredSurfaceHandler,
+ SurfaceResolvedReference,
+} from "@hypit/markup";
+import type { CanonicalValue, TypeRef } from "@hypit/protocol";
+import { textTypes, verifyText } from "@hypit/text";
+
+import { wanEndpoints } from "./index.js";
+
+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;
+}
+
+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 = required.filter((name) => element.attributes[name] === undefined);
+ assert(missing.length === 0, `${element.name} requires ${missing.join(", ")}`);
+}
+
+function text(element: StructuredElement, name: string): string {
+ const value = element.attributes[name];
+ assert(typeof value === "string" && value.trim().length > 0, `${element.name}.${name} must be text`);
+ return value.trim();
+}
+
+/** An absent optional attribute leaves its port unstated, which the model reads as its own default. */
+function optionalText(element: StructuredElement, name: string): readonly GenerationPortValue[] | undefined {
+ return element.attributes[name] === undefined ? undefined : [text(element, name)];
+}
+
+function optionalFlag(element: StructuredElement, name: string): readonly GenerationPortValue[] | undefined {
+ if (element.attributes[name] === undefined) return undefined;
+ const value = text(element, name);
+ assert(value === "true" || value === "false", `${element.name}.${name} must be true or false`);
+ return [value === "true"];
+}
+
+function optionalInteger(element: StructuredElement, name: string): readonly GenerationPortValue[] | undefined {
+ if (element.attributes[name] === undefined) return undefined;
+ const value = text(element, name);
+ assert(/^\d+$/u.test(value), `${element.name}.${name} must be a whole number`);
+ return [Number(value)];
+}
+
+function ref(
+ element: StructuredElement,
+ name: string,
+ type: TypeRef,
+ resolve: (path: string) => SurfaceResolvedReference | undefined,
+): SurfaceResolvedReference {
+ const value: MarkupAttributeValue | undefined = element.attributes[name];
+ assert(typeof value === "object" && value.kind === "reference", `${element.name}.${name} must be a reference`);
+ const result = resolve(value.path);
+ assert(result !== undefined && sameType(result.type, type), `${element.name}.${name} has the wrong type`);
+ return result;
+}
+
+const attributes = ["id", "prompt", "resolution", "count", "image-set", "extended-reasoning", "watermark", "seed"] as const;
+
+function decoder(endpoint: ExactModelEndpoint): StructuredSurfaceHandler {
+ return ({ element, resolveReference }) => {
+ exact(element, [...attributes], ["id", "prompt"]);
+ 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 imagePort = generationPort(endpoint.ports, "images");
+ assert(imagePort.value.kind === "media", "Wan images port is not media");
+ const images: SurfaceResolvedReference[] = [];
+ 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`);
+ exact(child, ["image"], ["image"]);
+ assert(!child.children.some((item) => item.kind === "element" || item.value.trim()), `${child.name} must be empty`);
+ const image = ref(child, "image", artifactTypes.blob, resolveReference);
+ if (image.record !== undefined) {
+ assert(image.record.value.kind === "blob" && image.record.value.mediaType.startsWith("image/"),
+ `${child.name}.image must reference image media`);
+ }
+ images.push(image);
+ }
+ assert(images.length <= imagePort.maxItems, `${element.name} accepts at most ${imagePort.maxItems} references`);
+ const stated: Record<string, readonly GenerationPortValue[] | undefined> = {
+ resolution: optionalText(element, "resolution"),
+ count: optionalInteger(element, "count"),
+ imageSet: optionalFlag(element, "image-set"),
+ extendedReasoning: optionalFlag(element, "extended-reasoning"),
+ watermark: optionalFlag(element, "watermark"),
+ seed: optionalInteger(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 = images.map((image, index) => {
+ const name = `image-${String(index + 1).padStart(4, "0")}`;
+ const bindingId = `${id}.${name}.binding`;
+ records.push({
+ id: bindingId, type: endpoint.mediaBindings.images!.type,
+ value: { kind: "inline", value: sealGenerationMediaBinding(imagePort 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: "images" } as const;
+ });
+ const fragment = createExactModelPrimaryGenerationFragment(endpoint, media, [{ name: "prompt", port: "prompt" }]);
+ return { records, fragments: [fragment], components: [{
+ id, fragment: fragment.id, inputs, outputs: { image: `${id}.image` }, range: element.range,
+ }] };
+ };
+}
+
+export const decodeWanImageSurface = decoder(wanEndpoints.image!);
+export const decodeWanProImageSurface = decoder(wanEndpoints.pro!);
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index f238305b..e70d85e4 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -315,6 +315,9 @@ importers:
'@hypit/volcengine-matting':
specifier: workspace:*
version: link:packages/volcengine-matting
+ '@hypit/wan':
+ specifier: workspace:*
+ version: link:packages/wan
'@hypit/whisperx':
specifier: workspace:*
version: link:packages/whisperx
@@ -2447,6 +2450,9 @@ importers:
'@hypit/runtime-kit':
specifier: workspace:*
version: link:../runtime-kit
+ '@hypit/wan':
+ specifier: workspace:*
+ version: link:../wan
devDependencies:
'@hypit/seedance':
specifier: workspace:*
@@ -3645,6 +3651,27 @@ importers:
specifier: workspace:*
version: link:../protocol
+ packages/wan:
+ dependencies:
+ '@hypit/artifact':
+ specifier: workspace:*
+ version: link:../artifact
+ '@hypit/generation':
+ specifier: workspace:*
+ version: link:../generation
+ '@hypit/markup':
+ specifier: workspace:*
+ version: link:../markup
+ '@hypit/model-kit':
+ specifier: workspace:*
+ version: link:../model-kit
+ '@hypit/protocol':
+ specifier: workspace:*
+ version: link:../protocol
+ '@hypit/text':
+ specifier: workspace:*
+ version: link:../text
+
packages/whisperx:
dependencies:
'@hypit/component-kit':