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.
TypeScript agentic-aiaiai-agentsai-videocompilerdslffmpeggenerative-aillmmarkup-languagemonorepoplugin-systemprogramming-languagetext-to-videotypescriptvideovideo-automationvideo-clonevideo-editingvideo-generation
feat(provider-monid): serve MiniMax H3 (#286)
Sharky Wangc7ace07a2dad
diff --git a/docs/guide/service-partners.md b/docs/guide/service-partners.mdindex 6e157dcf..a971f422 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 andprices, 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 uploads reference media through Monid's workspace-file system. For another Monid tool, its+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[HTTP API documentation](https://monid.ai/docs/api/overview) supplies the connection details, andthe 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.mdindex 1e435069..cd24e1a0 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 系列端点,并通过 Monid 的工作区文件系统上传参考素材。+提供 Seedance 2.0、2.5 系列端点与 MiniMax H3,并通过 Monid 的工作区文件系统上传参考素材。使用 Monid 的其他工具时,[HTTP API 文档](https://monid.ai/docs/api/overview)提供接入依据,Agent 可以在项目包中实现这次所需的请求与结果映射。diff --git a/packages/provider-monid/README.md b/packages/provider-monid/README.mdindex e64f06b1..d4825c66 100644--- a/packages/provider-monid/README.md+++ b/packages/provider-monid/README.md@@ -1,8 +1,8 @@# `@hypit/provider-monid`-Hypit Runtime Provider for a [Monid](https://monid.ai) workspace. It runs Monid's `bytedance`-Seedance endpoints through `POST /v1/run`, polls `GET /v1/runs/{runId}` until the run is terminal,-downloads the returned `video_url` and stores the video in the current Build.+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.| Capability | Monid endpoint || --- | --- |@@ -10,20 +10,32 @@ downloads the returned `video_url` and stores the video in the current Build.| `@hypit/seedance@1#seedance-2-fast` | `bytedance` `/v1/video/seedance-2.0-fast` || `@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` |-Monid's catalogue also lists MiniMax H3 and other generation endpoints; their input schemas are-published only through the authenticated `inspect` operation, so this Provider maps the Seedance-endpoints whose request body Monid documents publicly.--The run `input` is the BytePlus ModelArk request the endpoint relays: 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`, `duration` and-`generate_audio`. Monid documents no web search field for these endpoints, so `web-search="true"`-is unsupported. Seedance 2.5 frame mode (`first-frame` present) requires `aspect-ratio="adaptive"`.-Seedance visual references may carry `person-reference`; the Provider accepts the declaration and-transmits nothing for it, since the endpoint has no field for it. Seedance rejects reference images-and videos that contain a real human face; Monid offers no way to register authorized portrait-material, so such a request fails with the upstream moderation error.+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.++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 Seedance endpoints add `generate_audio`. Monid documents no web search field for them, so+`web-search="true"` is unsupported, and Seedance 2.5 frame mode (`first-frame` present) requires+`aspect-ratio="adaptive"`. Seedance visual references may carry `person-reference`; the Provider+accepts the declaration and transmits nothing for it, since the endpoint has no field for it.+Seedance rejects reference images and videos that contain a real human face; Monid offers no way to+register authorized portrait material, so such a request fails with the upstream moderation error.++MiniMax H3 names its model in the body and takes neither of those two fields. The endpoint requires+a resolution, so a request that states none is sent at `2K`, the resolution the HypiHub Provider+also selects. It also requires a ratio that is not `adaptive` for text-to-video, while frame mode+resolves the framing from the uploaded image and reference-to-video defaults to adaptive: a+text-to-video request carrying no `aspect-ratio` is reported unsupported before any reference is+resolved, and the other two modes are sent as `adaptive`. H3 returns its video at `content.url`+rather than the ModelArk `video_url`.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, anddiff --git a/packages/provider-monid/package.json b/packages/provider-monid/package.jsonindex ab3f15f3..3fa4577c 100644--- a/packages/provider-monid/package.json+++ b/packages/provider-monid/package.json@@ -9,6 +9,7 @@"dependencies": {"@hypit/endpoint-kit": "workspace:*","@hypit/generation": "workspace:*",+ "@hypit/minimax-h3": "workspace:*","@hypit/protocol": "workspace:*","@hypit/runtime": "workspace:*","@hypit/runtime-kit": "workspace:*"diff --git a/packages/provider-monid/src/mapping.ts b/packages/provider-monid/src/mapping.tsindex 56562b44..99140967 100644--- a/packages/provider-monid/src/mapping.ts+++ b/packages/provider-monid/src/mapping.ts@@ -2,13 +2,21 @@ import type { ModuleRef } from "@hypit/protocol";import type { GenerationWireMapping } from "@hypit/generation";const SEEDANCE: ModuleRef = { name: "@hypit/seedance", version: "1" };+const MINIMAX_H3: ModuleRef = { name: "@hypit/minimax-h3", version: "1" };++/**+ * One mapping plus the Monid provider that relays the endpoint. Monid addresses an endpoint by+ * provider and path, so the provider travels with the mapping rather than being assumed.+ */+export type MonidMapping = GenerationWireMapping & { readonly service: string };/*** Monid `bytedance` endpoints and the fields their ModelArk request body takes. Media fields name* the `role` of a `content` item; routes.ts folds them into that array. `personReference` is* accepted on visual references and not transmitted: the endpoint has no field for it.*/-const seedance = (name: string, endpoint: string): GenerationWireMapping => ({+const seedance = (name: string, endpoint: string): MonidMapping => ({+ service: "bytedance",capability: { module: SEEDANCE, name }, result: "video", routes: [{ model: endpoint }],fields: {prompt: { as: "value", field: "text" },@@ -25,9 +33,34 @@ const seedance = (name: string, endpoint: string): GenerationWireMapping => ({},});-export const monidMappings: readonly GenerationWireMapping[] = [+/**+ * Monid's `minimax` MiniMax-H3 endpoint. It takes the same role-tagged `content` array as the+ * ModelArk endpoints above, names the model in the body, and carries neither a generated-audio nor+ * a web-search field. `resolution` is required by the endpoint while the model's port is optional,+ * so an unstated resolution is sent as the 2K the HypiHub Provider also selects.+ */+const minimaxH3: MonidMapping = {+ service: "minimax",+ capability: { module: MINIMAX_H3, name: "minimax-h3" }, result: "video",+ routes: [{ model: "/v1/video/minimax-h3" }],+ constants: { model: "MiniMax-H3" },+ fields: {+ prompt: { as: "value", field: "text" },+ referenceImage: { as: "urlArray", field: "reference_image" },+ referenceVideo: { as: "urlArray", field: "reference_video" },+ referenceAudio: { as: "urlArray", field: "reference_audio" },+ firstFrame: { as: "url", field: "first_frame" },+ lastFrame: { as: "url", field: "last_frame" },+ resolution: { as: "value", field: "resolution", whenAbsent: "2K" },+ aspectRatio: { as: "value", field: "ratio" },+ duration: { as: "value", field: "duration" },+ },+};++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,];diff --git a/packages/provider-monid/src/provider.ts b/packages/provider-monid/src/provider.tsindex 8cd695f5..0d2ff5d6 100644--- a/packages/provider-monid/src/provider.ts+++ b/packages/provider-monid/src/provider.ts@@ -65,11 +65,14 @@ function httpsUrl(value: unknown, subject: string): string {assert(typeof value === "string" && /^https?:\/\//u.test(value), `${subject} has no URL`);return value;}-/** The relayed ModelArk result; Monid returns the task's `video_url` in the run output. */+/**+ * 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.+ */function outputVideoUrl(run: Record<string, unknown>): string {const output = object(run.output, "Monid run output");- const nested = output.content !== undefined ? object(output.content, "Monid run output content").video_url : undefined;- return httpsUrl(output.video_url ?? nested, "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 extensions: Readonly<Record<string, string>> = {"image/jpeg": "jpg", "image/png": "png", "image/webp": "webp", "video/mp4": "mp4", "video/quicktime": "mov",@@ -160,7 +163,7 @@ function endpoint(client: MonidClient, pollIntervalMs: number, maxOperationMs: nconst route = monidRouteForCapability(context.need.capability);assert(route !== undefined, "Monid does not implement this exact capability");const request = route.prepare(context.need.constraints);- await context.reportProgress?.({ phase: `Preparing Monid request: bytedance ${request.endpoint}` });+ await context.reportProgress?.({ phase: `Preparing Monid request: ${request.service} ${request.endpoint}` });let input: Record<string, unknown>;try {input = await request.compile(resolverFor(client, context, publicAssetUrl));@@ -168,8 +171,8 @@ function endpoint(client: MonidClient, pollIntervalMs: number, maxOperationMs: nthrow new MonidServiceError(error instanceof MonidServiceError ? error.code : "MONID_ERROR",`Monid request preparation failed; endpoint=${request.endpoint}; generation not submitted: ${failureMessage(error)}`);}- await context.reportProgress?.({ phase: `Submitting Monid request: bytedance ${request.endpoint}` });- const { body: run } = await client.run({ provider: "bytedance", endpoint: request.endpoint, input }, apiKey(context.credentials));+ await context.reportProgress?.({ phase: `Submitting Monid request: ${request.service} ${request.endpoint}` });+ const { body: run } = await client.run({ provider: request.service, endpoint: request.endpoint, input }, apiKey(context.credentials));const handle: Handle = { contract: "hypit.monid-operation@1", runId: runId(run), route: route.key, startedAt: Date.now() };const receipt = { id: handle.runId };const ended = monidTerminalStatuses.includes(String(run.status) as typeof monidTerminalStatuses[number]);@@ -230,7 +233,7 @@ export function createMonidProvider(options: CreateMonidProviderOptions = {}) {const asyncEndpoint = endpoint(client, pollIntervalMs, operationTimeoutMs, options.publicAssetUrl);return defineEndpointPackage({module: monidProviderModuleRef, facet: "gateway", instance: options.instance ?? "monid.default", pool: options.pool ?? options.instance ?? "monid.default",- pricing: { kind: "page", url: "https://monid.ai/tools/bytedance" },+ pricing: { kind: "page", url: "https://monid.ai/tools" },credentials: { apiKey: options.apiKey ?? credentialRef("os", "monid.api-key") },credentialInputs: { apiKey: { label: "Monid API key" } },defaultConcurrency: options.defaultConcurrency ?? 4,diff --git a/packages/provider-monid/src/routes.ts b/packages/provider-monid/src/routes.tsindex 93ee7b21..99351764 100644--- a/packages/provider-monid/src/routes.ts+++ b/packages/provider-monid/src/routes.ts@@ -4,19 +4,22 @@ import {generationTypes,sealGeneratedVideoSet,} from "@hypit/generation";-import type { GenerationArtifactUrlResolver, GenerationRequest, GenerationWireMapping } from "@hypit/generation";+import type { GenerationArtifactUrlResolver, GenerationRequest } from "@hypit/generation";import { canonicalize } from "@hypit/protocol";import type { BlobRef, CapabilityRef, CanonicalValue, StoredValue, TypeRef } from "@hypit/protocol";import type { EndpointRequest, EndpointSupport } from "@hypit/endpoint-kit";import { monidMappings } from "./mapping.js";+import type { MonidMapping } from "./mapping.js";export type MonidPreparedRequest = {- /** Monid endpoint path under the `bytedance` provider. */+ /** Monid provider relaying the endpoint. */+ readonly service: string;+ /** Monid endpoint path under that provider. */readonly endpoint: string;readonly compile: (resolve: GenerationArtifactUrlResolver) => Promise<Record<string, unknown>>;};-export type MonidRoute = GenerationWireMapping & {+export type MonidRoute = MonidMapping & {readonly key: string;readonly returns: TypeRef;readonly supports: (request: EndpointRequest) => EndpointSupport;@@ -35,7 +38,21 @@ function strings(value: unknown): readonly string[] {return Array.isArray(value) ? value.filter((item): item is string => typeof item === "string" && item.length > 0) : [];}-function rejection(mapping: GenerationWireMapping, request: GenerationRequest): string | undefined {+function referenceToVideo(request: GenerationRequest): boolean {+ return present(request, "referenceImage") || present(request, "referenceVideo") || present(request, "referenceAudio");+}++function rejection(mapping: MonidMapping, request: GenerationRequest): string | undefined {+ 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+ // takes no adaptive ratio there, so the aspect ratio has to be stated.+ if (!present(request, "firstFrame") && !present(request, "lastFrame") && !referenceToVideo(request)+ && scalar(request, "aspectRatio") === undefined) {+ return "MiniMax H3 text-to-video on Monid requires an aspect ratio";+ }+ return undefined;+ }if (scalar(request, "webSearch") === true) {return "Monid's Seedance endpoints document no web search field";}@@ -54,6 +71,7 @@ function arkInput(input: Record<string, unknown>): Record<string, unknown> {const first = input.first_frame;const last = input.last_frame;return {+ ...(typeof input.model === "string" ? { model: input.model } : {}),content: [{ type: "text", text: input.text },...(typeof first === "string" ? [contentItem("image_url", first, "first_frame")] : []),@@ -69,6 +87,15 @@ function arkInput(input: Record<string, unknown>): Record<string, unknown> {};}+/**+ * MiniMax-H3 takes a required ratio: frame mode and reference-to-video both resolve to adaptive,+ * and rejection() has already required a stated ratio for text-to-video.+ */+function minimaxH3Input(input: Record<string, unknown>): Record<string, unknown> {+ const body = arkInput(input);+ return { ...body, ratio: body.ratio ?? "adaptive" };+}+function capabilityKey(capability: CapabilityRef): string {return `${capability.module.name}@${capability.module.version}#${capability.name}`;}@@ -85,9 +112,11 @@ 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;return {+ service: mapping.service,endpoint: selectWireModelForRequest(mapping, request),- compile: async (resolve) => arkInput((await compileWireRequest(mapping, request, resolve)).input as Record<string, unknown>),+ compile: async (resolve) => body((await compileWireRequest(mapping, request, resolve)).input as Record<string, unknown>),};},packageResult: (artifacts) => ({diff --git a/packages/provider-monid/test/routes.test.ts b/packages/provider-monid/test/routes.test.tsindex 6ff6077d..e644dd1f 100644--- a/packages/provider-monid/test/routes.test.ts+++ b/packages/provider-monid/test/routes.test.ts@@ -2,6 +2,7 @@ import assert from "node:assert/strict";import test from "node:test";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 { monidMappings } from "../src/mapping.js";@@ -12,7 +13,10 @@ const resolve = async () => "https://sfs.monid.ai/signed";test("every Monid mapping covers its model's ports", () => {for (const mapping of monidMappings) {- assertMappingCoversPorts(seedancePorts[mapping.capability.name as keyof typeof seedancePorts], mapping);+ const ports = mapping.capability.module.name === "@hypit/minimax-h3"+ ? minimaxH3Ports+ : seedancePorts[mapping.capability.name as keyof typeof seedancePorts];+ assertMappingCoversPorts(ports, mapping);}});diff --git a/pnpm-lock.yaml b/pnpm-lock.yamlindex 9ee15624..f238305b 100644--- a/pnpm-lock.yaml+++ b/pnpm-lock.yaml@@ -2435,6 +2435,9 @@ importers:'@hypit/generation':specifier: workspace:*version: link:../generation+ '@hypit/minimax-h3':+ specifier: workspace:*+ version: link:../minimax-h3'@hypit/protocol':specifier: workspace:*version: link:../protocol