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(provider-monid): serve MiniMax H3 (#286)

Sharky Wangc7ace07a2dad
diff --git a/docs/guide/service-partners.md b/docs/guide/service-partners.md
index 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 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 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, 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 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.md
index 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, and
diff --git a/packages/provider-monid/package.json b/packages/provider-monid/package.json
index 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.ts
index 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.ts
index 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: n
const 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: n
throw 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.ts
index 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.ts
index 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.yaml
index 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