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.

fix: enforce model-owned request rules across entry points

kashorin5e27c83879ce
diff --git a/packages/model-kit/README.md b/packages/model-kit/README.md
index 5952981e..b1ca6cfe 100644
--- a/packages/model-kit/README.md
+++ b/packages/model-kit/README.md
@@ -50,3 +50,31 @@ exact fields, constraints, model identity, capability name and validator. The he
Provider routing, fallback, credentials or Runtime authority.
This is a package-authoring utility, not an author-importable model by itself.
+
+## Model-owned request checks
+
+An endpoint may supply two synchronous, pure functions in addition to its port table:
+
+- `validateInputs(inputs)` checks values already supplied, both in drafts and complete requests.
+ Text and media may still be missing from a draft. Use this for rules such as a reference's media
+ type; do not require a future input to exist.
+- `validateRequest(request)` checks additional relationships that require the complete request.
+ It runs after the port table and `validateInputs`, when every required input is available.
+
+Both return `void` and throw a useful error to reject. They read the supplied values only: no IO,
+Provider selection, request mutation or saved validation result. Existing port rules remain in the
+port table. The helper supplies structural validation before calling either function.
+
+Register each rule once in the endpoint definition. The helper connects these functions to Type
+validators, media/Text bindings, finalization, generation and planning. Planning checks the known
+values and leaves future media on the existing graph edges. A directly supplied request or an
+existing Need receives full validation, just as it does during execution.
+
+For a public request builder, use `model.endpoints.image.sealRequest(ports)`: it canonicalizes the
+request and applies all model rules. `endpoint.validateRequest(value)` checks an existing complete
+request; `endpoint.validateDraft(value)` checks a partially assembled one. Calling the common
+generation port helpers alone applies only the port table, not these model-owned functions.
+
+Keep service-specific limits in the Provider. Its existing `supports` and pre-submission preparation
+should share its own checks, rejecting known unsupported values before resource transfer. This does
+not require the Provider to import the Model implementation or add any fields to the request.
diff --git a/packages/model-kit/src/index.ts b/packages/model-kit/src/index.ts
index edda6bf9..bac86086 100644
--- a/packages/model-kit/src/index.ts
+++ b/packages/model-kit/src/index.ts
@@ -13,13 +13,13 @@ import type { HostFacet } from "@hypit/host";
import {
bindGenerationMedia,
bindGenerationText,
- finalizeGenerationRequestDraft,
generationModuleRef,
generationProducers,
generationTypes,
mediaBindingSchemaFromPort,
requestDraftSchemaFromPorts,
requestSchemaFromPorts,
+ sealGenerationPortRequest,
verifyGenerationMediaBinding,
verifyRequestDraftAgainstPorts,
verifyRequestAgainstPorts,
@@ -28,6 +28,7 @@ import type {
GenerationMediaBinding,
GenerationMediaPort,
GenerationPortTable,
+ GenerationRequest,
GenerationRequestDraft,
} from "@hypit/generation";
import { textDependency, textTypes } from "@hypit/text";
@@ -76,6 +77,10 @@ export type ExactModelEndpointSpec = {
readonly requestTypeName: string;
readonly producerName: string;
readonly ports: GenerationPortTable;
+ /** Additional complete-request rules, after port and supplied-input validation. */
+ readonly validateRequest?: (request: GenerationRequest) => void;
+ /** Pure, synchronous checks of supplied values, in drafts and complete requests; throw to reject. */
+ readonly validateInputs?: (inputs: GenerationRequestDraft) => void;
};
export type ExactModelEndpoint = {
@@ -89,6 +94,9 @@ export type ExactModelEndpoint = {
readonly mediaBindings: Readonly<Record<string, ExactModelMediaBindingEndpoint>>;
readonly textBindings: Readonly<Record<string, ExactModelTextBindingEndpoint>>;
readonly ports: GenerationPortTable;
+ readonly validateRequest: (request: unknown) => void;
+ readonly validateDraft: (draft: unknown) => void;
+ readonly sealRequest: (ports: GenerationRequest["ports"]) => GenerationRequest;
readonly fragment: ReturnType<typeof sealGraphFragment>;
};
@@ -267,7 +275,7 @@ export function plannedExactModelRequest(
const knownNeed = state.needs.find((need) => need.id === binding.id);
if (knownNeed !== undefined) {
- verifyRequestAgainstPorts(endpoint.ports, knownNeed.constraints);
+ endpoint.validateRequest(knownNeed.constraints);
return {
model: endpoint.ports.model,
ports: structuredClone((knownNeed.constraints as unknown as GenerationRequestDraft).ports),
@@ -281,6 +289,12 @@ export function plannedExactModelRequest(
Object.values(step.outputs).map((record) => [record, step] as const)));
const requestRecord = generationStep.inputs.request;
if (requestRecord === undefined) return undefined;
+ const knownRequest = records.get(requestRecord);
+ if (knownRequest !== undefined) {
+ const request = inlineValue<GenerationRequest>(knownRequest.value, `${endpoint.ports.model} request`);
+ endpoint.validateRequest(request);
+ return { model: endpoint.ports.model, ports: structuredClone(request.ports), pendingMedia: [], complete: false };
+ }
const finalize = producedBy.get(requestRecord);
if (finalize === undefined || !sameReference(finalize.producer, endpoint.finalizeProducer)) return undefined;
const finalDraft = finalize.inputs.draft;
@@ -295,7 +309,7 @@ export function plannedExactModelRequest(
const record = records.get(recordId);
if (record !== undefined) {
const draft = inlineValue<GenerationRequestDraft>(record.value, `${endpoint.ports.model} request draft`);
- verifyRequestDraftAgainstPorts(endpoint.ports, draft);
+ endpoint.validateDraft(draft);
return draft;
}
const step = producedBy.get(recordId);
@@ -354,6 +368,8 @@ export function plannedExactModelRequest(
};
const draft = rebuildDraft(finalDraft);
+ endpoint.validateDraft(draft);
+ if (pendingMedia.length === 0) endpoint.validateRequest(draft);
return {
model: endpoint.ports.model,
ports: structuredClone(draft.ports),
@@ -502,6 +518,15 @@ export function defineExactModelModule<const Key extends string>(
};
const endpoints = Object.fromEntries(endpointData.map((item): [Key, ExactModelEndpoint] => {
+ const validateRequest = (request: unknown): void => {
+ verifyRequestAgainstPorts(item.spec.ports, request);
+ item.spec.validateInputs?.(request);
+ item.spec.validateRequest?.(request);
+ };
+ const validateDraft = (draft: unknown): void => {
+ verifyRequestDraftAgainstPorts(item.spec.ports, draft);
+ item.spec.validateInputs?.(draft);
+ };
const fragment = sealGraphFragment({
inputs: [{ name: "request", type: item.requestType }],
operations: [{
@@ -527,6 +552,14 @@ export function defineExactModelModule<const Key extends string>(
mediaBindings: item.mediaBindings,
textBindings: item.textBindings,
ports: item.spec.ports,
+ validateRequest,
+ validateDraft,
+ sealRequest(ports) {
+ const request = sealGenerationPortRequest(item.spec.ports, ports);
+ item.spec.validateInputs?.(request);
+ item.spec.validateRequest?.(request);
+ return request;
+ },
fragment,
} satisfies ExactModelEndpoint];
}));
@@ -540,12 +573,12 @@ export function defineExactModelModule<const Key extends string>(
validators: endpointData.flatMap((item) => [{
type: item.requestType,
handler({ value }) {
- verifyRequestAgainstPorts(item.spec.ports, inlineRequest(value, item.spec.key));
+ endpoints[item.spec.key]!.validateRequest(inlineRequest(value, item.spec.key));
},
}, {
type: item.draftType,
handler({ value }) {
- verifyRequestDraftAgainstPorts(item.spec.ports, inlineRequest(value, `${item.spec.key} draft`));
+ endpoints[item.spec.key]!.validateDraft(inlineRequest(value, `${item.spec.key} draft`));
},
}]),
producers: endpointData.flatMap((item) => [
@@ -555,7 +588,7 @@ export function defineExactModelModule<const Key extends string>(
const requestRecord = inputs.request;
assert(requestRecord !== undefined, `${item.spec.key} request input is missing`);
const request = inlineRequest(requestRecord.value, item.spec.key);
- verifyRequestAgainstPorts(item.spec.ports, request);
+ endpoints[item.spec.key]!.validateRequest(request);
return { outputs: {}, needs: { generation: request } };
},
},
@@ -570,11 +603,13 @@ export function defineExactModelModule<const Key extends string>(
verifyGenerationMediaBinding(port, value);
const artifact = inputs.artifact!.value;
assert(artifact.kind === "blob", `${binding.port} artifact must be a Blob`);
+ const bound = bindGenerationMedia(item.spec.ports, draft, binding.port, value, artifact);
+ endpoints[item.spec.key]!.validateDraft(bound);
return {
outputs: {
draft: {
kind: "inline" as const,
- value: canonicalize(bindGenerationMedia(item.spec.ports, draft, binding.port, value, artifact)),
+ value: canonicalize(bound),
},
},
needs: {},
@@ -586,11 +621,13 @@ export function defineExactModelModule<const Key extends string>(
handler: ({ inputs }: ProducerHandlerContext) => {
const draft = inlineValue<GenerationRequestDraft>(inputs.draft!.value, `${item.spec.key} draft`);
const text = inlineValue<Text>(inputs.text!.value, `${binding.port} Text`);
+ const bound = bindGenerationText(item.spec.ports, draft, binding.port, text);
+ endpoints[item.spec.key]!.validateDraft(bound);
return {
outputs: {
draft: {
kind: "inline" as const,
- value: canonicalize(bindGenerationText(item.spec.ports, draft, binding.port, text)),
+ value: canonicalize(bound),
},
},
needs: {},
@@ -599,18 +636,20 @@ export function defineExactModelModule<const Key extends string>(
})),
{
producer: item.finalizeProducer,
- handler: ({ inputs }) => ({
- outputs: {
- request: {
- kind: "inline" as const,
- value: canonicalize(finalizeGenerationRequestDraft(
- item.spec.ports,
- inlineValue<GenerationRequestDraft>(inputs.draft!.value, `${item.spec.key} draft`),
- )),
+ handler: ({ inputs }) => {
+ const endpoint = endpoints[item.spec.key]!;
+ const draft = inlineValue<GenerationRequestDraft>(inputs.draft!.value, `${item.spec.key} draft`);
+ endpoint.validateDraft(draft);
+ return {
+ outputs: {
+ request: {
+ kind: "inline" as const,
+ value: canonicalize(endpoint.sealRequest(draft.ports)),
+ },
},
- },
- needs: {},
- }),
+ needs: {},
+ };
+ },
},
]),
plannedNeeds: Object.values(endpoints).map((endpoint) => exactModelPlannedNeedFacet(endpoint)),
diff --git a/packages/model-kit/test/model-kit.test.ts b/packages/model-kit/test/model-kit.test.ts
index a2748123..e496184e 100644
--- a/packages/model-kit/test/model-kit.test.ts
+++ b/packages/model-kit/test/model-kit.test.ts
@@ -166,3 +166,50 @@ test("planning follows the model's declared assembly edges and leaves an upstrea
references: { image: 2 },
});
});
+
+test("model input rules run during assembly while complete-request rules wait for all inputs", async () => {
+ const checked = defineExactModelModule({
+ module: { name: "@test/compare-images", version: "1" },
+ endpoints: [{
+ key: "compare", requestTypeName: "CompareRequest", producerName: "compare", ports,
+ validateInputs(request) {
+ for (const value of request.ports.images ?? []) {
+ if (typeof value === "object" && value.artifact.mediaType === "image/gif") {
+ throw new Error("comparison references must be still images");
+ }
+ }
+ },
+ validateRequest(request) {
+ if (request.ports.prompt?.[0] === "compare" && request.ports.images?.length !== 2) {
+ throw new Error("compare requires two reference images");
+ }
+ },
+ }],
+ });
+ const endpoint = checked.endpoints.compare;
+ const bind = checked.component.producers.find((item) => item.producer.name === endpoint.mediaBindings.images!.producer.name)!;
+ const finalize = checked.component.producers.find((item) => item.producer.name === endpoint.finalizeProducer.name)!;
+ const artifact = { kind: "blob" as const, resource: fixtureResource("compare-image"), size: 4, mediaType: "image/png" };
+ const initial = { kind: "inline" as const, value: sealGenerationRequestDraft(ports, { prompt: ["compare"] }) };
+ const bindImage = async (draft: unknown, mediaType: string) => await bind.handler({ inputs: {
+ draft: { value: draft }, binding: { value: { kind: "inline", value: { role: "image" } } },
+ artifact: { value: { ...artifact, mediaType } },
+ } } as never);
+
+ const first = await bindImage(initial, "image/png");
+ await assert.rejects(async () => finalize.handler({ inputs: { draft: { value: first.outputs.draft } } } as never), /two reference images/);
+ await assert.rejects(bindImage(initial, "image/gif"), /must be still images/);
+ assert.throws(() => endpoint.sealRequest({ prompt: ["compare"], images: [{ role: "image", artifact }] }), /two reference images/);
+ assert.throws(() => endpoint.sealRequest({ prompt: ["draw"], images: [{ role: "image", artifact: { ...artifact, mediaType: "image/gif" } }] }), /must be still images/);
+
+ const second = await bindImage(first.outputs.draft, "image/jpeg");
+ const complete = await finalize.handler({ inputs: { draft: { value: second.outputs.draft } } } as never);
+ assert.ok(complete.outputs.request);
+ const requestValidator = checked.component.validators.find((item) => item.type.name === endpoint.requestType.name)!;
+ await requestValidator.handler({ value: complete.outputs.request } as never);
+
+ // Another model using the same common port vocabulary has not acquired this model's GIF rule.
+ assert.doesNotThrow(() => definition.endpoints.image.sealRequest({
+ prompt: ["draw"], images: [{ role: "image", artifact: { ...artifact, mediaType: "image/gif" } }],
+ }));
+});
diff --git a/packages/provider-hypihub/README.md b/packages/provider-hypihub/README.md
index f8c79093..bfd6fb1e 100644
--- a/packages/provider-hypihub/README.md
+++ b/packages/provider-hypihub/README.md
@@ -118,6 +118,9 @@ Resource identity with the same declared person-reference classification is uplo
cross-Build cache. Seedance visual references can carry `personReference` in their media fields;
the mapping declares it as a resource-transport field and the upload session receives
`is_person_reference`, preserving true, false and omission. It stays out of the generation body.
+This covers reference images, reference videos, and first/last frames for every declared Seedance
+variant. Omission remains absent on the wire; HypiHub's upload API currently defaults it to false,
+so omission does not enable detection or person-reference preparation.
HypiHub stores the authored classification and prepares the applicable upstream person reference;
this Provider does not detect faces or select an upstream private-avatar group.
diff --git a/packages/provider-hypihub/test/routes.test.ts b/packages/provider-hypihub/test/routes.test.ts
index 340ed7d3..3fde808a 100644
--- a/packages/provider-hypihub/test/routes.test.ts
+++ b/packages/provider-hypihub/test/routes.test.ts
@@ -2,16 +2,17 @@ import assert from "node:assert/strict";
import test from "node:test";
import type { GenerationArtifactUrlResolver } from "@hypit/generation";
import type { EndpointSupport } from "@hypit/endpoint-kit";
-import type { CanonicalValue } from "@hypit/protocol";
+import type { BlobRef, CanonicalValue } from "@hypit/protocol";
import { hypiHubRoutes } from "../src/routes.js";
import type { HypiHubRoute } from "../src/routes.js";
+import { sealGptImage2Request } from "../../gpt-image/src/index.js";
async function compile(route: HypiHubRoute, constraints: CanonicalValue, resolve: GenerationArtifactUrlResolver) {
return await route.prepare(constraints).compile(resolve);
}
-const image = {
+const image: BlobRef = {
kind: "blob" as const,
resource: "res_hypihub-route-1",
size: 3,
@@ -21,6 +22,25 @@ const image = {
const resolve = async () => "data:image/png;base64,AQID";
const resolveAudio = async () => "data:audio/wav;base64,AQID";
+test("service restrictions leave the model request valid and reject before resolving uploads", async () => {
+ const route = hypiHubRoutes.find((item) => item.capability.name === "gpt-image-2")!;
+ const request = sealGptImage2Request({
+ prompt: ["edit the cutout"], aspectRatio: ["1:1"], resolution: ["2K"],
+ background: ["opaque"], images: [{ role: "image", artifact: image }],
+ });
+ const constraints = request as unknown as CanonicalValue;
+ assert.equal(route.supports!({ capability: route.capability, returns: route.returns, constraints }).status, "unsupported");
+ let resolved = 0;
+ const upload: GenerationArtifactUrlResolver = async () => { resolved++; return "https://example.test/reference.png"; };
+ await assert.rejects(compile(route, constraints, upload), /background option only at 1K/);
+ assert.equal(resolved, 0);
+
+ const supported = sealGptImage2Request({ ...request.ports, resolution: ["1K"] }) as unknown as CanonicalValue;
+ assert.equal(route.supports!({ capability: route.capability, returns: route.returns, constraints: supported }).status, "supported");
+ await compile(route, supported, upload);
+ assert.equal(resolved, 1);
+});
+
test("HypiHub GPT image requests use canonical edit references and the authored resolution tier", async () => {
const route = hypiHubRoutes.find((item) => item.capability.name === "gpt-image-2");
assert.ok(route);
@@ -214,19 +234,20 @@ test("HypiHub MiMo Speech mappings use the public audio speech fields", async ()
});
test("Seedance person metadata reaches resource transport without changing video request fields", async () => {
- for (const port of ["referenceImage", "referenceVideo", "firstFrame", "lastFrame"] as const) {
- const route = hypiHubRoutes.find((item) => item.capability.name === "seedance-2-mini")!;
- for (const flag of [true, false, undefined]) {
- const fields = flag === undefined ? {} : { personReference: flag };
- const seen: unknown[] = [];
- const result = await compile(route, { ports: {
- prompt: ["animate"], duration: [5],
- [port]: [{ role: port === "referenceVideo" ? "video" : "image", artifact: image, fields }],
- } }, async (_artifact, metadata) => { seen.push(metadata); return "https://media.test/ref"; });
- assert.deepEqual(seen, [fields]);
- const wireField = { referenceImage: "reference_image_urls", referenceVideo: "reference_videos", firstFrame: "first_frame", lastFrame: "last_frame" }[port];
- assert.deepEqual((result.input as Record<string, unknown>)[wireField], port.startsWith("reference") ? ["https://media.test/ref"] : "https://media.test/ref");
- assert.equal(JSON.stringify(result.input).includes("person"), false);
+ for (const route of hypiHubRoutes.filter((item) => item.capability.module.name === "@hypit/seedance")) {
+ for (const port of ["referenceImage", "referenceVideo", "firstFrame", "lastFrame"] as const) {
+ for (const flag of [true, false, undefined]) {
+ const fields = flag === undefined ? {} : { personReference: flag };
+ const seen: unknown[] = [];
+ const result = await compile(route, { ports: {
+ prompt: ["animate"], duration: [5],
+ [port]: [{ role: port === "referenceVideo" ? "video" : "image", artifact: image, fields }],
+ } }, async (_artifact, metadata) => { seen.push(metadata); return "https://media.test/ref"; });
+ assert.deepEqual(seen, [fields]);
+ const wireField = { referenceImage: "reference_image_urls", referenceVideo: "reference_videos", firstFrame: "first_frame", lastFrame: "last_frame" }[port];
+ assert.deepEqual((result.input as Record<string, unknown>)[wireField], port.startsWith("reference") ? ["https://media.test/ref"] : "https://media.test/ref");
+ assert.equal(JSON.stringify(result.input).includes("person"), false);
+ }
}
}
});
diff --git a/packages/seedance/README.md b/packages/seedance/README.md
index f0ca7c4f..64378910 100644
--- a/packages/seedance/README.md
+++ b/packages/seedance/README.md
@@ -18,6 +18,20 @@ the author's literal, in whole seconds inside the model's declared range; measur
with `hypit measure` and write the number here. Nothing in the graph computes it, so a Build plan is
complete before it starts.
+## Reference audio
+
+The Seedance package rejects reference audio declared as `audio/mp4` or `audio/x-m4a`. Convert the
+audio to WAV or MP3 before using it; `media:ExtractAudio` produces WAV and can consume an upstream
+component's media output. Renaming a file or changing its declared media type is not conversion.
+
+Known imports are checked during Surface decoding. Future audio stays a graph input and is checked
+when its Blob arrives. The same rule applies to drafts, complete requests, planning and direct
+generation Producers. `sealSeedanceRequest` uses the endpoint's model-aware request builder;
+`seedanceComponent` and `seedanceDefinition.component` expose the same implementation.
+
+This checks the Blob's declared media type, not its bytes or codec. The selected Provider remains
+responsible for any additional service-specific input limits.
+
## Visual reference metadata
Declare whether each image or video contains a person/avatar reference, including an AI-generated
@@ -37,10 +51,38 @@ Inspect the actual reference when deciding the value. For `FrameVideo`, use
`first-frame-person-reference` and `last-frame-person-reference` beside their respective frame
inputs. A last-frame classification requires a last-frame input.
+| Supplied visual input | Authored attribute | Request port |
+| --- | --- | --- |
+| Each `Reference image={...}` | `person-reference` | `referenceImage` |
+| Each `Reference video={...}` | `person-reference` | `referenceVideo` |
+| `FrameVideo` first frame | `first-frame-person-reference` | `firstFrame` |
+| `FrameVideo` last frame | `last-frame-person-reference` | `lastFrame` |
+
+These forms apply to `standard`, `fast`, `mini` and `2.5`. For example:
+
+```xml
+<seedance:FrameVideo id="turn" model="fast" prompt={direction} duration="5"
+ first-frame={presenter.image} first-frame-person-reference="true"
+ last-frame={empty-room.image} last-frame-person-reference="false"/>
+```
+
+Classify the material supplied to this request, not the intended result. A dance video with a person
+still needs `true` when used only for motion, even if the prompt asks for a different performer.
+An empty room stays `false` when the prompt asks to add a person. Inspect video across the selected
+excerpt, not only its opening frame. This flag neither detects faces nor locks or names an identity.
+Identity and action direction remain in the prompt and references.
+
+The SVML author declares this parameter on each reference input. Admitted files, generated
+images/videos and reused Results use the same attributes. For a future output, declare the intended
+reference classification explicitly; if its contents are uncertain, generate and inspect that
+material before using it downstream.
+
The model's media ports carry this as `fields.personReference`. Providers interpret it through their
service's media handling; it is not a prompt sentence or a Core-level identity. HypiHub sends it as
`is_person_reference` when uploading the file, then uses the returned URL in the ordinary video
request. A project Provider maps it according to its own API.
+Omission does not request automatic face detection. HypiHub currently treats omitted upload flags
+as unmarked (`false`); declare `true` explicitly for a person reference that needs its preparation.
Video references can carry motion or camera behavior while image references carry the target
appearance. Request duration and reference-clip duration are different limits. Check the selected
diff --git a/packages/seedance/src/index.ts b/packages/seedance/src/index.ts
index 8c0112a1..2b045bd7 100644
--- a/packages/seedance/src/index.ts
+++ b/packages/seedance/src/index.ts
@@ -1,7 +1,4 @@
-import {
- sealGenerationPortRequest,
- sealGenerationPortTable,
-} from "@hypit/generation";
+import { sealGenerationPortTable } from "@hypit/generation";
import type {
GenerationPortTable,
GenerationPortValue,
@@ -12,6 +9,7 @@ import type { SurfaceAttributeVocabulary, SurfacePortVocabulary } from "@hypit/m
import { defineExactModelModule } from "@hypit/model-kit";
import { textTypes } from "@hypit/text";
import type { ResourceId } from "@hypit/protocol";
+import { validateSeedanceInputs } from "./validation.js";
export const seedanceModuleRef = { name: "@hypit/seedance", version: "1" } as const;
export const seedanceModels = ["seedance-2", "seedance-2-fast", "seedance-2-mini", "seedance-2.5"] as const;
@@ -93,7 +91,7 @@ export const seedancePorts: Readonly<Record<SeedanceModel, GenerationPortTable>>
export type SeedancePortMap = Readonly<Record<string, readonly GenerationPortValue[]>>;
export function sealSeedanceRequest(model: SeedanceModel, ports: SeedancePortMap): GenerationRequest {
- return sealGenerationPortRequest(seedancePorts[model], ports);
+ return seedanceEndpointsByModel[model].sealRequest(ports);
}
const seedanceBaseDefinition = defineExactModelModule({
@@ -110,6 +108,7 @@ const seedanceBaseDefinition = defineExactModelModule({
: `${model.split("-").map((part) => part[0]!.toUpperCase() + part.slice(1)).join("")}Request`,
producerName: `request-${model}`,
ports: seedancePorts[model],
+ validateInputs: validateSeedanceInputs,
})),
});
@@ -327,23 +326,7 @@ export const seedanceMarkupSurfaces = [
/** The duration is an author literal on every Seedance Surface, so the manifest is the exact-model module's own. */
export const seedanceManifest = seedanceBaseDefinition.manifest;
-const referenceAudioProducers = new Set(Object.values(seedanceEndpoints)
- .map((endpoint) => endpoint.mediaBindings["referenceAudio"]!.producer.name));
-
-export const seedanceComponent = {
- ...seedanceBaseDefinition.component,
- producers: seedanceBaseDefinition.component.producers.map((facet) =>
- referenceAudioProducers.has(facet.producer.name) ? {
- ...facet,
- handler: (context: Parameters<typeof facet.handler>[0]) => {
- const artifact = context.inputs.artifact?.value;
- if (artifact?.kind === "blob" && ["audio/mp4", "audio/x-m4a"].includes(artifact.mediaType)) {
- throw new Error("Seedance reference audio does not accept m4a; convert to wav or mp3");
- }
- return facet.handler(context);
- },
- } : facet),
-};
+export const seedanceComponent = seedanceBaseDefinition.component;
export const seedanceDefinition = seedanceBaseDefinition;
export {
diff --git a/packages/seedance/src/surface.ts b/packages/seedance/src/surface.ts
index 2912d656..1ac3cbc1 100644
--- a/packages/seedance/src/surface.ts
+++ b/packages/seedance/src/surface.ts
@@ -23,6 +23,7 @@ import type {
import { createSeedanceAssembledGenerationFragment } from "./fragment.js";
import { seedanceEndpoints, seedancePorts } from "./index.js";
import type { SeedanceModel, SeedancePortMap } from "./index.js";
+import { validateSeedanceAudio } from "./validation.js";
type MediaInput = {
readonly port: "referenceImage" | "referenceVideo" | "referenceAudio" | "firstFrame" | "lastFrame";
@@ -109,9 +110,7 @@ function mediaReference(
if (value !== undefined && (value.kind !== "blob" || !value.mediaType.startsWith(`${role}/`))) {
throw new Error(`${subject} must reference ${role} media`);
}
- if (value !== undefined && value.kind === "blob" && role === "audio" && ["audio/mp4", "audio/x-m4a"].includes(value.mediaType)) {
- throw new Error(`${subject} references m4a audio, which Seedance does not accept; convert to wav or mp3 and admit that file`);
- }
+ if (value?.kind === "blob" && role === "audio") validateSeedanceAudio(value, subject);
return reference;
}
diff --git a/packages/seedance/src/validation.ts b/packages/seedance/src/validation.ts
new file mode 100644
index 00000000..ac98f0f0
--- /dev/null
+++ b/packages/seedance/src/validation.ts
@@ -0,0 +1,16 @@
+import type { GenerationRequestDraft } from "@hypit/generation";
+import type { BlobRef } from "@hypit/protocol";
+
+/** Seedance's reference-audio rule, shared by known imports and request assembly. */
+export function validateSeedanceAudio(artifact: BlobRef, subject = "Seedance reference audio"): void {
+ if (artifact.mediaType === "audio/mp4" || artifact.mediaType === "audio/x-m4a") {
+ throw new Error(`${subject} does not accept m4a; convert the reference audio to WAV or MP3 before using it (media:ExtractAudio produces WAV)`);
+ }
+}
+
+/** Missing references in a draft remain graph inputs; only supplied audio is checked. */
+export function validateSeedanceInputs(request: GenerationRequestDraft): void {
+ for (const value of request.ports.referenceAudio ?? []) {
+ if (typeof value === "object" && value.role === "audio") validateSeedanceAudio(value.artifact);
+ }
+}
diff --git a/packages/seedance/test/surface.test.ts b/packages/seedance/test/surface.test.ts
index 67547310..2c886761 100644
--- a/packages/seedance/test/surface.test.ts
+++ b/packages/seedance/test/surface.test.ts
@@ -5,6 +5,7 @@ import { artifactTypes } from "@hypit/artifact";
import { parseStructuredElement } from "@hypit/markup";
import type { StructuredSurfaceHandler, SurfaceResolvedReference } from "@hypit/markup";
import { textTypes } from "@hypit/text";
+import { fixtureResource } from "../../../test/fixture-resource.js";
import {
decodeSeedanceFrameVideoSurface,
@@ -25,12 +26,12 @@ const refs = new Map<string, SurfaceResolvedReference>([
}] as const),
]);
-async function decode(source: string, handler: StructuredSurfaceHandler) {
+async function decode(source: string, handler: StructuredSurfaceHandler, references = refs) {
const element = parseStructuredElement({ name: "seedance.svml", text: source }, 0).element;
return await handler({
sourceName: "seedance.svml",
element,
- resolveReference: (path) => refs.get(path),
+ resolveReference: (path) => references.get(path),
resolveAsset: () => { throw new Error("no asset"); },
});
}
@@ -47,6 +48,27 @@ test("TextVideo exposes prompt-only generation without inventing a usage", async
assert.equal(Object.keys(result.components[0]?.inputs ?? {}).some((name) => name.includes("media")), false);
});
+test("admitted M4A audio is rejected at decode while future audio remains a graph reference", async () => {
+ const source = '<seedance:ReferenceVideo id="speaker" model="mini" prompt={direction} duration="6"><seedance:Reference image={generated.image}/><seedance:Reference audio={voice.audio}/></seedance:ReferenceVideo>';
+ for (const mediaType of ["audio/mp4", "audio/x-m4a", "audio/wav", "audio/mpeg"]) {
+ const admitted = new Map(refs);
+ admitted.set("voice.audio", {
+ ...refs.get("voice.audio")!,
+ record: {
+ id: "voice", type: artifactTypes.blob,
+ value: { kind: "blob", resource: fixtureResource("admitted-voice"), size: 4, mediaType },
+ },
+ });
+ if (mediaType === "audio/mp4" || mediaType === "audio/x-m4a") {
+ await assert.rejects(decode(source, decodeSeedanceReferenceVideoSurface, admitted), /m4a/);
+ } else {
+ assert.ok((await decode(source, decodeSeedanceReferenceVideoSurface, admitted)).components.length);
+ }
+ }
+ const future = await decode(source, decodeSeedanceReferenceVideoSurface);
+ assert.deepEqual(future.components[0]!.inputs["media-0002:artifact"], refs.get("voice.audio")!.ref);
+});
+
test("Seedance 2.5 is an exact model with 1080p and auto or 4-30 second duration", async () => {
const automatic = await decode(
'<seedance:TextVideo id="motion" model="2.5" prompt={direction} duration="-1" resolution="1080p" aspect-ratio="9:16"/>',
diff --git a/packages/seedance/test/validation.test.ts b/packages/seedance/test/validation.test.ts
new file mode 100644
index 00000000..8264bbfe
--- /dev/null
+++ b/packages/seedance/test/validation.test.ts
@@ -0,0 +1,137 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { sealGenerationRequestDraft } from "@hypit/generation";
+import type { GenerationRequest } from "@hypit/generation";
+import { plannedExactModelRequest } from "@hypit/model-kit";
+import type { ExactModelEndpoint } from "@hypit/model-kit";
+import { canonicalize } from "@hypit/protocol";
+import type { BlobRef, BuildState, ProducerRef, StoredValue } from "@hypit/protocol";
+import { fixtureResource } from "../../../test/fixture-resource.js";
+import {
+ seedanceComponent, seedanceDefinition, seedanceEndpointsByModel, sealSeedanceRequest,
+} from "../src/index.js";
+
+const audio = (mediaType: string): BlobRef => ({
+ kind: "blob", resource: fixtureResource("reference-audio"), size: 4, mediaType,
+});
+const settings = {
+ prompt: ["A presenter explains the scene"], resolution: ["720p"], aspectRatio: ["9:16"],
+ duration: [5], generateAudio: [true], webSearch: [false],
+ referenceImage: [{ role: "image" as const, artifact: {
+ kind: "blob" as const, resource: fixtureResource("reference-image"), size: 4, mediaType: "image/png",
+ } }],
+};
+const inline = (value: unknown): StoredValue => ({ kind: "inline", value: canonicalize(value) });
+const input = (value: StoredValue) => ({ value });
+async function produce(producer: ProducerRef, inputs: Record<string, { value: StoredValue }>) {
+ const facet = seedanceDefinition.component.producers.find((item) => item.producer.name === producer.name);
+ assert.ok(facet);
+ return await facet.handler({ inputs } as never);
+}
+
+function assembly(endpoint: ExactModelEndpoint, artifact?: BlobRef): BuildState {
+ return {
+ records: [
+ { id: "draft", type: endpoint.draftType, value: inline(sealGenerationRequestDraft(endpoint.ports, settings)) },
+ { id: "binding", type: endpoint.mediaBindings.referenceAudio!.type, value: inline({ role: "audio" }) },
+ ...(artifact === undefined ? [] : [{ id: "audio", value: artifact }]),
+ ],
+ needs: [],
+ plan: { steps: [
+ { id: "upstream", producer: { module: { name: "@test/audio", version: "1" }, name: "generate" }, inputs: {}, outputs: { audio: "audio" }, needs: {} },
+ { id: "bind", producer: endpoint.mediaBindings.referenceAudio!.producer, inputs: { draft: "draft", binding: "binding", artifact: "audio" }, outputs: { draft: "bound" }, needs: {} },
+ { id: "finalize", producer: endpoint.finalizeProducer, inputs: { draft: "bound" }, outputs: { request: "request" }, needs: {} },
+ { id: "generate", producer: endpoint.producer, inputs: { request: "request" }, outputs: {}, needs: { generation: { id: "need" } } },
+ ] },
+ } as unknown as BuildState;
+}
+
+test("Seedance activation and public definition share their component implementation", () => {
+ assert.equal(seedanceComponent, seedanceDefinition.component);
+});
+
+for (const [model, endpoint] of Object.entries(seedanceEndpointsByModel)) {
+ test(`${model}: visual classification survives runtime binding, finalization and generation`, async () => {
+ const { referenceImage, ...scalars } = settings;
+ for (const port of ["referenceImage", "referenceVideo", "firstFrame", "lastFrame"] as const) {
+ const role = port === "referenceVideo" ? "video" : "image";
+ const artifact = { ...referenceImage[0]!.artifact, mediaType: role === "video" ? "video/mp4" : "image/png" };
+ const initial = { ...scalars, ...(port === "lastFrame" ? { firstFrame: referenceImage } : {}) };
+ for (const flag of [true, false, undefined]) {
+ const binding = { role, ...(flag === undefined ? {} : { fields: { personReference: flag } }) };
+ const bound = await produce(endpoint.mediaBindings[port]!.producer, {
+ draft: input(inline(sealGenerationRequestDraft(endpoint.ports, initial))),
+ binding: input(inline(binding)), artifact: input(artifact),
+ });
+ const finalized = await produce(endpoint.finalizeProducer, { draft: input(bound.outputs.draft!) });
+ const generated = await produce(endpoint.producer, { request: input(finalized.outputs.request!) });
+ const request = generated.needs.generation as unknown as GenerationRequest;
+ assert.deepEqual(request.ports[port], [{ ...binding, artifact }]);
+ }
+ }
+ assert.throws(() => endpoint.sealRequest({ ...settings,
+ referenceAudio: [{ role: "audio", artifact: audio("audio/wav"), fields: { personReference: true } }],
+ }));
+ });
+
+ test(`${model}: M4A is rejected through runtime binding and complete request entry points`, async () => {
+ for (const mediaType of ["audio/mp4", "audio/x-m4a"]) {
+ const artifact = audio(mediaType);
+ const ports = { ...settings, referenceAudio: [{ role: "audio" as const, artifact }] };
+ // The generic envelope can represent this media; the exact model owns its restriction.
+ const request = sealGenerationRequestDraft(endpoint.ports, ports);
+ assert.throws(() => sealSeedanceRequest(endpoint.ports.model as keyof typeof seedanceEndpointsByModel, ports), /m4a/);
+ assert.throws(() => endpoint.sealRequest(ports), /m4a/);
+ const validator = seedanceComponent.validators.find((item) => item.type.name === endpoint.requestType.name)!;
+ await assert.rejects(async () => validator.handler({ value: inline(request) } as never), /m4a/);
+ await assert.rejects(produce(endpoint.finalizeProducer, { draft: input(inline(request)) }), /m4a/);
+ await assert.rejects(produce(endpoint.producer, { request: input(inline(request)) }), /m4a/);
+ await assert.rejects(produce(endpoint.mediaBindings.referenceAudio!.producer, {
+ draft: input(inline(sealGenerationRequestDraft(endpoint.ports, settings))),
+ binding: input(inline({ role: "audio" })), artifact: input(artifact),
+ }), /m4a/);
+ }
+ });
+
+ test(`${model}: supported audio still binds, finalizes and becomes a generation request`, async () => {
+ for (const mediaType of ["audio/wav", "audio/mpeg"]) {
+ const artifact = audio(mediaType);
+ const bound = await produce(endpoint.mediaBindings.referenceAudio!.producer, {
+ draft: input(inline(sealGenerationRequestDraft(endpoint.ports, settings))),
+ binding: input(inline({ role: "audio" })), artifact: input(artifact),
+ });
+ const finalized = await produce(endpoint.finalizeProducer, { draft: input(bound.outputs.draft!) });
+ const generated = await produce(endpoint.producer, { request: input(finalized.outputs.request!) });
+ assert.deepEqual(generated.needs.generation, endpoint.sealRequest({
+ ...settings, referenceAudio: [{ role: "audio", artifact }],
+ }));
+ }
+ });
+
+ test(`${model}: planning preserves future audio and rejects it when the actual unsupported value exists`, () => {
+ const pending = plannedExactModelRequest(assembly(endpoint), "generate", "generation", endpoint)!;
+ assert.equal(pending.complete, false);
+ assert.equal(pending.ports.referenceAudio, undefined);
+ assert.deepEqual(pending.pendingMedia, [{
+ port: "referenceAudio", role: "audio", record: "audio", sourceStep: "upstream", available: false,
+ }]);
+ assert.throws(() => plannedExactModelRequest(assembly(endpoint, audio("audio/mp4")), "generate", "generation", endpoint), /m4a/);
+ const known = plannedExactModelRequest(assembly(endpoint, audio("audio/wav")), "generate", "generation", endpoint)!;
+ assert.deepEqual(known.pendingMedia, []);
+ assert.deepEqual(known.ports.referenceAudio, [{ role: "audio", artifact: audio("audio/wav") }]);
+ });
+
+ test(`${model}: planning validates directly supplied requests and already formed Needs`, () => {
+ for (const mediaType of ["audio/mp4", "audio/wav"]) {
+ const request = { ports: { ...settings, referenceAudio: [{ role: "audio", artifact: audio(mediaType) }] } };
+ const state = assembly(endpoint);
+ const direct = { ...state, records: [...state.records, { id: "request", type: endpoint.requestType, value: inline(request) }] } as BuildState;
+ const withNeed = { ...state, needs: [{ id: "need", constraints: request }] } as unknown as BuildState;
+ for (const candidate of [direct, withNeed]) {
+ const plan = () => plannedExactModelRequest(candidate, "generate", "generation", endpoint);
+ if (mediaType === "audio/mp4") assert.throws(plan, /m4a/);
+ else assert.deepEqual(plan()!.ports, request.ports);
+ }
+ }
+ });
+}