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(providers): add TokenDance, HiAPI, Pollo and Monid gateway Providers (#282)

Sharky Wang6386639f2e85
diff --git a/docs/guide/providers.md b/docs/guide/providers.md
index 7495c357..80a48770 100644
--- a/docs/guide/providers.md
+++ b/docs/guide/providers.md
@@ -8,7 +8,8 @@ A **Provider** knows how to fulfill that request through a particular service. A
configured instance of that Provider, with its service address, credential reference and capacity.
The Runtime Profile binds the requested capability to an Endpoint.
-Hypit's official Distribution includes local Providers and the HypiHub Provider. Other services
+Hypit's official Distribution includes local Providers, the HypiHub Provider, and API-key Providers
+for TokenDance, HiAPI, Pollo and Monid that serve the installed models each service offers. Other services
connect through packages owned by the production or their authors. The Agent can implement a new
service through the public SDK, just as it can create a visual component for a video.
[Model and deployment services](./service-partners.md) introduces independent partners through that
diff --git a/docs/guide/service-partners.md b/docs/guide/service-partners.md
index 72407b5e..6e157dcf 100644
--- a/docs/guide/service-partners.md
+++ b/docs/guide/service-partners.md
@@ -11,22 +11,48 @@ work. Its Provider is maintained with Hypit. Local execution remains available t
Providers, and users can connect their own services through project Providers.
The services introduced below are independent partners. They have their own accounts, terms,
-prices, model availability and APIs. A partnership is an introduction, not a shared HypiHub account
-or an automatically installed integration. Choose a service for the work and connect its supported
-capabilities through the ordinary [Model and Provider](./providers.md) extension path.
+prices, model availability and APIs. A partnership is an introduction, not a shared HypiHub account.
+The Distribution bundles an API-key Provider for each service named below; each Provider maps the
+installed models that service offers and reports that service's input limits, and its README lists
+both. A model the service offers beyond that set connects through the ordinary
+[Model and Provider](./providers.md) extension path.
## Model and tool API partners
+### TokenDance
+
+[TokenDance](https://tokendance.space) is a multi-model gateway.
+[`@hypit/provider-tokendance`](https://github.com/hypit-ai/hypit/blob/main/packages/provider-tokendance/README.md)
+serves the Seedance 2.0 and 2.5 models, Seedream 5.0 lite and MiniMax H3 through the Ark and
+MiniMax protocols TokenDance documents. Its
+[documentation index](https://tokendance.space/llms.txt) and live model catalogue supply the
+details of other models.
+
+### HiAPI
+
+[HiAPI](https://www.hiapi.ai) offers image, video and audio models through one asynchronous task
+API. [`@hypit/provider-hiapi`](https://github.com/hypit-ai/hypit/blob/main/packages/provider-hiapi/README.md)
+serves the Seedance, Seedream 5.0 lite, MiniMax H3, GPT Image 2, Nano Banana and Grok Imagine
+models the Distribution describes. Its [model index](https://www.hiapi.ai/docs/models.json) lists
+the rest.
+
+### Pollo
+
+[Pollo AI](https://docs.pollo.ai) offers video and image models through per-model generation
+paths. [`@hypit/provider-pollo`](https://github.com/hypit-ai/hypit/blob/main/packages/provider-pollo/README.md)
+serves MiniMax H3, Grok Imagine 1.5, GPT Image 2 and Nano Banana. Pollo takes reference media by
+public URL only, so a request with reference media needs a URL the embedding caller supplies.
+
### Monid
[Monid](https://monid.ai) is a Hypit service partner.
-[Its documentation](https://docs.monid.ai/) describes discovering tools, inspecting their inputs and
-prices, and calling them through its interfaces. For a video production, identify the concrete
-image, video, audio or other tool that meets the material requirement. Its
-[HTTP API documentation](https://docs.monid.ai/api/overview.html) supplies the connection details.
-An installed compatible Provider can be reused; otherwise the Agent can implement the required
-request and result mapping in a project package. Availability of a tool does not itself install
-a Hypit Provider for it.
+[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
+[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.
## Your own model deployment
diff --git a/docs/quickstart/generation.md b/docs/quickstart/generation.md
index 7e77517e..f91a2a72 100644
--- a/docs/quickstart/generation.md
+++ b/docs/quickstart/generation.md
@@ -152,7 +152,8 @@ On an image or video reference, `person-reference="true"` declares a person/avat
material, including a generated human likeness. Use false for a reference without that content;
omission leaves the classification unspecified. Audio references do not use this visual flag.
Frame mode provides `first-frame-person-reference` and `last-frame-person-reference`. The selected
-Provider carries this fact through the service's media preparation.
+Provider carries this fact through the service's media preparation; a service without such a field
+accepts the declaration without transmitting it.
A video reference can guide dance, physical action or camera movement while images guide the new
appearance. Choose an excerpt that carries the intended motion within the selected model and
diff --git a/docs/zh/guide/providers.md b/docs/zh/guide/providers.md
index cbdf75c7..18a7c165 100644
--- a/docs/zh/guide/providers.md
+++ b/docs/zh/guide/providers.md
@@ -5,7 +5,7 @@ description: 选择账户、连接服务或添加模型,沿用同一套视频
**Model** 定义要生成什么:输入、支持的参数和输出类型。**Provider** 知道如何通过某个服务完成这个请求。**Endpoint** 是配置好的 Provider 实例,包含服务地址、凭据引用和容量。Runtime Profile 将所需能力绑定到 Endpoint。
-官方发行包含本地 Provider 和 HypiHub Provider。其他服务通过项目或作者自己的包接入;Agent 可以使用公开 SDK 编写所需接入,就像为视频创建视觉组件。[模型与部署服务](./service-partners.md) 集中介绍独立合作服务,它们沿用同一套扩展方式。选择执行服务,与[选择 Agent 工作环境](./agents.md)是两件事。
+官方发行包含本地 Provider、HypiHub Provider,以及 TokenDance、HiAPI、Pollo、Monid 四个使用 API Key 的 Provider,各自覆盖该服务提供的已安装模型。其他服务通过项目或作者自己的包接入;Agent 可以使用公开 SDK 编写所需接入,就像为视频创建视觉组件。[模型与部署服务](./service-partners.md) 集中介绍独立合作服务,它们沿用同一套扩展方式。选择执行服务,与[选择 Agent 工作环境](./agents.md)是两件事。
HypiHub 是我们推荐的集成托管服务。**BYOK** 指使用自己账户的 API Key:Key 通过兼容的 Provider 连接到签发它的服务。告诉 Agent 你已有哪个服务及其 API 文档,具体接线和项目包可以由 Agent 完成。Key 负责授权请求,本身不会实现 API 接口。一个项目可以为不同能力使用不同服务,分别使用各自的账户并按各自规则计费。
diff --git a/docs/zh/guide/service-partners.md b/docs/zh/guide/service-partners.md
index 84301d46..1e435069 100644
--- a/docs/zh/guide/service-partners.md
+++ b/docs/zh/guide/service-partners.md
@@ -9,19 +9,42 @@ HypiHub 是 Hypit 推荐的集成托管服务,提供已支持的生成与 Whis
维护。本地能力仍可通过本地 Provider 使用,用户自己的服务通过项目 Provider 接入。
下面介绍的合作方是独立服务,各有自己的账户、条款、价格、模型可用性和 API。
-合作关系提供一个了解服务的入口,不共用 HypiHub 账户,也不意味着已经自动安装了适配。
-根据当前作品选择服务,通过普通的 [Model 与 Provider](./providers.md) 扩展方式连接所需能力。
+合作关系提供一个了解服务的入口,不共用 HypiHub 账户。
+发行包为下面每个服务内置了一个使用 API Key 的 Provider,覆盖该服务提供的已安装模型,
+并按该服务的输入限制报告不支持的请求;具体清单见各 Provider 的 README。
+服务提供、但不在这个范围内的模型,通过普通的 [Model 与 Provider](./providers.md) 扩展方式连接。
## 模型与工具 API 合作方
+### TokenDance
+
+[TokenDance](https://tokendance.space) 是多模型网关。
+[`@hypit/provider-tokendance`](https://github.com/hypit-ai/hypit/blob/main/packages/provider-tokendance/README.md)
+按 TokenDance 文档中的方舟与 MiniMax 协议提供 Seedance 2.0、2.5 系列、Seedream 5.0 lite 和 MiniMax H3。
+其他模型见它的[文档索引](https://tokendance.space/llms.txt)和实时模型目录。
+
+### HiAPI
+
+[HiAPI](https://www.hiapi.ai) 通过一个异步任务接口提供图片、视频和音频模型。
+[`@hypit/provider-hiapi`](https://github.com/hypit-ai/hypit/blob/main/packages/provider-hiapi/README.md)
+提供发行包已描述的 Seedance、Seedream 5.0 lite、MiniMax H3、GPT Image 2、Nano Banana 和 Grok Imagine 模型。
+其余模型见它的[模型索引](https://www.hiapi.ai/docs/models.json)。
+
+### Pollo
+
+[Pollo AI](https://docs.pollo.ai) 按模型路径提供视频和图片生成。
+[`@hypit/provider-pollo`](https://github.com/hypit-ai/hypit/blob/main/packages/provider-pollo/README.md)
+提供 MiniMax H3、Grok Imagine 1.5、GPT Image 2 和 Nano Banana。
+Pollo 只接受公网 URL 形式的参考素材,带参考素材的请求需要由嵌入方提供 URL。
+
### Monid
[Monid](https://monid.ai) 是 Hypit 的服务合作方。
-[它的文档](https://docs.monid.ai/)介绍了工具发现、输入与价格查询,以及调用方式。
-制作视频时,根据具体素材需要找到合适的图片、视频、音频或其他工具,
-[HTTP API 文档](https://docs.monid.ai/api/overview.html)提供接入依据。
-已有兼容 Provider 可以复用;缺少时,Agent 可以在项目包中实现这次所需的请求与结果映射。
-服务里存在某个工具,并不意味着项目已经安装了对应的 Hypit Provider。
+[它的文档](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 的工作区文件系统上传参考素材。
+使用 Monid 的其他工具时,[HTTP API 文档](https://monid.ai/docs/api/overview)提供接入依据,
+Agent 可以在项目包中实现这次所需的请求与结果映射。
## 自己部署模型
diff --git a/docs/zh/quickstart/generation.md b/docs/zh/quickstart/generation.md
index 0adde651..6bd141be 100644
--- a/docs/zh/quickstart/generation.md
+++ b/docs/zh/quickstart/generation.md
@@ -136,7 +136,7 @@ Seedance 2.5 复用同样的 Surface,而不是由 Runtime 把别的模型偷
图片或视频参考上的 `person-reference="true"` 声明素材中含有人物/数字人形象,AI 生成的人像也适用。
没有这类内容时可写 false;省略表示没有提供分类。音频参考不使用这个视觉标记。
首尾帧模式提供 `first-frame-person-reference` 和 `last-frame-person-reference`。
-选定的 Provider 负责把这项事实交给服务的素材准备流程。
+选定的 Provider 负责把这项事实交给服务的素材准备流程;服务 API 没有对应字段时,Provider 接受这项声明但不传输。
舞蹈、身体动作或运镜可以由参考视频提供运动依据,再用参考图指定新的形象与场景。
围绕需要保留的动作选取片段,并核对模型与服务的参考视频时长上限;它和要生成的视频时长是两回事。
diff --git a/package.json b/package.json
index 3e406c72..53a58d4e 100644
--- a/package.json
+++ b/package.json
@@ -236,9 +236,13 @@
"@hypit/project-context-node": "workspace:*",
"@hypit/protocol": "workspace:*",
"@hypit/provider-hyperframes-local": "workspace:*",
+ "@hypit/provider-hiapi": "workspace:*",
"@hypit/provider-hypihub": "workspace:*",
"@hypit/provider-image-opencv-local": "workspace:*",
"@hypit/provider-media-local": "workspace:*",
+ "@hypit/provider-monid": "workspace:*",
+ "@hypit/provider-pollo": "workspace:*",
+ "@hypit/provider-tokendance": "workspace:*",
"@hypit/provider-whisperx-local": "workspace:*",
"@hypit/ranking": "workspace:*",
"@hypit/ranking-studio": "workspace:*",
diff --git a/packages/provider-hiapi/README.md b/packages/provider-hiapi/README.md
new file mode 100644
index 00000000..75420acc
--- /dev/null
+++ b/packages/provider-hiapi/README.md
@@ -0,0 +1,75 @@
+# `@hypit/provider-hiapi`
+
+Hypit Runtime Provider for a [HiAPI](https://www.hiapi.ai) account. Every capability submits one
+task to `POST /v1/tasks` with the model's documented `input` fields, polls
+`GET /v1/tasks/{taskId}` until the task is terminal, downloads `data.output[].url` and stores the
+files in the current Build. Submission carries an `Idempotency-Key`, so a retried submission returns
+the original task.
+
+| Capability | HiAPI model |
+| --- | --- |
+| `@hypit/seedance@1#seedance-2` | `seedance-2.0` |
+| `@hypit/seedance@1#seedance-2-fast` | `seedance-2.0-fast` |
+| `@hypit/seedance@1#seedance-2-mini` | `seedance-2.0-mini` |
+| `@hypit/seedance@1#seedance-2.5` | `seedance-2.5/reference-to-video` with a reference video, `seedance-2.5/image-to-video` with frames, reference images or reference audio, otherwise `seedance-2.5/text-to-video` |
+| `@hypit/seedream@1#seedream-5-lite` | `seedream-5.0-lite/image-to-image` with references, otherwise `seedream-5.0-lite/text-to-image` |
+| `@hypit/minimax-h3@1#minimax-h3` | `minimax-h3` |
+| `@hypit/gpt-image@1#gpt-image-2` | `gpt-image-2/image-to-image` with references, otherwise `gpt-image-2/text-to-image` |
+| `@hypit/nano-banana@1#nano-banana-2` | `Nano-Banana-2` |
+| `@hypit/nano-banana@1#nano-banana-pro` | `Nano-Banana-Pro` |
+| `@hypit/grok-imagine@1#grok-imagine-video` | `grok-imagine/image-to-video` with images, otherwise `grok-imagine/text-to-video` |
+| `@hypit/grok-imagine@1#grok-imagine-video-1.5-preview` | `grok-imagine-1.5/image-to-video` |
+
+HiAPI's model index at `https://www.hiapi.ai/docs/models.json` lists further models and routes;
+this Provider maps only the models the Distribution already describes, on each model's standard
+route.
+
+Service limits this Provider reports as unsupported before submitting:
+
+- `seedance-2.0-mini` has no `web_search` field; `web-search="true"` is unsupported there.
+- `seedance-2.5/image-to-video` takes only `aspect-ratio="adaptive"`; `text-to-video` and
+ `image-to-video` render 720p or 1080p, `reference-to-video` also 480p.
+- Seedream 5.0 lite renders 2K (`quality="basic"`) or 4K (`quality="ultra"`); `high` (3K) is
+ unsupported. `output-format` and `nsfw-check` have no HiAPI field and are not sent.
+- `minimax-h3` renders 2K only and accepts up to five reference images; requests send
+ `watermark: false`.
+- GPT Image 2: `background` only at 1K; `auto` ratio only at 1K; 2K excludes `5:4`, `4:5`, `3:1`,
+ `1:3`, `9:21`; 4K excludes `1:1`, `3:1`, `1:3`, `9:21`; image-to-image takes up to six references.
+- Grok Imagine renders 480p or 720p; `grok-imagine-1.5/image-to-video` animates exactly one image.
+
+Seedance visual references may carry `person-reference`; the Provider accepts the declaration and
+transmits nothing for it, since HiAPI has no field for it. Seedance rejects reference images and
+videos that contain a real human face; HiAPI offers no way to register authorized portrait material,
+so such a request fails with the service's moderation error.
+
+Reference images and audio travel inline as `data:` URLs, which HiAPI documents for its Seedance
+inputs, within the per-file sizes each model page states: 30 MB images and 15 MB audio for
+`seedance-2.0-mini` and the Seedance 2.5 models (2.5 also caps combined images at 120 MB), 10 MB
+images for `seedream-5.0-lite/image-to-image` and `grok-imagine/image-to-video`, 20 MB for
+`grok-imagine-1.5/image-to-video`, 30 MB for `Nano-Banana-Pro`. The Provider checks these before
+submitting. A reference video must be a public HTTPS URL; configure `publicAssetUrl` when embedding
+the Provider, otherwise such a request fails before submission.
+
+Runtime Profile example:
+
+```json
+{
+ "endpoints": {
+ "hiapi.default": {
+ "use": "@hypit/provider-hiapi",
+ "pool": "hiapi.default",
+ "config": {
+ "apiKey": { "store": "platform", "key": "hiapi.api-key" },
+ "defaultConcurrency": 3,
+ "pollIntervalMs": 10000
+ }
+ }
+ }
+}
+```
+
+`baseUrl` defaults to `https://api.hiapi.ai`. Store the API key with
+`hypit auth login hiapi.default --runtime hypit.runtime.json`. Optional `requestTimeoutMs`,
+`operationTimeoutMs` and `actionLimits` bound single HTTP calls, the whole remote task and action
+concurrency. HTTP failures keep HiAPI's `error_code` and message; failed tasks keep
+`data.error.code` and message, with any signed URL in the message redacted.
diff --git a/packages/provider-hiapi/package.json b/packages/provider-hiapi/package.json
new file mode 100644
index 00000000..80dbd109
--- /dev/null
+++ b/packages/provider-hiapi/package.json
@@ -0,0 +1,24 @@
+{
+ "name": "@hypit/provider-hiapi",
+ "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/endpoint-kit": "workspace:*",
+ "@hypit/generation": "workspace:*",
+ "@hypit/protocol": "workspace:*",
+ "@hypit/runtime": "workspace:*",
+ "@hypit/runtime-kit": "workspace:*"
+ },
+ "devDependencies": {
+ "@hypit/gpt-image": "workspace:*",
+ "@hypit/grok-imagine": "workspace:*",
+ "@hypit/minimax-h3": "workspace:*",
+ "@hypit/nano-banana": "workspace:*",
+ "@hypit/seedance": "workspace:*",
+ "@hypit/seedream": "workspace:*"
+ }
+}
diff --git a/packages/provider-hiapi/src/activation.ts b/packages/provider-hiapi/src/activation.ts
new file mode 100644
index 00000000..61814ddc
--- /dev/null
+++ b/packages/provider-hiapi/src/activation.ts
@@ -0,0 +1,62 @@
+import {
+ createRuntimeEndpointAdapterFacet,
+ runtimeConfigCredentialRef,
+ runtimeConfigActionLimits,
+ runtimeConfigExact,
+ runtimeConfigObject,
+ runtimeConfigPositiveInteger,
+ runtimeConfigString,
+} from "@hypit/runtime-kit";
+
+import { createHiApiProvider } from "./provider.js";
+
+const adapter = createRuntimeEndpointAdapterFacet({
+ use: "@hypit/provider-hiapi",
+ activate(context) {
+ if (context.pool === undefined) throw new Error("HiAPI Provider Pool is required");
+ const config = runtimeConfigObject(context.config, "HiAPI");
+ runtimeConfigExact(config, [
+ "baseUrl",
+ "apiKey",
+ "defaultConcurrency",
+ "actionLimits",
+ "pollIntervalMs",
+ "requestTimeoutMs",
+ "operationTimeoutMs",
+ ], "HiAPI");
+ const baseUrl = runtimeConfigString(config.baseUrl, "HiAPI baseUrl");
+ if (baseUrl !== undefined) {
+ const url = new URL(baseUrl);
+ if (url.protocol !== "https:" && url.hostname !== "localhost" && url.hostname !== "127.0.0.1") {
+ throw new Error("HiAPI baseUrl must use HTTPS or loopback");
+ }
+ }
+ const apiKey = runtimeConfigCredentialRef(config.apiKey, "HiAPI apiKey");
+ if (apiKey === undefined) throw new Error("HiAPI apiKey CredentialRef is required");
+ const actionLimits = runtimeConfigActionLimits(config.actionLimits);
+ const defaultConcurrency = runtimeConfigPositiveInteger(config.defaultConcurrency, "HiAPI defaultConcurrency");
+ const pollIntervalMs = runtimeConfigPositiveInteger(config.pollIntervalMs, "HiAPI pollIntervalMs");
+ const requestTimeoutMs = runtimeConfigPositiveInteger(config.requestTimeoutMs, "HiAPI requestTimeoutMs");
+ const operationTimeoutMs = runtimeConfigPositiveInteger(config.operationTimeoutMs, "HiAPI operationTimeoutMs");
+ return {
+ endpoint: createHiApiProvider({
+ instance: context.instance,
+ pool: context.pool,
+ ...(baseUrl === undefined ? {} : { baseUrl }),
+ apiKey,
+ ...(defaultConcurrency === undefined ? {} : { defaultConcurrency }),
+ ...(actionLimits === undefined ? {} : { actionLimits }),
+ ...(pollIntervalMs === undefined ? {} : { pollIntervalMs }),
+ ...(requestTimeoutMs === undefined ? {} : { requestTimeoutMs }),
+ ...(operationTimeoutMs === undefined ? {} : { operationTimeoutMs }),
+ }),
+ };
+ },
+});
+
+export const hypitPackage = {
+ format: "hypit.node-package@1" as const,
+ hostFacets: [adapter],
+};
+
+export default hypitPackage;
diff --git a/packages/provider-hiapi/src/errors.ts b/packages/provider-hiapi/src/errors.ts
new file mode 100644
index 00000000..0e32e849
--- /dev/null
+++ b/packages/provider-hiapi/src/errors.ts
@@ -0,0 +1,44 @@
+/** HiAPI's `{ code, message, error_code }` envelope and task `error` object, kept at the service boundary. */
+function record(value: unknown): Record<string, unknown> | undefined {
+ return value !== null && typeof value === "object" && !Array.isArray(value)
+ ? value as Record<string, unknown> : undefined;
+}
+function text(value: unknown): string | undefined {
+ return typeof value === "string" && value.trim().length > 0 ? value.trim() : undefined;
+}
+
+// Responses may mention a signed asset URL. Keep the reason, not its access capability.
+export function safeHiApiReason(value: string): string {
+ return value.replace(/https?:\/\/\S+/giu, "[redacted-url]");
+}
+
+export class HiApiServiceError extends Error {
+ constructor(readonly code: string, message: string) { super(message); }
+}
+
+export class HiApiHttpError extends HiApiServiceError {
+ constructor(readonly status: number, response: { readonly headers: Headers }, bodyText: string,
+ request: { readonly method: string; readonly path: string; readonly model?: string }) {
+ let body: Record<string, unknown> | undefined;
+ try { body = record(JSON.parse(bodyText)); } catch { /* Non-JSON gateway failures still have HTTP evidence. */ }
+ const code = text(body?.error_code) ?? "HIAPI_HTTP_ERROR";
+ const reason = text(body?.message) ?? (body === undefined ? text(bodyText.slice(0, 2000)) : undefined);
+ const requestId = text(response.headers.get("x-request-id"));
+ const facts = [
+ `HiAPI HTTP ${status}`, code, `${request.method} ${request.path}`,
+ ...(request.model === undefined ? [] : [`model=${request.model}`]),
+ ...(requestId === undefined ? [] : [`request=${requestId}`]),
+ ];
+ super(code, `${facts.join("; ")}${reason === undefined ? "" : `: ${safeHiApiReason(reason)}`}`);
+ }
+}
+
+/** A terminal `fail` task; `undefined` otherwise. */
+export function hiApiTaskFailure(task: Record<string, unknown>, id: string): HiApiServiceError | undefined {
+ if (task.status !== "fail") return undefined;
+ const error = record(task.error);
+ const code = text(error?.code) ?? "HIAPI_TASK_FAILED";
+ const reason = text(error?.message);
+ return new HiApiServiceError(code,
+ `HiAPI task ${id} failed; ${code}${reason === undefined ? "" : `: ${safeHiApiReason(reason)}`}`);
+}
diff --git a/packages/provider-hiapi/src/index.ts b/packages/provider-hiapi/src/index.ts
new file mode 100644
index 00000000..858cd7de
--- /dev/null
+++ b/packages/provider-hiapi/src/index.ts
@@ -0,0 +1,2 @@
+export { createHiApiProvider, hiApiProviderModuleRef } from "./provider.js";
+export type { CreateHiApiProviderOptions } from "./provider.js";
diff --git a/packages/provider-hiapi/src/mapping.ts b/packages/provider-hiapi/src/mapping.ts
new file mode 100644
index 00000000..d4393b0d
--- /dev/null
+++ b/packages/provider-hiapi/src/mapping.ts
@@ -0,0 +1,129 @@
+import type { ModuleRef } from "@hypit/protocol";
+import type { GenerationWireMapping } from "@hypit/generation";
+
+const SEEDANCE: ModuleRef = { name: "@hypit/seedance", version: "1" };
+const SEEDREAM: ModuleRef = { name: "@hypit/seedream", version: "1" };
+const MINIMAX: ModuleRef = { name: "@hypit/minimax-h3", version: "1" };
+const GPT_IMAGE: ModuleRef = { name: "@hypit/gpt-image", version: "1" };
+const NANO_BANANA: ModuleRef = { name: "@hypit/nano-banana", version: "1" };
+const GROK: ModuleRef = { name: "@hypit/grok-imagine", version: "1" };
+
+/**
+ * HiAPI model IDs and the `input` fields each documents. A model whose HiAPI ID depends on the
+ * request shape (text, frames or references) lists one route per shape; the first route whose
+ * ports are present wins. `personReference` is accepted on Seedance visual references and not
+ * transmitted: HiAPI has no field for it.
+ */
+const seedanceFields = {
+ prompt: { as: "value", field: "prompt" },
+ aspectRatio: { as: "value", field: "aspect_ratio" },
+ duration: { as: "value", field: "duration" },
+ resolution: { as: "value", field: "resolution" },
+ firstFrame: { as: "url", field: "first_frame_url", resourceFields: ["personReference"] },
+ lastFrame: { as: "url", field: "last_frame_url", resourceFields: ["personReference"] },
+ referenceImage: { as: "urlArray", field: "reference_image_urls", resourceFields: ["personReference"] },
+ referenceVideo: { as: "urlArray", field: "reference_video_urls", resourceFields: ["personReference"] },
+ referenceAudio: { as: "urlArray", field: "reference_audio_urls" },
+ generateAudio: { as: "value", field: "generate_audio" },
+ webSearch: { as: "value", field: "web_search" },
+} as const satisfies GenerationWireMapping["fields"];
+
+const seedance2 = (name: string, model: string): GenerationWireMapping => ({
+ capability: { module: SEEDANCE, name }, result: "video", routes: [{ model }], fields: seedanceFields,
+});
+
+export const hiApiMappings: readonly GenerationWireMapping[] = [
+ seedance2("seedance-2", "seedance-2.0"),
+ seedance2("seedance-2-fast", "seedance-2.0-fast"),
+ seedance2("seedance-2-mini", "seedance-2.0-mini"),
+ {
+ capability: { module: SEEDANCE, name: "seedance-2.5" }, result: "video",
+ routes: [
+ { model: "seedance-2.5/reference-to-video", whenPresent: ["referenceVideo"] },
+ { model: "seedance-2.5/image-to-video", whenPresent: ["firstFrame"] },
+ { model: "seedance-2.5/image-to-video", whenPresent: ["referenceImage"] },
+ { model: "seedance-2.5/image-to-video", whenPresent: ["referenceAudio"] },
+ { model: "seedance-2.5/text-to-video" },
+ ],
+ fields: seedanceFields,
+ },
+ {
+ capability: { module: SEEDREAM, name: "seedream-5-lite" }, result: "image",
+ routes: [
+ { model: "seedream-5.0-lite/image-to-image", whenPresent: ["images"] },
+ { model: "seedream-5.0-lite/text-to-image" },
+ ],
+ fields: {
+ prompt: { as: "value", field: "prompt" },
+ aspectRatio: { as: "value", field: "aspect_ratio" },
+ quality: { as: "value", field: "quality" },
+ outputFormat: { as: "value", field: "output_format" },
+ nsfwCheck: { as: "value", field: "nsfw_check" },
+ images: { as: "urlArray", field: "image_urls" },
+ },
+ },
+ {
+ capability: { module: MINIMAX, name: "minimax-h3" }, result: "video", routes: [{ model: "minimax-h3" }],
+ constants: { watermark: false },
+ fields: {
+ prompt: { as: "value", field: "prompt" },
+ duration: { as: "value", field: "duration" },
+ resolution: { as: "value", field: "resolution" },
+ aspectRatio: { as: "value", field: "aspect_ratio" },
+ firstFrame: { as: "url", field: "first_frame_image" },
+ lastFrame: { as: "url", field: "last_frame_image" },
+ referenceImage: { as: "urlArray", field: "image_urls" },
+ referenceVideo: { as: "urlArray", field: "video_urls" },
+ referenceAudio: { as: "urlArray", field: "audio_urls" },
+ },
+ },
+ {
+ capability: { module: GPT_IMAGE, name: "gpt-image-2" }, result: "image",
+ routes: [
+ { model: "gpt-image-2/image-to-image", whenPresent: ["images"] },
+ { model: "gpt-image-2/text-to-image" },
+ ],
+ fields: {
+ prompt: { as: "value", field: "prompt" },
+ aspectRatio: { as: "value", field: "aspect_ratio" },
+ resolution: { as: "value", field: "resolution" },
+ background: { as: "value", field: "background" },
+ images: { as: "urlArray", field: "input_urls" },
+ },
+ },
+ ...([["nano-banana-2", "Nano-Banana-2"], ["nano-banana-pro", "Nano-Banana-Pro"]] as const).map(([name, model]): GenerationWireMapping => ({
+ capability: { module: NANO_BANANA, name }, result: "image", routes: [{ model }],
+ fields: {
+ prompt: { as: "value", field: "prompt" },
+ images: { as: "urlArray", field: "image_input" },
+ aspectRatio: { as: "value", field: "aspect_ratio" },
+ resolution: { as: "value", field: "resolution" },
+ outputFormat: { as: "value", field: "output_format" },
+ },
+ })),
+ {
+ capability: { module: GROK, name: "grok-imagine-video" }, result: "video",
+ routes: [
+ { model: "grok-imagine/image-to-video", whenPresent: ["images"] },
+ { model: "grok-imagine/text-to-video" },
+ ],
+ fields: {
+ prompt: { as: "value", field: "prompt" },
+ aspectRatio: { as: "value", field: "aspect_ratio" },
+ resolution: { as: "value", field: "resolution" },
+ duration: { as: "value", field: "duration" },
+ images: { as: "urlArray", field: "image_urls" },
+ },
+ },
+ {
+ capability: { module: GROK, name: "grok-imagine-video-1.5-preview" }, result: "video",
+ routes: [{ model: "grok-imagine-1.5/image-to-video" }],
+ fields: {
+ prompt: { as: "value", field: "prompt" },
+ aspectRatio: { as: "value", field: "aspect_ratio" },
+ resolution: { as: "value", field: "resolution" },
+ duration: { as: "value", field: "duration" },
+ images: { as: "urlArray", field: "image_urls" },
+ },
+ },
+];
diff --git a/packages/provider-hiapi/src/provider.ts b/packages/provider-hiapi/src/provider.ts
new file mode 100644
index 00000000..c9870473
--- /dev/null
+++ b/packages/provider-hiapi/src/provider.ts
@@ -0,0 +1,215 @@
+import { requestDeadline } from "@hypit/runtime-kit";
+import type { AsyncEndpoint, EndpointCredential, EndpointInvocationContext, EndpointOutcome } from "@hypit/endpoint-kit";
+import { defineEndpointPackage, wakeAfter } from "@hypit/endpoint-kit";
+import type { GenerationArtifactUrlResolver } from "@hypit/generation";
+import { canonicalize } from "@hypit/protocol";
+import type { BlobRef, CapabilityRef } from "@hypit/protocol";
+import { credentialRef } from "@hypit/runtime";
+import type { CredentialRef, ResourceStore } from "@hypit/runtime";
+import { hiApiRouteForCapability, hiApiRoutes } from "./routes.js";
+import type { HiApiMediaLimits } from "./routes.js";
+import { HiApiHttpError, HiApiServiceError, hiApiTaskFailure } from "./errors.js";
+
+export const hiApiProviderModuleRef = { name: "@hypit/provider-hiapi", version: "1" } as const;
+
+export type CreateHiApiProviderOptions = {
+ readonly instance?: string;
+ readonly pool?: string;
+ readonly baseUrl?: string;
+ readonly apiKey?: CredentialRef;
+ readonly defaultConcurrency?: number;
+ readonly actionLimits?: import("@hypit/endpoint-kit").EndpointActionLimits;
+ readonly pollIntervalMs?: number;
+ readonly requestTimeoutMs?: number;
+ readonly operationTimeoutMs?: number;
+ readonly fetch?: typeof globalThis.fetch;
+ /** Publish a referenced Resource at a URL the service can fetch; replaces inline data URLs. */
+ readonly publicAssetUrl?: (artifact: BlobRef, artifacts: ResourceStore, fields?: Readonly<Record<string, string | number | boolean>>) => Promise<string>;
+};
+
+type Handle = {
+ readonly contract: "hypit.hiapi-operation@1";
+ readonly taskId: string;
+ readonly route: string;
+ readonly startedAt: number;
+ readonly urls?: readonly string[];
+};
+
+function assert(condition: unknown, message: string): asserts condition { if (!condition) throw new Error(message); }
+function object(value: unknown, subject: string): Record<string, unknown> {
+ assert(value !== null && typeof value === "object" && !Array.isArray(value), `${subject} must be an object`);
+ return value as Record<string, unknown>;
+}
+function capabilityKey(capability: CapabilityRef): string { return `${capability.module.name}@${capability.module.version}#${capability.name}`; }
+function apiBaseUrl(value: string): string {
+ let trimmed = value.trim();
+ while (trimmed.endsWith("/")) trimmed = trimmed.slice(0, -1);
+ assert(trimmed.length > 0, "HiAPI base URL is empty");
+ return trimmed;
+}
+function apiKey(credentials: Readonly<Record<string, EndpointCredential>>): string {
+ const value = credentials.apiKey?.secret;
+ assert(typeof value === "string" && value.length > 0, "HiAPI apiKey credential is unavailable; store a HiAPI API key for this Endpoint");
+ return value;
+}
+function failureMessage(error: unknown): string {
+ return error instanceof Error ? error.message : String(error);
+}
+function failure(error: unknown): EndpointOutcome {
+ return { status: "failed", failure: { code: error instanceof HiApiServiceError ? error.code : "HIAPI_ERROR", message: failureMessage(error) } };
+}
+
+class HiApiClient {
+ constructor(readonly baseUrl: string, readonly timeout: number, readonly fetcher: typeof globalThis.fetch) {}
+ async json(path: string, key: string, init: RequestInit = {}): Promise<Record<string, unknown>> {
+ const deadline = requestDeadline(this.timeout);
+ try {
+ const response = await deadline.wait(this.fetcher(`${this.baseUrl}${path}`, {
+ ...init, signal: deadline.signal, headers: { authorization: `Bearer ${key}`, ...(init.headers ?? {}) },
+ }));
+ const text = await deadline.wait(response.text());
+ if (!response.ok) {
+ const input = typeof init.body === "string" ? JSON.parse(init.body) as Record<string, unknown> : undefined;
+ throw new HiApiHttpError(response.status, response, text, {
+ method: init.method ?? "GET", path, ...(typeof input?.model === "string" ? { model: input.model } : {}),
+ });
+ }
+ let body: unknown;
+ try { body = text.length === 0 ? {} : JSON.parse(text); } catch { throw new Error(`HiAPI returned invalid JSON (${response.status})`); }
+ return object(object(body, "HiAPI response").data, "HiAPI response data");
+ } finally { deadline.finish(); }
+ }
+ async download(url: string): Promise<{ readonly bytes: Uint8Array; readonly mediaType: string }> {
+ const deadline = requestDeadline(this.timeout);
+ try {
+ const response = await deadline.wait(this.fetcher(url, { signal: deadline.signal }));
+ if (!response.ok) throw new Error(`HiAPI asset returned HTTP ${response.status}`);
+ return { bytes: new Uint8Array(await deadline.wait(response.arrayBuffer())), mediaType: response.headers.get("content-type")?.split(";", 1)[0] ?? "application/octet-stream" };
+ } finally { deadline.finish(); }
+ }
+}
+
+function resolverFor(limits: HiApiMediaLimits, context: EndpointInvocationContext, publicAssetUrl: CreateHiApiProviderOptions["publicAssetUrl"]): GenerationArtifactUrlResolver {
+ const resolved = new Map<string, Promise<string>>();
+ let imageBytes = 0;
+ return (artifact, fields) => {
+ const existing = resolved.get(artifact.resource);
+ if (existing !== undefined) return existing;
+ const promise = (async () => {
+ if (publicAssetUrl !== undefined) return await publicAssetUrl(artifact, context.resources, fields);
+ // HiAPI documents data URLs for image and audio inputs; reference videos must be public HTTPS URLs.
+ const kind = artifact.mediaType.split("/", 1)[0];
+ assert(kind === "image" || kind === "audio",
+ `HiAPI accepts ${artifact.mediaType} references only by public URL; configure publicAssetUrl for this Endpoint`);
+ const limit = limits[kind];
+ assert(limit === undefined || artifact.size <= limit,
+ `HiAPI accepts ${kind} references up to ${(limit ?? 0) / 1_000_000} MB for this model; ${artifact.resource} is ${artifact.size} bytes`);
+ if (kind === "image") {
+ imageBytes += artifact.size;
+ assert(limits.imagesTotal === undefined || imageBytes <= limits.imagesTotal,
+ `HiAPI accepts reference images up to ${(limits.imagesTotal ?? 0) / 1_000_000} MB combined for this model`);
+ }
+ const bytes = await context.resources.get(artifact.resource);
+ assert(bytes !== undefined && bytes.byteLength === artifact.size, `Reference Resource ${artifact.resource} is unavailable or has changed`);
+ return `data:${artifact.mediaType};base64,${Buffer.from(bytes).toString("base64")}`;
+ })();
+ resolved.set(artifact.resource, promise);
+ return promise;
+ };
+}
+
+function endpoint(client: HiApiClient, pollIntervalMs: number, maxOperationMs: number, publicAssetUrl: CreateHiApiProviderOptions["publicAssetUrl"]): AsyncEndpoint {
+ return {
+ async start(context) {
+ try {
+ const route = hiApiRouteForCapability(context.need.capability);
+ assert(route !== undefined, "HiAPI does not implement this exact capability");
+ const request = route.prepare(context.need.constraints);
+ await context.reportProgress?.({ phase: `Preparing HiAPI request: ${request.model}` });
+ let body: Record<string, unknown>;
+ try {
+ body = await request.compile(resolverFor(request.mediaLimits, context, publicAssetUrl));
+ } catch (error) {
+ throw new HiApiServiceError(error instanceof HiApiServiceError ? error.code : "HIAPI_ERROR",
+ `HiAPI request preparation failed; model=${request.model}; generation not submitted: ${failureMessage(error)}`);
+ }
+ await context.reportProgress?.({ phase: `Submitting HiAPI request: ${request.model}` });
+ const response = await client.json("/v1/tasks", apiKey(context.credentials), {
+ method: "POST", headers: { "content-type": "application/json", "idempotency-key": context.operation }, body: JSON.stringify(body),
+ });
+ assert(typeof response.taskId === "string" && response.taskId.length > 0, "HiAPI response has no taskId");
+ const handle: Handle = { contract: "hypit.hiapi-operation@1", taskId: response.taskId, route: route.key, startedAt: Date.now() };
+ const receipt = { id: handle.taskId };
+ await context.checkpoint?.({ handle: canonicalize(handle), receipt });
+ return { ...wakeAfter(canonicalize(handle), pollIntervalMs, Date.now(), { phase: "submitted" }), receipt };
+ } catch (error) {
+ return failure(error);
+ }
+ },
+ async poll(context) {
+ try {
+ const handle = object(context.handle, "HiAPI handle") as unknown as Handle;
+ const route = hiApiRouteForCapability(context.need.capability);
+ assert(route !== undefined && handle.contract === "hypit.hiapi-operation@1" && handle.route === route.key, "HiAPI handle is invalid");
+ const receipt = { id: handle.taskId };
+ if (Date.now() - handle.startedAt > maxOperationMs) {
+ return { status: "failed", receipt, failure: { code: "HIAPI_OPERATION_TIMEOUT", message: `HiAPI task ${handle.taskId} exceeded this Provider's operationTimeoutMs (${maxOperationMs}); remote outcome is unknown` } };
+ }
+ const task = await client.json(`/v1/tasks/${encodeURIComponent(handle.taskId)}`, apiKey(context.credentials));
+ const status = String(task.status);
+ if (status === "queued" || status === "handling" || status === "archiving") {
+ return { ...wakeAfter(canonicalize(handle), pollIntervalMs, Date.now(), { phase: status }), receipt };
+ }
+ const rejected = hiApiTaskFailure(task, handle.taskId);
+ if (rejected !== undefined) return { ...failure(rejected), receipt };
+ assert(status === "success", `HiAPI returned unknown task status ${status}`);
+ assert(Array.isArray(task.output) && task.output.length > 0, "HiAPI task succeeded without output");
+ const urls = task.output.map((item, index) => {
+ const url = object(item, `HiAPI output ${index + 1}`).url;
+ assert(typeof url === "string" && /^https?:\/\//u.test(url), `HiAPI output ${index + 1} has no URL`);
+ return url;
+ });
+ return { status: "ready", handle: canonicalize({ ...handle, urls }), receipt };
+ } catch (error) {
+ return failure(error);
+ }
+ },
+ async collect(context) {
+ try {
+ const handle = object(context.handle, "HiAPI handle") as unknown as Handle;
+ const route = hiApiRouteForCapability(context.need.capability);
+ assert(route !== undefined && handle.route === route.key && Array.isArray(handle.urls), "HiAPI collection route differs");
+ await context.reportProgress?.({ phase: "Receiving generated files" });
+ const blobs: BlobRef[] = [];
+ for (const url of handle.urls) {
+ const downloaded = await client.download(url);
+ blobs.push(await context.resources.put(downloaded.bytes, downloaded.mediaType));
+ }
+ return { status: "completed", result: { value: route.packageResult(blobs) }, receipt: { id: handle.taskId } };
+ } catch (error) {
+ return failure(error);
+ }
+ },
+ };
+}
+
+export function createHiApiProvider(options: CreateHiApiProviderOptions = {}) {
+ const requestTimeoutMs = options.requestTimeoutMs ?? 300_000;
+ const operationTimeoutMs = options.operationTimeoutMs ?? 30 * 60_000;
+ for (const [name, value] of Object.entries({ requestTimeoutMs, operationTimeoutMs })) {
+ assert(Number.isSafeInteger(value) && value > 0, `HiAPI ${name} must be a positive integer`);
+ }
+ const client = new HiApiClient(apiBaseUrl(options.baseUrl ?? "https://api.hiapi.ai"), requestTimeoutMs, options.fetch ?? globalThis.fetch);
+ const asyncEndpoint = endpoint(client, options.pollIntervalMs ?? 10_000, operationTimeoutMs, options.publicAssetUrl);
+ return defineEndpointPackage({
+ module: hiApiProviderModuleRef, facet: "gateway", instance: options.instance ?? "hiapi.default", pool: options.pool ?? options.instance ?? "hiapi.default",
+ pricing: { kind: "page", url: "https://www.hiapi.ai/en/pricing" },
+ credentials: { apiKey: options.apiKey ?? credentialRef("os", "hiapi.api-key") },
+ credentialInputs: { apiKey: { label: "HiAPI API key" } },
+ defaultConcurrency: options.defaultConcurrency ?? 4,
+ ...(options.actionLimits === undefined ? {} : { actionLimits: options.actionLimits }),
+ capabilities: hiApiRoutes.map((route) => ({
+ capability: route.capability, returns: route.returns, lifecycle: "asynchronous" as const, endpoint: asyncEndpoint, capacity: route.capability.name, supports: route.supports,
+ })),
+ });
+}
diff --git a/packages/provider-hiapi/src/routes.ts b/packages/provider-hiapi/src/routes.ts
new file mode 100644
index 00000000..ae65b4e7
--- /dev/null
+++ b/packages/provider-hiapi/src/routes.ts
@@ -0,0 +1,154 @@
+import {
+ compileWireRequest,
+ selectWireModelForRequest,
+ generationTypes,
+ sealGeneratedImageSet,
+ sealGeneratedVideoSet,
+} from "@hypit/generation";
+import type { GenerationArtifactUrlResolver, GenerationRequest, GenerationWireMapping } 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 { hiApiMappings } from "./mapping.js";
+
+/** Documented byte limits for inline media on one HiAPI model; an absent kind carries no documented cap. */
+export type HiApiMediaLimits = {
+ readonly image?: number;
+ readonly audio?: number;
+ /** Documented cap on the combined size of all reference images. */
+ readonly imagesTotal?: number;
+};
+
+const MB = 1_000_000;
+
+/** Per-file sizes HiAPI's model pages state for images and audio; videos travel by public URL. */
+const hiApiMediaLimits: Readonly<Record<string, HiApiMediaLimits>> = {
+ "seedance-2.0-mini": { image: 30 * MB, audio: 15 * MB },
+ "seedance-2.5/image-to-video": { image: 30 * MB, audio: 15 * MB, imagesTotal: 120 * MB },
+ "seedance-2.5/reference-to-video": { image: 30 * MB, audio: 15 * MB, imagesTotal: 120 * MB },
+ "seedream-5.0-lite/image-to-image": { image: 10 * MB },
+ "Nano-Banana-Pro": { image: 30 * MB },
+ "grok-imagine/image-to-video": { image: 10 * MB },
+ "grok-imagine-1.5/image-to-video": { image: 20 * MB },
+};
+
+export type HiApiPreparedRequest = {
+ readonly model: string;
+ readonly mediaLimits: HiApiMediaLimits;
+ readonly compile: (resolve: GenerationArtifactUrlResolver) => Promise<Record<string, unknown>>;
+};
+
+export type HiApiRoute = GenerationWireMapping & {
+ readonly key: string;
+ readonly returns: TypeRef;
+ readonly supports: (request: EndpointRequest) => EndpointSupport;
+ readonly prepare: (constraints: CanonicalValue) => HiApiPreparedRequest;
+ readonly packageResult: (artifacts: readonly BlobRef[]) => StoredValue;
+};
+
+function scalar(request: GenerationRequest, port: string): string | number | boolean | undefined {
+ const value = request.ports[port]?.[0];
+ return typeof value === "string" || typeof value === "number" || typeof value === "boolean" ? value : undefined;
+}
+function count(request: GenerationRequest, port: string): number {
+ return request.ports[port]?.length ?? 0;
+}
+
+const SEEDREAM_RESOLUTION: Readonly<Record<string, string>> = { basic: "2K", ultra: "4K" };
+const GPT_IMAGE_UNAVAILABLE: Readonly<Record<string, readonly string[]>> = {
+ "2K": ["5:4", "4:5", "3:1", "1:3", "9:21"],
+ "4K": ["1:1", "3:1", "1:3", "9:21"],
+};
+
+/** HiAPI's documented input ranges for each mapped model, checked before any reference is resolved. */
+function rejection(mapping: GenerationWireMapping, request: GenerationRequest): string | undefined {
+ const { name } = mapping.capability;
+ const ratio = scalar(request, "aspectRatio");
+ const resolution = scalar(request, "resolution");
+ let model: string;
+ try { model = selectWireModelForRequest(mapping, request); } catch (error) { return error instanceof Error ? error.message : String(error); }
+ if (name === "seedance-2-mini" && scalar(request, "webSearch") === true) {
+ return "HiAPI seedance-2.0-mini has no web_search field";
+ }
+ if (name === "seedance-2.5") {
+ if (model === "seedance-2.5/image-to-video" && ratio !== "adaptive") {
+ return `HiAPI ${model} takes only aspect-ratio adaptive, not ${String(ratio)}`;
+ }
+ if (model !== "seedance-2.5/reference-to-video" && resolution === "480p") {
+ return `HiAPI ${model} renders 720p or 1080p, not 480p`;
+ }
+ }
+ if (name === "seedream-5-lite" && SEEDREAM_RESOLUTION[String(scalar(request, "quality"))] === undefined) {
+ return `HiAPI Seedream 5.0 lite renders 2K (basic) or 4K (ultra), not quality ${String(scalar(request, "quality"))}`;
+ }
+ if (name === "minimax-h3") {
+ if (resolution !== undefined && resolution !== "2K") return `HiAPI minimax-h3 renders 2K only, not ${String(resolution)}`;
+ if (count(request, "referenceImage") > 5) return "HiAPI minimax-h3 accepts up to five reference images";
+ }
+ if (name === "gpt-image-2") {
+ if (count(request, "images") > 6) return "HiAPI gpt-image-2/image-to-image accepts up to six reference images";
+ if (scalar(request, "background") !== undefined && resolution !== "1K") return `HiAPI GPT Image 2 accepts background only at 1K; omit it at ${String(resolution)}`;
+ if (ratio === "auto" && resolution !== "1K") return "HiAPI GPT Image 2 renders aspect-ratio auto only at 1K";
+ if (GPT_IMAGE_UNAVAILABLE[String(resolution)]?.includes(String(ratio))) return `HiAPI GPT Image 2 does not render ${String(ratio)} at ${String(resolution)}`;
+ }
+ if (mapping.capability.module.name === "@hypit/grok-imagine") {
+ if (resolution === "1080p") return `HiAPI ${model} renders 480p or 720p, not 1080p`;
+ if (name === "grok-imagine-video-1.5-preview" && count(request, "images") !== 1) {
+ return "HiAPI grok-imagine-1.5/image-to-video animates exactly one image";
+ }
+ }
+ return undefined;
+}
+
+/** Fields the model package requires that HiAPI names differently or does not take. */
+function normalize(mapping: GenerationWireMapping, input: Record<string, unknown>): Record<string, unknown> {
+ const { name } = mapping.capability;
+ if (name === "seedance-2-mini" && input.web_search === false) delete input.web_search;
+ if (name === "seedream-5-lite") {
+ input.resolution = SEEDREAM_RESOLUTION[String(input.quality)];
+ delete input.quality;
+ delete input.output_format;
+ delete input.nsfw_check;
+ }
+ return input;
+}
+
+function capabilityKey(capability: CapabilityRef): string {
+ return `${capability.module.name}@${capability.module.version}#${capability.name}`;
+}
+
+export const hiApiRoutes: readonly HiApiRoute[] = hiApiMappings.map((mapping) => ({
+ ...mapping,
+ key: capabilityKey(mapping.capability),
+ returns: mapping.result === "image" ? generationTypes.imageSet : generationTypes.videoSet,
+ supports: (request) => {
+ const reason = rejection(mapping, request.constraints as unknown as GenerationRequest);
+ return reason === undefined ? { status: "supported" } : { status: "unsupported", reason };
+ },
+ prepare: (constraints) => {
+ const request = constraints as unknown as GenerationRequest;
+ const reason = rejection(mapping, request);
+ if (reason !== undefined) throw new Error(reason);
+ const model = selectWireModelForRequest(mapping, request);
+ return {
+ model,
+ mediaLimits: hiApiMediaLimits[model] ?? {},
+ compile: async (resolve) => ({
+ model,
+ input: normalize(mapping, (await compileWireRequest(mapping, request, resolve)).input as Record<string, unknown>),
+ }),
+ };
+ },
+ packageResult: (artifacts) => ({
+ kind: "inline",
+ value: canonicalize(mapping.result === "image"
+ ? sealGeneratedImageSet({ images: artifacts })
+ : sealGeneratedVideoSet({ videos: artifacts })),
+ }),
+}));
+
+const byCapability = new Map(hiApiRoutes.map((route) => [route.key, route]));
+
+export function hiApiRouteForCapability(capability: CapabilityRef): HiApiRoute | undefined {
+ return byCapability.get(capabilityKey(capability));
+}
diff --git a/packages/provider-hiapi/test/routes.test.ts b/packages/provider-hiapi/test/routes.test.ts
new file mode 100644
index 00000000..e7b89c71
--- /dev/null
+++ b/packages/provider-hiapi/test/routes.test.ts
@@ -0,0 +1,68 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { assertMappingCoversPorts } from "@hypit/generation";
+import type { BlobRef, CanonicalValue } from "@hypit/protocol";
+import { gptImage2Ports, sealGptImage2Request } from "@hypit/gpt-image";
+import { grokImaginePorts } from "@hypit/grok-imagine";
+import { minimaxH3Ports } from "@hypit/minimax-h3";
+import { nanoBananaPorts } from "@hypit/nano-banana";
+import { seedancePorts, sealSeedanceRequest } from "@hypit/seedance";
+import { seedream5LitePorts, sealSeedreamRequest } from "@hypit/seedream";
+
+import { hiApiMappings } from "../src/mapping.js";
+import { hiApiRouteForCapability } from "../src/routes.js";
+
+const image: BlobRef = { kind: "blob", resource: "res_hiapi_1", size: 3, mediaType: "image/png" };
+const video: BlobRef = { kind: "blob", resource: "res_hiapi_2", size: 3, mediaType: "video/mp4" };
+const resolve = async () => "https://example.test/reference";
+const route = (module: string, name: string) => hiApiRouteForCapability({ module: { name: module, version: "1" }, name })!;
+const constraints = (request: unknown) => request as CanonicalValue;
+
+test("every HiAPI mapping covers its model's ports", () => {
+ const tables = {
+ ...seedancePorts, ...grokImaginePorts, ...nanoBananaPorts,
+ "seedream-5-lite": seedream5LitePorts, "minimax-h3": minimaxH3Ports, "gpt-image-2": gptImage2Ports,
+ };
+ for (const mapping of hiApiMappings) {
+ assertMappingCoversPorts(tables[mapping.capability.name as keyof typeof tables], mapping);
+ }
+});
+
+test("Seedance 2.5 selects the HiAPI model from the request shape", async () => {
+ const seedance = route("@hypit/seedance", "seedance-2.5");
+ const base = { prompt: ["go"], resolution: ["720p"], duration: [5], generateAudio: [true], webSearch: [false] };
+ const text = seedance.prepare(constraints(sealSeedanceRequest("seedance-2.5", { ...base, aspectRatio: ["16:9"] })));
+ assert.equal(text.model, "seedance-2.5/text-to-video");
+ const frames = seedance.prepare(constraints(sealSeedanceRequest("seedance-2.5", {
+ ...base, aspectRatio: ["adaptive"], firstFrame: [{ role: "image", artifact: image, fields: { personReference: true } }],
+ })));
+ assert.equal(frames.model, "seedance-2.5/image-to-video");
+ assert.deepEqual(await frames.compile(resolve), {
+ model: "seedance-2.5/image-to-video",
+ input: { prompt: "go", resolution: "720p", duration: 5, generate_audio: true, web_search: false, aspect_ratio: "adaptive", first_frame_url: "https://example.test/reference" },
+ });
+ const references = sealSeedanceRequest("seedance-2.5", {
+ ...base, aspectRatio: ["16:9"], referenceVideo: [{ role: "video", artifact: video }],
+ });
+ assert.equal(seedance.prepare(constraints(references)).model, "seedance-2.5/reference-to-video");
+ const framed = seedance.supports({ capability: seedance.capability, returns: seedance.returns,
+ constraints: constraints(sealSeedanceRequest("seedance-2.5", { ...base, aspectRatio: ["16:9"], firstFrame: [{ role: "image", artifact: image }] })) });
+ assert.equal(framed.status, "unsupported");
+});
+
+test("Seedream quality becomes the HiAPI resolution tier and 3K is unsupported", async () => {
+ const seedream = route("@hypit/seedream", "seedream-5-lite");
+ const request = sealSeedreamRequest({ prompt: ["a cup"], aspectRatio: ["9:16"], quality: ["ultra"], outputFormat: ["png"], nsfwCheck: [true], images: [{ role: "image", artifact: image }] });
+ assert.deepEqual(await seedream.prepare(constraints(request)).compile(resolve), {
+ model: "seedream-5.0-lite/image-to-image",
+ input: { prompt: "a cup", aspect_ratio: "9:16", resolution: "4K", image_urls: ["https://example.test/reference"] },
+ });
+ const high = sealSeedreamRequest({ ...request.ports, quality: ["high"] });
+ assert.equal(seedream.supports({ capability: seedream.capability, returns: seedream.returns, constraints: constraints(high) }).status, "unsupported");
+});
+
+test("GPT Image 2 background outside 1K is unsupported before references resolve", () => {
+ const gpt = route("@hypit/gpt-image", "gpt-image-2");
+ const request = sealGptImage2Request({ prompt: ["cut"], aspectRatio: ["1:1"], resolution: ["2K"], background: ["opaque"] });
+ assert.equal(gpt.supports({ capability: gpt.capability, returns: gpt.returns, constraints: constraints(request) }).status, "unsupported");
+});
diff --git a/packages/provider-monid/README.md b/packages/provider-monid/README.md
new file mode 100644
index 00000000..e64f06b1
--- /dev/null
+++ b/packages/provider-monid/README.md
@@ -0,0 +1,60 @@
+# `@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.
+
+| Capability | Monid endpoint |
+| --- | --- |
+| `@hypit/seedance@1#seedance-2` | `bytedance` `/v1/video/seedance-2.0` |
+| `@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` |
+
+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.
+
+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
+workspace until removed with `/rm`. Embedded callers may replace this transport with
+`publicAssetUrl`.
+
+A run ends with Monid's own status (`COMPLETED`, `FAILED`, `BLOCKED`, `STOPPED`, `TIMED_OUT`) and,
+when completed, the provider's HTTP status in `providerResponse`. A completed run whose provider
+answered 4xx or 5xx fails with that status and the provider's error message; a `BLOCKED` run keeps
+Monid's `reason`. Signed URLs in messages are redacted.
+
+Runtime Profile example:
+
+```json
+{
+ "endpoints": {
+ "monid.default": {
+ "use": "@hypit/provider-monid",
+ "pool": "monid.default",
+ "config": {
+ "apiKey": { "store": "platform", "key": "monid.api-key" },
+ "defaultConcurrency": 3,
+ "pollIntervalMs": 10000
+ }
+ }
+ }
+}
+```
+
+`baseUrl` defaults to `https://api.monid.ai`. Store the API key with
+`hypit auth login monid.default --runtime hypit.runtime.json`. Optional `requestTimeoutMs`,
+`operationTimeoutMs` and `actionLimits` bound single HTTP calls, the whole remote run and action
+concurrency; file-system runs poll at most every five seconds within `requestTimeoutMs`.
diff --git a/packages/provider-monid/package.json b/packages/provider-monid/package.json
new file mode 100644
index 00000000..ab3f15f3
--- /dev/null
+++ b/packages/provider-monid/package.json
@@ -0,0 +1,19 @@
+{
+ "name": "@hypit/provider-monid",
+ "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/endpoint-kit": "workspace:*",
+ "@hypit/generation": "workspace:*",
+ "@hypit/protocol": "workspace:*",
+ "@hypit/runtime": "workspace:*",
+ "@hypit/runtime-kit": "workspace:*"
+ },
+ "devDependencies": {
+ "@hypit/seedance": "workspace:*"
+ }
+}
diff --git a/packages/provider-monid/src/activation.ts b/packages/provider-monid/src/activation.ts
new file mode 100644
index 00000000..185133a6
--- /dev/null
+++ b/packages/provider-monid/src/activation.ts
@@ -0,0 +1,62 @@
+import {
+ createRuntimeEndpointAdapterFacet,
+ runtimeConfigCredentialRef,
+ runtimeConfigActionLimits,
+ runtimeConfigExact,
+ runtimeConfigObject,
+ runtimeConfigPositiveInteger,
+ runtimeConfigString,
+} from "@hypit/runtime-kit";
+
+import { createMonidProvider } from "./provider.js";
+
+const adapter = createRuntimeEndpointAdapterFacet({
+ use: "@hypit/provider-monid",
+ activate(context) {
+ if (context.pool === undefined) throw new Error("Monid Provider Pool is required");
+ const config = runtimeConfigObject(context.config, "Monid");
+ runtimeConfigExact(config, [
+ "baseUrl",
+ "apiKey",
+ "defaultConcurrency",
+ "actionLimits",
+ "pollIntervalMs",
+ "requestTimeoutMs",
+ "operationTimeoutMs",
+ ], "Monid");
+ const baseUrl = runtimeConfigString(config.baseUrl, "Monid baseUrl");
+ if (baseUrl !== undefined) {
+ const url = new URL(baseUrl);
+ if (url.protocol !== "https:" && url.hostname !== "localhost" && url.hostname !== "127.0.0.1") {
+ throw new Error("Monid baseUrl must use HTTPS or loopback");
+ }
+ }
+ const apiKey = runtimeConfigCredentialRef(config.apiKey, "Monid apiKey");
+ if (apiKey === undefined) throw new Error("Monid apiKey CredentialRef is required");
+ const actionLimits = runtimeConfigActionLimits(config.actionLimits);
+ const defaultConcurrency = runtimeConfigPositiveInteger(config.defaultConcurrency, "Monid defaultConcurrency");
+ const pollIntervalMs = runtimeConfigPositiveInteger(config.pollIntervalMs, "Monid pollIntervalMs");
+ const requestTimeoutMs = runtimeConfigPositiveInteger(config.requestTimeoutMs, "Monid requestTimeoutMs");
+ const operationTimeoutMs = runtimeConfigPositiveInteger(config.operationTimeoutMs, "Monid operationTimeoutMs");
+ return {
+ endpoint: createMonidProvider({
+ instance: context.instance,
+ pool: context.pool,
+ ...(baseUrl === undefined ? {} : { baseUrl }),
+ apiKey,
+ ...(defaultConcurrency === undefined ? {} : { defaultConcurrency }),
+ ...(actionLimits === undefined ? {} : { actionLimits }),
+ ...(pollIntervalMs === undefined ? {} : { pollIntervalMs }),
+ ...(requestTimeoutMs === undefined ? {} : { requestTimeoutMs }),
+ ...(operationTimeoutMs === undefined ? {} : { operationTimeoutMs }),
+ }),
+ };
+ },
+});
+
+export const hypitPackage = {
+ format: "hypit.node-package@1" as const,
+ hostFacets: [adapter],
+};
+
+export default hypitPackage;
diff --git a/packages/provider-monid/src/errors.ts b/packages/provider-monid/src/errors.ts
new file mode 100644
index 00000000..c15bd039
--- /dev/null
+++ b/packages/provider-monid/src/errors.ts
@@ -0,0 +1,55 @@
+/** Monid's `{ code, message }` error envelope and run outcome fields, kept at the service boundary. */
+function record(value: unknown): Record<string, unknown> | undefined {
+ return value !== null && typeof value === "object" && !Array.isArray(value)
+ ? value as Record<string, unknown> : undefined;
+}
+function text(value: unknown): string | undefined {
+ return typeof value === "string" && value.trim().length > 0 ? value.trim() : undefined;
+}
+
+// Responses may mention a signed asset URL. Keep the reason, not its access capability.
+export function safeMonidReason(value: string): string {
+ return value.replace(/https?:\/\/\S+/giu, "[redacted-url]");
+}
+
+export class MonidServiceError extends Error {
+ constructor(readonly code: string, message: string) { super(message); }
+}
+
+export class MonidHttpError extends MonidServiceError {
+ constructor(readonly status: number, response: { readonly headers: Headers }, bodyText: string,
+ request: { readonly method: string; readonly path: string }) {
+ let body: Record<string, unknown> | undefined;
+ try { body = record(JSON.parse(bodyText)); } catch { /* Non-JSON gateway failures still have HTTP evidence. */ }
+ const reason = text(body?.message) ?? (body === undefined ? text(bodyText.slice(0, 2000)) : undefined);
+ const requestId = text(response.headers.get("x-request-id"));
+ const facts = [
+ `Monid HTTP ${status}`, `${request.method} ${request.path}`,
+ ...(requestId === undefined ? [] : [`request=${requestId}`]),
+ ];
+ super("MONID_HTTP_ERROR", `${facts.join("; ")}${reason === undefined ? "" : `: ${safeMonidReason(reason)}`}`);
+ }
+}
+
+export const monidTerminalStatuses = ["COMPLETED", "FAILED", "BLOCKED", "STOPPED", "TIMED_OUT"] as const;
+
+/**
+ * A run that ended without provider output: a non-COMPLETED terminal status, or COMPLETED with a
+ * provider HTTP error. `undefined` while the run is pending or when the provider answered 2xx.
+ */
+export function monidRunFailure(run: Record<string, unknown>, id: string): MonidServiceError | undefined {
+ const status = String(run.status);
+ if (status !== "COMPLETED") {
+ if (!monidTerminalStatuses.includes(status as typeof monidTerminalStatuses[number])) return undefined;
+ const reason = text(run.reason);
+ return new MonidServiceError(`MONID_RUN_${status}`,
+ `Monid run ${id} ${status}${reason === undefined ? "" : `: ${safeMonidReason(reason)}`}`);
+ }
+ const provider = record(run.providerResponse);
+ const httpStatus = typeof provider?.httpStatus === "number" ? provider.httpStatus : 200;
+ if (httpStatus < 400) return undefined;
+ const error = record(provider?.error);
+ const detail = text(error?.message) ?? text(record(error?.error)?.message) ?? text(provider?.error);
+ return new MonidServiceError("MONID_PROVIDER_ERROR",
+ `Monid run ${id} completed with provider HTTP ${httpStatus}${detail === undefined ? "" : `: ${safeMonidReason(detail)}`}`);
+}
diff --git a/packages/provider-monid/src/index.ts b/packages/provider-monid/src/index.ts
new file mode 100644
index 00000000..abcda2ca
--- /dev/null
+++ b/packages/provider-monid/src/index.ts
@@ -0,0 +1,2 @@
+export { createMonidProvider, monidProviderModuleRef } from "./provider.js";
+export type { CreateMonidProviderOptions } from "./provider.js";
diff --git a/packages/provider-monid/src/mapping.ts b/packages/provider-monid/src/mapping.ts
new file mode 100644
index 00000000..56562b44
--- /dev/null
+++ b/packages/provider-monid/src/mapping.ts
@@ -0,0 +1,33 @@
+import type { ModuleRef } from "@hypit/protocol";
+import type { GenerationWireMapping } from "@hypit/generation";
+
+const SEEDANCE: ModuleRef = { name: "@hypit/seedance", version: "1" };
+
+/**
+ * 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 => ({
+ capability: { module: SEEDANCE, name }, result: "video", routes: [{ model: endpoint }],
+ fields: {
+ prompt: { as: "value", field: "text" },
+ referenceImage: { as: "urlArray", field: "reference_image", resourceFields: ["personReference"] },
+ referenceVideo: { as: "urlArray", field: "reference_video", resourceFields: ["personReference"] },
+ referenceAudio: { as: "urlArray", field: "reference_audio" },
+ firstFrame: { as: "url", field: "first_frame", resourceFields: ["personReference"] },
+ lastFrame: { as: "url", field: "last_frame", resourceFields: ["personReference"] },
+ resolution: { as: "value", field: "resolution" },
+ aspectRatio: { as: "value", field: "ratio" },
+ duration: { as: "value", field: "duration" },
+ generateAudio: { as: "value", field: "generate_audio" },
+ webSearch: { as: "value", field: "web_search" },
+ },
+});
+
+export const monidMappings: readonly GenerationWireMapping[] = [
+ 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"),
+];
diff --git a/packages/provider-monid/src/provider.ts b/packages/provider-monid/src/provider.ts
new file mode 100644
index 00000000..8cd695f5
--- /dev/null
+++ b/packages/provider-monid/src/provider.ts
@@ -0,0 +1,242 @@
+import { requestDeadline } from "@hypit/runtime-kit";
+import type { AsyncEndpoint, EndpointCredential, EndpointInvocationContext, EndpointOutcome } from "@hypit/endpoint-kit";
+import { defineEndpointPackage, wakeAfter } from "@hypit/endpoint-kit";
+import type { GenerationArtifactUrlResolver } from "@hypit/generation";
+import { canonicalize } from "@hypit/protocol";
+import type { BlobRef, CapabilityRef } from "@hypit/protocol";
+import { credentialRef } from "@hypit/runtime";
+import type { CredentialRef, ResourceStore } from "@hypit/runtime";
+import { monidRouteForCapability, monidRoutes } from "./routes.js";
+import { MonidHttpError, MonidServiceError, monidRunFailure, monidTerminalStatuses } from "./errors.js";
+
+export const monidProviderModuleRef = { name: "@hypit/provider-monid", version: "1" } as const;
+
+export type CreateMonidProviderOptions = {
+ readonly instance?: string;
+ readonly pool?: string;
+ readonly baseUrl?: string;
+ readonly apiKey?: CredentialRef;
+ readonly defaultConcurrency?: number;
+ readonly actionLimits?: import("@hypit/endpoint-kit").EndpointActionLimits;
+ readonly pollIntervalMs?: number;
+ readonly requestTimeoutMs?: number;
+ readonly operationTimeoutMs?: number;
+ readonly fetch?: typeof globalThis.fetch;
+ /** Publish a referenced Resource at a URL the service can fetch; replaces the workspace file system upload. */
+ readonly publicAssetUrl?: (artifact: BlobRef, artifacts: ResourceStore, fields?: Readonly<Record<string, string | number | boolean>>) => Promise<string>;
+};
+
+type Handle = {
+ readonly contract: "hypit.monid-operation@1";
+ readonly runId: string;
+ readonly route: string;
+ readonly startedAt: number;
+ readonly url?: string;
+};
+
+function assert(condition: unknown, message: string): asserts condition { if (!condition) throw new Error(message); }
+function object(value: unknown, subject: string): Record<string, unknown> {
+ assert(value !== null && typeof value === "object" && !Array.isArray(value), `${subject} must be an object`);
+ return value as Record<string, unknown>;
+}
+function capabilityKey(capability: CapabilityRef): string { return `${capability.module.name}@${capability.module.version}#${capability.name}`; }
+function apiBaseUrl(value: string): string {
+ let trimmed = value.trim();
+ while (trimmed.endsWith("/")) trimmed = trimmed.slice(0, -1);
+ assert(trimmed.length > 0, "Monid base URL is empty");
+ return trimmed;
+}
+function apiKey(credentials: Readonly<Record<string, EndpointCredential>>): string {
+ const value = credentials.apiKey?.secret;
+ assert(typeof value === "string" && value.length > 0, "Monid apiKey credential is unavailable; store a Monid API key for this Endpoint");
+ return value;
+}
+function failureMessage(error: unknown): string {
+ return error instanceof Error ? error.message : String(error);
+}
+function failure(error: unknown): EndpointOutcome {
+ return { status: "failed", failure: { code: error instanceof MonidServiceError ? error.code : "MONID_ERROR", message: failureMessage(error) } };
+}
+function runId(run: Record<string, unknown>): string {
+ assert(typeof run.runId === "string" && run.runId.length > 0, "Monid response has no runId");
+ return run.runId;
+}
+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. */
+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 extensions: Readonly<Record<string, string>> = {
+ "image/jpeg": "jpg", "image/png": "png", "image/webp": "webp", "video/mp4": "mp4", "video/quicktime": "mov",
+ "audio/wav": "wav", "audio/x-wav": "wav", "audio/mpeg": "mp3",
+};
+
+class MonidClient {
+ constructor(readonly baseUrl: string, readonly timeout: number, readonly pollIntervalMs: number, readonly fetcher: typeof globalThis.fetch) {}
+ async json(path: string, key: string, init: RequestInit = {}): Promise<{ readonly status: number; readonly body: Record<string, unknown> }> {
+ const deadline = requestDeadline(this.timeout);
+ try {
+ const response = await deadline.wait(this.fetcher(`${this.baseUrl}${path}`, {
+ ...init, signal: deadline.signal, headers: { authorization: `Bearer ${key}`, ...(init.headers ?? {}) },
+ }));
+ const text = await deadline.wait(response.text());
+ let body: unknown;
+ try { body = text.length === 0 ? {} : JSON.parse(text); } catch { body = undefined; }
+ // A synchronous run mirrors the provider's HTTP status while still returning the run itself.
+ const run = body !== null && typeof body === "object" && !Array.isArray(body) && typeof (body as Record<string, unknown>).runId === "string";
+ if (!response.ok && !run) throw new MonidHttpError(response.status, response, text, { method: init.method ?? "GET", path });
+ assert(body !== undefined, `Monid returned invalid JSON (${response.status})`);
+ return { status: response.status, body: object(body, "Monid response") };
+ } finally { deadline.finish(); }
+ }
+ async run(request: { readonly provider: string; readonly endpoint: string; readonly input: Record<string, unknown> }, key: string) {
+ return await this.json("/v1/run", key, { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify(request) });
+ }
+ async getRun(id: string, key: string): Promise<Record<string, unknown>> {
+ return (await this.json(`/v1/runs/${encodeURIComponent(id)}`, key)).body;
+ }
+ /** Run a short workspace operation to completion and return its provider output. */
+ async completeRun(request: { readonly provider: string; readonly endpoint: string; readonly input: Record<string, unknown> }, key: string): Promise<Record<string, unknown>> {
+ let run = (await this.run(request, key)).body;
+ const id = runId(run);
+ const deadline = requestDeadline(this.timeout);
+ try {
+ while (!monidTerminalStatuses.includes(String(run.status) as typeof monidTerminalStatuses[number])) {
+ await deadline.wait(new Promise((resolve) => setTimeout(resolve, this.pollIntervalMs)));
+ run = await this.getRun(id, key);
+ }
+ } finally { deadline.finish(); }
+ const rejected = monidRunFailure(run, id);
+ if (rejected !== undefined) throw rejected;
+ return object(run.output, `Monid ${request.provider}${request.endpoint} output`);
+ }
+ /** Upload through the workspace file system (`sfs`) and mint a URL third parties can fetch. */
+ async publish(artifact: BlobRef, resources: ResourceStore, key: string): Promise<string> {
+ const bytes = await resources.get(artifact.resource);
+ assert(bytes !== undefined && bytes.byteLength === artifact.size, `Reference Resource ${artifact.resource} is unavailable or has changed`);
+ const path = `hypit/${artifact.resource}.${extensions[artifact.mediaType] ?? artifact.mediaType.split("/")[1] ?? "bin"}`;
+ const put = await this.completeRun({ provider: "sfs", endpoint: "/put", input: { path, sizeBytes: bytes.byteLength } }, key);
+ const uploadUrl = httpsUrl(put.uploadUrl, "Monid sfs /put output");
+ const deadline = requestDeadline(this.timeout);
+ try {
+ const response = await deadline.wait(this.fetcher(uploadUrl, { method: "PUT", body: new Blob([new Uint8Array(bytes)]), signal: deadline.signal }));
+ assert(response.ok, `Monid file upload returned HTTP ${response.status}`);
+ } finally { deadline.finish(); }
+ const cat = await this.completeRun({ provider: "sfs", endpoint: "/cat", input: { path, ttl: "1d" } }, key);
+ return httpsUrl(cat.url, "Monid sfs /cat output");
+ }
+ async download(url: string): Promise<{ readonly bytes: Uint8Array; readonly mediaType: string }> {
+ const deadline = requestDeadline(this.timeout);
+ try {
+ const response = await deadline.wait(this.fetcher(url, { signal: deadline.signal }));
+ if (!response.ok) throw new Error(`Monid asset returned HTTP ${response.status}`);
+ return { bytes: new Uint8Array(await deadline.wait(response.arrayBuffer())), mediaType: response.headers.get("content-type")?.split(";", 1)[0] ?? "application/octet-stream" };
+ } finally { deadline.finish(); }
+ }
+}
+
+function resolverFor(client: MonidClient, context: EndpointInvocationContext, publicAssetUrl: CreateMonidProviderOptions["publicAssetUrl"]): GenerationArtifactUrlResolver {
+ const resolved = new Map<string, Promise<string>>();
+ return (artifact, fields) => {
+ const existing = resolved.get(artifact.resource);
+ if (existing !== undefined) return existing;
+ const promise = publicAssetUrl === undefined
+ ? client.publish(artifact, context.resources, apiKey(context.credentials))
+ : publicAssetUrl(artifact, context.resources, fields);
+ resolved.set(artifact.resource, promise);
+ return promise;
+ };
+}
+
+function endpoint(client: MonidClient, pollIntervalMs: number, maxOperationMs: number, publicAssetUrl: CreateMonidProviderOptions["publicAssetUrl"]): AsyncEndpoint {
+ return {
+ async start(context) {
+ try {
+ 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}` });
+ let input: Record<string, unknown>;
+ try {
+ input = await request.compile(resolverFor(client, context, publicAssetUrl));
+ } catch (error) {
+ 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));
+ 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]);
+ await context.checkpoint?.({ handle: canonicalize(handle), receipt, ...(ended ? { remoteEnded: true as const } : {}) });
+ 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 };
+ } catch (error) {
+ return failure(error);
+ }
+ },
+ async poll(context) {
+ try {
+ const handle = object(context.handle, "Monid handle") as unknown as Handle;
+ const route = monidRouteForCapability(context.need.capability);
+ assert(route !== undefined && handle.contract === "hypit.monid-operation@1" && handle.route === route.key, "Monid handle is invalid");
+ const receipt = { id: handle.runId };
+ if (Date.now() - handle.startedAt > maxOperationMs) {
+ return { status: "failed", receipt, failure: { code: "MONID_OPERATION_TIMEOUT", message: `Monid run ${handle.runId} exceeded this Provider's operationTimeoutMs (${maxOperationMs}); remote outcome is unknown` } };
+ }
+ const run = await client.getRun(handle.runId, apiKey(context.credentials));
+ const status = String(run.status);
+ if (!monidTerminalStatuses.includes(status as typeof monidTerminalStatuses[number])) {
+ return { ...wakeAfter(canonicalize(handle), pollIntervalMs, Date.now(), { phase: 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 };
+ } catch (error) {
+ return failure(error);
+ }
+ },
+ async collect(context) {
+ try {
+ 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 } };
+ } catch (error) {
+ return failure(error);
+ }
+ },
+ };
+}
+
+export function createMonidProvider(options: CreateMonidProviderOptions = {}) {
+ const requestTimeoutMs = options.requestTimeoutMs ?? 300_000;
+ const operationTimeoutMs = options.operationTimeoutMs ?? 30 * 60_000;
+ const pollIntervalMs = options.pollIntervalMs ?? 10_000;
+ for (const [name, value] of Object.entries({ requestTimeoutMs, operationTimeoutMs, pollIntervalMs })) {
+ assert(Number.isSafeInteger(value) && value > 0, `Monid ${name} must be a positive integer`);
+ }
+ const client = new MonidClient(apiBaseUrl(options.baseUrl ?? "https://api.monid.ai"), requestTimeoutMs, Math.min(pollIntervalMs, 5_000), options.fetch ?? globalThis.fetch);
+ 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" },
+ credentials: { apiKey: options.apiKey ?? credentialRef("os", "monid.api-key") },
+ credentialInputs: { apiKey: { label: "Monid API key" } },
+ defaultConcurrency: options.defaultConcurrency ?? 4,
+ ...(options.actionLimits === undefined ? {} : { actionLimits: options.actionLimits }),
+ capabilities: monidRoutes.map((route) => ({
+ capability: route.capability, returns: route.returns, lifecycle: "asynchronous" as const, endpoint: asyncEndpoint, capacity: route.capability.name, supports: route.supports,
+ })),
+ });
+}
diff --git a/packages/provider-monid/src/routes.ts b/packages/provider-monid/src/routes.ts
new file mode 100644
index 00000000..93ee7b21
--- /dev/null
+++ b/packages/provider-monid/src/routes.ts
@@ -0,0 +1,103 @@
+import {
+ compileWireRequest,
+ selectWireModelForRequest,
+ generationTypes,
+ sealGeneratedVideoSet,
+} from "@hypit/generation";
+import type { GenerationArtifactUrlResolver, GenerationRequest, GenerationWireMapping } 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";
+
+export type MonidPreparedRequest = {
+ /** Monid endpoint path under the `bytedance` provider. */
+ readonly endpoint: string;
+ readonly compile: (resolve: GenerationArtifactUrlResolver) => Promise<Record<string, unknown>>;
+};
+
+export type MonidRoute = GenerationWireMapping & {
+ readonly key: string;
+ readonly returns: TypeRef;
+ readonly supports: (request: EndpointRequest) => EndpointSupport;
+ readonly prepare: (constraints: CanonicalValue) => MonidPreparedRequest;
+ readonly packageResult: (artifacts: readonly BlobRef[]) => StoredValue;
+};
+
+function scalar(request: GenerationRequest, port: string): string | number | boolean | undefined {
+ const value = request.ports[port]?.[0];
+ return typeof value === "string" || typeof value === "number" || typeof value === "boolean" ? value : undefined;
+}
+function present(request: GenerationRequest, port: string): boolean {
+ return (request.ports[port]?.length ?? 0) > 0;
+}
+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 {
+ if (scalar(request, "webSearch") === true) {
+ return "Monid's Seedance endpoints document no web search field";
+ }
+ if (mapping.capability.name === "seedance-2.5" && present(request, "firstFrame") && scalar(request, "aspectRatio") !== "adaptive") {
+ return `Seedance 2.5 frame mode takes only aspect-ratio adaptive, not ${String(scalar(request, "aspectRatio"))}`;
+ }
+ return undefined;
+}
+
+function contentItem(type: "image_url" | "video_url" | "audio_url", url: string, role: string) {
+ return { type, [type]: { url }, role };
+}
+
+/** The ModelArk request body Monid relays: one `content` array of typed, role-tagged items plus the output settings. */
+function arkInput(input: Record<string, unknown>): Record<string, unknown> {
+ const first = input.first_frame;
+ const last = input.last_frame;
+ return {
+ content: [
+ { type: "text", text: input.text },
+ ...(typeof first === "string" ? [contentItem("image_url", first, "first_frame")] : []),
+ ...(typeof last === "string" ? [contentItem("image_url", last, "last_frame")] : []),
+ ...strings(input.reference_image).map((url) => contentItem("image_url", url, "reference_image")),
+ ...strings(input.reference_video).map((url) => contentItem("video_url", url, "reference_video")),
+ ...strings(input.reference_audio).map((url) => contentItem("audio_url", url, "reference_audio")),
+ ],
+ resolution: input.resolution,
+ ratio: input.ratio,
+ duration: input.duration,
+ generate_audio: input.generate_audio,
+ };
+}
+
+function capabilityKey(capability: CapabilityRef): string {
+ return `${capability.module.name}@${capability.module.version}#${capability.name}`;
+}
+
+export const monidRoutes: readonly MonidRoute[] = monidMappings.map((mapping) => ({
+ ...mapping,
+ key: capabilityKey(mapping.capability),
+ returns: generationTypes.videoSet,
+ supports: (request) => {
+ const reason = rejection(mapping, request.constraints as unknown as GenerationRequest);
+ return reason === undefined ? { status: "supported" } : { status: "unsupported", reason };
+ },
+ prepare: (constraints) => {
+ const request = constraints as unknown as GenerationRequest;
+ const reason = rejection(mapping, request);
+ if (reason !== undefined) throw new Error(reason);
+ return {
+ endpoint: selectWireModelForRequest(mapping, request),
+ compile: async (resolve) => arkInput((await compileWireRequest(mapping, request, resolve)).input as Record<string, unknown>),
+ };
+ },
+ packageResult: (artifacts) => ({
+ kind: "inline",
+ value: canonicalize(sealGeneratedVideoSet({ videos: artifacts })),
+ }),
+}));
+
+const byCapability = new Map(monidRoutes.map((route) => [route.key, route]));
+
+export function monidRouteForCapability(capability: CapabilityRef): MonidRoute | undefined {
+ return byCapability.get(capabilityKey(capability));
+}
diff --git a/packages/provider-monid/test/routes.test.ts b/packages/provider-monid/test/routes.test.ts
new file mode 100644
index 00000000..6ff6077d
--- /dev/null
+++ b/packages/provider-monid/test/routes.test.ts
@@ -0,0 +1,34 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { assertMappingCoversPorts } from "@hypit/generation";
+import type { BlobRef, CanonicalValue } from "@hypit/protocol";
+import { seedancePorts, sealSeedanceRequest } from "@hypit/seedance";
+
+import { monidMappings } from "../src/mapping.js";
+import { monidRouteForCapability } from "../src/routes.js";
+
+const image: BlobRef = { kind: "blob", resource: "res_monid_1", size: 3, mediaType: "image/png" };
+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);
+ }
+});
+
+test("Seedance requests become the ModelArk input Monid relays", async () => {
+ const route = monidRouteForCapability({ module: { name: "@hypit/seedance", version: "1" }, name: "seedance-2-mini" })!;
+ const request = sealSeedanceRequest("seedance-2-mini", {
+ prompt: ["turn"], referenceImage: [{ role: "image", artifact: image, fields: { personReference: true } }],
+ resolution: ["720p"], aspectRatio: ["9:16"], duration: [6], generateAudio: [true], webSearch: [false],
+ });
+ const prepared = route.prepare(request as unknown as CanonicalValue);
+ assert.equal(prepared.endpoint, "/v1/video/seedance-2.0-mini");
+ assert.deepEqual(await prepared.compile(resolve), {
+ content: [
+ { type: "text", text: "turn" },
+ { type: "image_url", image_url: { url: "https://sfs.monid.ai/signed" }, role: "reference_image" },
+ ],
+ resolution: "720p", ratio: "9:16", duration: 6, generate_audio: true,
+ });
+});
diff --git a/packages/provider-pollo/README.md b/packages/provider-pollo/README.md
new file mode 100644
index 00000000..dc6becff
--- /dev/null
+++ b/packages/provider-pollo/README.md
@@ -0,0 +1,59 @@
+# `@hypit/provider-pollo`
+
+Hypit Runtime Provider for a [Pollo AI](https://docs.pollo.ai) API platform account. Each capability
+posts `{ "input": … }` to the model's generation path with the `x-api-key` header, polls
+`GET /v1/generation/{taskId}/status` until every generation reaches `succeed`, downloads each
+generation's `url` and stores the files in the current Build.
+
+| Capability | Pollo generation path |
+| --- | --- |
+| `@hypit/minimax-h3@1#minimax-h3` | `/v1/generation/minimax/minimax-h3/video` |
+| `@hypit/grok-imagine@1#grok-imagine-video-1.5-preview` | `/v1/generation/xai/grok-imagine-video-1-5/video` |
+| `@hypit/gpt-image@1#gpt-image-2` | `/v1/generation/openai/gpt-image-2/image` |
+| `@hypit/nano-banana@1#nano-banana-2` | `/v1/generation/google/nano-banana-2/image` |
+| `@hypit/nano-banana@1#nano-banana-pro` | `/v1/generation/google/nano-banana-pro/image` |
+
+Pollo documents further models; this Provider maps only the models the Distribution already
+describes. Seedance and Seedream are not offered by Pollo.
+
+MiniMax H3 requests send `prompt`, `duration`, `resolution` and `aspectRatio`; a first frame is
+`image`, a last frame `imageTail`, and reference images, videos and audio become typed entries of
+`refs`. Pollo renders 480p when `resolution` is omitted.
+
+Service limits this Provider reports as unsupported before submitting:
+
+- Grok Imagine 1.5 animates exactly one image and has no aspect-ratio field; author
+ `aspect-ratio="auto"`.
+- GPT Image 2 renders `1:1`, `3:2`, `2:3`, `16:9`, `9:16`, `4:3`, `3:4`, `21:9` and `auto`;
+ other ratios are unsupported. Pollo's `quality` field is left at its default.
+- Nano Banana takes an explicit aspect ratio, not `auto`. `output-format` has no Pollo field and is
+ not sent.
+
+Pollo accepts reference media only by HTTP(S) URL. Configure `publicAssetUrl` when embedding the
+Provider; without it, a request with reference media fails before submission, while text-only
+requests proceed.
+
+Runtime Profile example:
+
+```json
+{
+ "endpoints": {
+ "pollo.default": {
+ "use": "@hypit/provider-pollo",
+ "pool": "pollo.default",
+ "config": {
+ "apiKey": { "store": "platform", "key": "pollo.api-key" },
+ "defaultConcurrency": 3,
+ "pollIntervalMs": 10000
+ }
+ }
+ }
+}
+```
+
+`baseUrl` defaults to `https://pollo.ai/api/platform`. Store the API key with
+`hypit auth login pollo.default --runtime hypit.runtime.json`. Optional `requestTimeoutMs`,
+`operationTimeoutMs` and `actionLimits` bound single HTTP calls, the whole remote task and action
+concurrency. HTTP failures keep Pollo's `errorCode`, message and `requestId`; a failed generation
+keeps its `failMsg`, with any signed URL in the message redacted. Pollo stores generated files for
+14 days; the Provider downloads them when the task completes.
diff --git a/packages/provider-pollo/package.json b/packages/provider-pollo/package.json
new file mode 100644
index 00000000..b7b50266
--- /dev/null
+++ b/packages/provider-pollo/package.json
@@ -0,0 +1,22 @@
+{
+ "name": "@hypit/provider-pollo",
+ "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/endpoint-kit": "workspace:*",
+ "@hypit/generation": "workspace:*",
+ "@hypit/protocol": "workspace:*",
+ "@hypit/runtime": "workspace:*",
+ "@hypit/runtime-kit": "workspace:*"
+ },
+ "devDependencies": {
+ "@hypit/gpt-image": "workspace:*",
+ "@hypit/grok-imagine": "workspace:*",
+ "@hypit/minimax-h3": "workspace:*",
+ "@hypit/nano-banana": "workspace:*"
+ }
+}
diff --git a/packages/provider-pollo/src/activation.ts b/packages/provider-pollo/src/activation.ts
new file mode 100644
index 00000000..a2d13c61
--- /dev/null
+++ b/packages/provider-pollo/src/activation.ts
@@ -0,0 +1,62 @@
+import {
+ createRuntimeEndpointAdapterFacet,
+ runtimeConfigCredentialRef,
+ runtimeConfigActionLimits,
+ runtimeConfigExact,
+ runtimeConfigObject,
+ runtimeConfigPositiveInteger,
+ runtimeConfigString,
+} from "@hypit/runtime-kit";
+
+import { createPolloProvider } from "./provider.js";
+
+const adapter = createRuntimeEndpointAdapterFacet({
+ use: "@hypit/provider-pollo",
+ activate(context) {
+ if (context.pool === undefined) throw new Error("Pollo Provider Pool is required");
+ const config = runtimeConfigObject(context.config, "Pollo");
+ runtimeConfigExact(config, [
+ "baseUrl",
+ "apiKey",
+ "defaultConcurrency",
+ "actionLimits",
+ "pollIntervalMs",
+ "requestTimeoutMs",
+ "operationTimeoutMs",
+ ], "Pollo");
+ const baseUrl = runtimeConfigString(config.baseUrl, "Pollo baseUrl");
+ if (baseUrl !== undefined) {
+ const url = new URL(baseUrl);
+ if (url.protocol !== "https:" && url.hostname !== "localhost" && url.hostname !== "127.0.0.1") {
+ throw new Error("Pollo baseUrl must use HTTPS or loopback");
+ }
+ }
+ const apiKey = runtimeConfigCredentialRef(config.apiKey, "Pollo apiKey");
+ if (apiKey === undefined) throw new Error("Pollo apiKey CredentialRef is required");
+ const actionLimits = runtimeConfigActionLimits(config.actionLimits);
+ const defaultConcurrency = runtimeConfigPositiveInteger(config.defaultConcurrency, "Pollo defaultConcurrency");
+ const pollIntervalMs = runtimeConfigPositiveInteger(config.pollIntervalMs, "Pollo pollIntervalMs");
+ const requestTimeoutMs = runtimeConfigPositiveInteger(config.requestTimeoutMs, "Pollo requestTimeoutMs");
+ const operationTimeoutMs = runtimeConfigPositiveInteger(config.operationTimeoutMs, "Pollo operationTimeoutMs");
+ return {
+ endpoint: createPolloProvider({
+ instance: context.instance,
+ pool: context.pool,
+ ...(baseUrl === undefined ? {} : { baseUrl }),
+ apiKey,
+ ...(defaultConcurrency === undefined ? {} : { defaultConcurrency }),
+ ...(actionLimits === undefined ? {} : { actionLimits }),
+ ...(pollIntervalMs === undefined ? {} : { pollIntervalMs }),
+ ...(requestTimeoutMs === undefined ? {} : { requestTimeoutMs }),
+ ...(operationTimeoutMs === undefined ? {} : { operationTimeoutMs }),
+ }),
+ };
+ },
+});
+
+export const hypitPackage = {
+ format: "hypit.node-package@1" as const,
+ hostFacets: [adapter],
+};
+
+export default hypitPackage;
diff --git a/packages/provider-pollo/src/errors.ts b/packages/provider-pollo/src/errors.ts
new file mode 100644
index 00000000..530ac3e5
--- /dev/null
+++ b/packages/provider-pollo/src/errors.ts
@@ -0,0 +1,41 @@
+/** Pollo's `{ errorCode, message, code, requestId }` envelope and generation `failMsg`, kept at the service boundary. */
+function record(value: unknown): Record<string, unknown> | undefined {
+ return value !== null && typeof value === "object" && !Array.isArray(value)
+ ? value as Record<string, unknown> : undefined;
+}
+function text(value: unknown): string | undefined {
+ return typeof value === "string" && value.trim().length > 0 ? value.trim() : undefined;
+}
+
+// Responses may mention a signed asset URL. Keep the reason, not its access capability.
+export function safePolloReason(value: string): string {
+ return value.replace(/https?:\/\/\S+/giu, "[redacted-url]");
+}
+
+export class PolloServiceError extends Error {
+ constructor(readonly code: string, message: string) { super(message); }
+}
+
+export class PolloHttpError extends PolloServiceError {
+ constructor(readonly status: number, bodyText: string, request: { readonly method: string; readonly path: string }) {
+ let body: Record<string, unknown> | undefined;
+ try { body = record(JSON.parse(bodyText)); } catch { /* Non-JSON gateway failures still have HTTP evidence. */ }
+ const code = text(body?.errorCode) ?? "POLLO_HTTP_ERROR";
+ const reason = text(body?.message) ?? (body === undefined ? text(bodyText.slice(0, 2000)) : undefined);
+ const requestId = text(body?.requestId);
+ const facts = [
+ `Pollo HTTP ${status}`, code, `${request.method} ${request.path}`,
+ ...(requestId === undefined ? [] : [`request=${requestId}`]),
+ ];
+ super(code, `${facts.join("; ")}${reason === undefined ? "" : `: ${safePolloReason(reason)}`}`);
+ }
+}
+
+/** The first failed generation of a task; `undefined` when none failed. */
+export function polloTaskFailure(generations: readonly Record<string, unknown>[], id: string): PolloServiceError | undefined {
+ const failed = generations.find((generation) => generation.status === "failed");
+ if (failed === undefined) return undefined;
+ const reason = text(failed.failMsg);
+ return new PolloServiceError("POLLO_TASK_FAILED",
+ `Pollo task ${id} failed${reason === undefined ? "" : `: ${safePolloReason(reason)}`}`);
+}
diff --git a/packages/provider-pollo/src/index.ts b/packages/provider-pollo/src/index.ts
new file mode 100644
index 00000000..691f1710
--- /dev/null
+++ b/packages/provider-pollo/src/index.ts
@@ -0,0 +1,2 @@
+export { createPolloProvider, polloProviderModuleRef } from "./provider.js";
+export type { CreatePolloProviderOptions } from "./provider.js";
diff --git a/packages/provider-pollo/src/mapping.ts b/packages/provider-pollo/src/mapping.ts
new file mode 100644
index 00000000..50d97b3b
--- /dev/null
+++ b/packages/provider-pollo/src/mapping.ts
@@ -0,0 +1,60 @@
+import type { ModuleRef } from "@hypit/protocol";
+import type { GenerationWireMapping } from "@hypit/generation";
+
+const MINIMAX: ModuleRef = { name: "@hypit/minimax-h3", version: "1" };
+const GROK: ModuleRef = { name: "@hypit/grok-imagine", version: "1" };
+const GPT_IMAGE: ModuleRef = { name: "@hypit/gpt-image", version: "1" };
+const NANO_BANANA: ModuleRef = { name: "@hypit/nano-banana", version: "1" };
+
+/**
+ * Pollo generation paths and the `input` fields each documents. The route model is the request
+ * path under the Pollo platform base URL. Reference fields prefixed `refs_` are folded into MiniMax's
+ * typed `refs` array by routes.ts.
+ */
+export const polloMappings: readonly GenerationWireMapping[] = [
+ {
+ capability: { module: MINIMAX, name: "minimax-h3" }, result: "video", routes: [{ model: "/v1/generation/minimax/minimax-h3/video" }],
+ fields: {
+ prompt: { as: "value", field: "prompt" },
+ duration: { as: "value", field: "duration" },
+ resolution: { as: "value", field: "resolution" },
+ aspectRatio: { as: "value", field: "aspectRatio" },
+ firstFrame: { as: "url", field: "image" },
+ lastFrame: { as: "url", field: "imageTail" },
+ referenceImage: { as: "urlArray", field: "refs_image" },
+ referenceVideo: { as: "urlArray", field: "refs_video" },
+ referenceAudio: { as: "urlArray", field: "refs_audio" },
+ },
+ },
+ {
+ capability: { module: GROK, name: "grok-imagine-video-1.5-preview" }, result: "video",
+ routes: [{ model: "/v1/generation/xai/grok-imagine-video-1-5/video" }],
+ fields: {
+ prompt: { as: "value", field: "prompt" },
+ aspectRatio: { as: "value", field: "aspect_ratio" },
+ resolution: { as: "value", field: "resolution" },
+ duration: { as: "value", field: "duration" },
+ images: { as: "urlArray", field: "images" },
+ },
+ },
+ {
+ capability: { module: GPT_IMAGE, name: "gpt-image-2" }, result: "image", routes: [{ model: "/v1/generation/openai/gpt-image-2/image" }],
+ fields: {
+ prompt: { as: "value", field: "prompt" },
+ aspectRatio: { as: "value", field: "aspectRatio" },
+ resolution: { as: "value", field: "resolution" },
+ background: { as: "value", field: "background" },
+ images: { as: "urlArray", field: "images" },
+ },
+ },
+ ...(["nano-banana-2", "nano-banana-pro"] as const).map((name): GenerationWireMapping => ({
+ capability: { module: NANO_BANANA, name }, result: "image", routes: [{ model: `/v1/generation/google/${name}/image` }],
+ fields: {
+ prompt: { as: "value", field: "prompt" },
+ images: { as: "urlArray", field: "images" },
+ aspectRatio: { as: "value", field: "aspectRatio" },
+ resolution: { as: "value", field: "resolution" },
+ outputFormat: { as: "value", field: "output_format" },
+ },
+ })),
+];
diff --git a/packages/provider-pollo/src/provider.ts b/packages/provider-pollo/src/provider.ts
new file mode 100644
index 00000000..ff3ffdcd
--- /dev/null
+++ b/packages/provider-pollo/src/provider.ts
@@ -0,0 +1,194 @@
+import { requestDeadline } from "@hypit/runtime-kit";
+import type { AsyncEndpoint, EndpointCredential, EndpointInvocationContext, EndpointOutcome } from "@hypit/endpoint-kit";
+import { defineEndpointPackage, wakeAfter } from "@hypit/endpoint-kit";
+import type { GenerationArtifactUrlResolver } from "@hypit/generation";
+import { canonicalize } from "@hypit/protocol";
+import type { BlobRef, CapabilityRef } from "@hypit/protocol";
+import { credentialRef } from "@hypit/runtime";
+import type { CredentialRef, ResourceStore } from "@hypit/runtime";
+import { polloRouteForCapability, polloRoutes } from "./routes.js";
+import { PolloHttpError, PolloServiceError, polloTaskFailure } from "./errors.js";
+
+export const polloProviderModuleRef = { name: "@hypit/provider-pollo", version: "1" } as const;
+
+export type CreatePolloProviderOptions = {
+ readonly instance?: string;
+ readonly pool?: string;
+ readonly baseUrl?: string;
+ readonly apiKey?: CredentialRef;
+ readonly defaultConcurrency?: number;
+ readonly actionLimits?: import("@hypit/endpoint-kit").EndpointActionLimits;
+ readonly pollIntervalMs?: number;
+ readonly requestTimeoutMs?: number;
+ readonly operationTimeoutMs?: number;
+ readonly fetch?: typeof globalThis.fetch;
+ /** Publish a referenced Resource at an HTTP(S) URL Pollo can fetch. Pollo accepts no inline media. */
+ readonly publicAssetUrl?: (artifact: BlobRef, artifacts: ResourceStore, fields?: Readonly<Record<string, string | number | boolean>>) => Promise<string>;
+};
+
+type Handle = {
+ readonly contract: "hypit.pollo-operation@1";
+ readonly taskId: string;
+ readonly route: string;
+ readonly startedAt: number;
+ readonly urls?: readonly string[];
+};
+
+function assert(condition: unknown, message: string): asserts condition { if (!condition) throw new Error(message); }
+function object(value: unknown, subject: string): Record<string, unknown> {
+ assert(value !== null && typeof value === "object" && !Array.isArray(value), `${subject} must be an object`);
+ return value as Record<string, unknown>;
+}
+function capabilityKey(capability: CapabilityRef): string { return `${capability.module.name}@${capability.module.version}#${capability.name}`; }
+function apiBaseUrl(value: string): string {
+ let trimmed = value.trim();
+ while (trimmed.endsWith("/")) trimmed = trimmed.slice(0, -1);
+ assert(trimmed.length > 0, "Pollo base URL is empty");
+ return trimmed;
+}
+function apiKey(credentials: Readonly<Record<string, EndpointCredential>>): string {
+ const value = credentials.apiKey?.secret;
+ assert(typeof value === "string" && value.length > 0, "Pollo apiKey credential is unavailable; store a Pollo API key for this Endpoint");
+ return value;
+}
+function failureMessage(error: unknown): string {
+ return error instanceof Error ? error.message : String(error);
+}
+function failure(error: unknown): EndpointOutcome {
+ return { status: "failed", failure: { code: error instanceof PolloServiceError ? error.code : "POLLO_ERROR", message: failureMessage(error) } };
+}
+
+class PolloClient {
+ constructor(readonly baseUrl: string, readonly timeout: number, readonly fetcher: typeof globalThis.fetch) {}
+ async json(path: string, key: string, init: RequestInit = {}): Promise<Record<string, unknown>> {
+ const deadline = requestDeadline(this.timeout);
+ try {
+ const response = await deadline.wait(this.fetcher(`${this.baseUrl}${path}`, {
+ ...init, signal: deadline.signal, headers: { "x-api-key": key, ...(init.headers ?? {}) },
+ }));
+ const text = await deadline.wait(response.text());
+ if (!response.ok) throw new PolloHttpError(response.status, text, { method: init.method ?? "GET", path });
+ let body: unknown;
+ try { body = text.length === 0 ? {} : JSON.parse(text); } catch { throw new Error(`Pollo returned invalid JSON (${response.status})`); }
+ return object(body, "Pollo response");
+ } finally { deadline.finish(); }
+ }
+ async download(url: string): Promise<{ readonly bytes: Uint8Array; readonly mediaType: string }> {
+ const deadline = requestDeadline(this.timeout);
+ try {
+ const response = await deadline.wait(this.fetcher(url, { signal: deadline.signal }));
+ if (!response.ok) throw new Error(`Pollo asset returned HTTP ${response.status}`);
+ return { bytes: new Uint8Array(await deadline.wait(response.arrayBuffer())), mediaType: response.headers.get("content-type")?.split(";", 1)[0] ?? "application/octet-stream" };
+ } finally { deadline.finish(); }
+ }
+}
+
+function resolverFor(context: EndpointInvocationContext, publicAssetUrl: CreatePolloProviderOptions["publicAssetUrl"]): GenerationArtifactUrlResolver {
+ const resolved = new Map<string, Promise<string>>();
+ return (artifact, fields) => {
+ const existing = resolved.get(artifact.resource);
+ if (existing !== undefined) return existing;
+ assert(publicAssetUrl !== undefined,
+ "Pollo accepts reference media only by HTTP(S) URL; configure publicAssetUrl for this Endpoint");
+ const promise = publicAssetUrl(artifact, context.resources, fields);
+ resolved.set(artifact.resource, promise);
+ return promise;
+ };
+}
+
+function endpoint(client: PolloClient, pollIntervalMs: number, maxOperationMs: number, publicAssetUrl: CreatePolloProviderOptions["publicAssetUrl"]): AsyncEndpoint {
+ return {
+ async start(context) {
+ try {
+ const route = polloRouteForCapability(context.need.capability);
+ assert(route !== undefined, "Pollo does not implement this exact capability");
+ const request = route.prepare(context.need.constraints);
+ await context.reportProgress?.({ phase: `Preparing Pollo request: ${request.path}` });
+ let body: Record<string, unknown>;
+ try {
+ body = await request.compile(resolverFor(context, publicAssetUrl));
+ } catch (error) {
+ throw new PolloServiceError(error instanceof PolloServiceError ? error.code : "POLLO_ERROR",
+ `Pollo request preparation failed; path=${request.path}; generation not submitted: ${failureMessage(error)}`);
+ }
+ await context.reportProgress?.({ phase: `Submitting Pollo request: ${request.path}` });
+ const response = await client.json(request.path, apiKey(context.credentials), {
+ method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify(body),
+ });
+ assert(typeof response.taskId === "string" && response.taskId.length > 0, "Pollo response has no taskId");
+ const handle: Handle = { contract: "hypit.pollo-operation@1", taskId: response.taskId, route: route.key, startedAt: Date.now() };
+ const receipt = { id: handle.taskId };
+ await context.checkpoint?.({ handle: canonicalize(handle), receipt });
+ return { ...wakeAfter(canonicalize(handle), pollIntervalMs, Date.now(), { phase: String(response.status ?? "submitted") }), receipt };
+ } catch (error) {
+ return failure(error);
+ }
+ },
+ async poll(context) {
+ try {
+ const handle = object(context.handle, "Pollo handle") as unknown as Handle;
+ const route = polloRouteForCapability(context.need.capability);
+ assert(route !== undefined && handle.contract === "hypit.pollo-operation@1" && handle.route === route.key, "Pollo handle is invalid");
+ const receipt = { id: handle.taskId };
+ if (Date.now() - handle.startedAt > maxOperationMs) {
+ return { status: "failed", receipt, failure: { code: "POLLO_OPERATION_TIMEOUT", message: `Pollo task ${handle.taskId} exceeded this Provider's operationTimeoutMs (${maxOperationMs}); remote outcome is unknown` } };
+ }
+ const task = await client.json(`/v1/generation/${encodeURIComponent(handle.taskId)}/status`, apiKey(context.credentials));
+ assert(Array.isArray(task.generations) && task.generations.length > 0, "Pollo task has no generations");
+ const generations = task.generations.map((item, index) => object(item, `Pollo generation ${index + 1}`));
+ const rejected = polloTaskFailure(generations, handle.taskId);
+ if (rejected !== undefined) return { ...failure(rejected), receipt };
+ const pending = generations.find((generation) => generation.status !== "succeed");
+ if (pending !== undefined) {
+ const status = String(pending.status);
+ assert(status === "waiting" || status === "processing", `Pollo returned unknown generation status ${status}`);
+ return { ...wakeAfter(canonicalize(handle), pollIntervalMs, Date.now(), { phase: status }), receipt };
+ }
+ const urls = generations.map((generation, index) => {
+ assert(typeof generation.url === "string" && /^https?:\/\//u.test(generation.url), `Pollo generation ${index + 1} has no URL`);
+ return generation.url;
+ });
+ return { status: "ready", handle: canonicalize({ ...handle, urls }), receipt };
+ } catch (error) {
+ return failure(error);
+ }
+ },
+ async collect(context) {
+ try {
+ const handle = object(context.handle, "Pollo handle") as unknown as Handle;
+ const route = polloRouteForCapability(context.need.capability);
+ assert(route !== undefined && handle.route === route.key && Array.isArray(handle.urls), "Pollo collection route differs");
+ await context.reportProgress?.({ phase: "Receiving generated files" });
+ const blobs: BlobRef[] = [];
+ for (const url of handle.urls) {
+ const downloaded = await client.download(url);
+ blobs.push(await context.resources.put(downloaded.bytes, downloaded.mediaType));
+ }
+ return { status: "completed", result: { value: route.packageResult(blobs) }, receipt: { id: handle.taskId } };
+ } catch (error) {
+ return failure(error);
+ }
+ },
+ };
+}
+
+export function createPolloProvider(options: CreatePolloProviderOptions = {}) {
+ const requestTimeoutMs = options.requestTimeoutMs ?? 300_000;
+ const operationTimeoutMs = options.operationTimeoutMs ?? 30 * 60_000;
+ for (const [name, value] of Object.entries({ requestTimeoutMs, operationTimeoutMs })) {
+ assert(Number.isSafeInteger(value) && value > 0, `Pollo ${name} must be a positive integer`);
+ }
+ const client = new PolloClient(apiBaseUrl(options.baseUrl ?? "https://pollo.ai/api/platform"), requestTimeoutMs, options.fetch ?? globalThis.fetch);
+ const asyncEndpoint = endpoint(client, options.pollIntervalMs ?? 10_000, operationTimeoutMs, options.publicAssetUrl);
+ return defineEndpointPackage({
+ module: polloProviderModuleRef, facet: "gateway", instance: options.instance ?? "pollo.default", pool: options.pool ?? options.instance ?? "pollo.default",
+ pricing: { kind: "page", url: "https://api.pollo.ai/pricing" },
+ credentials: { apiKey: options.apiKey ?? credentialRef("os", "pollo.api-key") },
+ credentialInputs: { apiKey: { label: "Pollo API key" } },
+ defaultConcurrency: options.defaultConcurrency ?? 4,
+ ...(options.actionLimits === undefined ? {} : { actionLimits: options.actionLimits }),
+ capabilities: polloRoutes.map((route) => ({
+ capability: route.capability, returns: route.returns, lifecycle: "asynchronous" as const, endpoint: asyncEndpoint, capacity: route.capability.name, supports: route.supports,
+ })),
+ });
+}
diff --git a/packages/provider-pollo/src/routes.ts b/packages/provider-pollo/src/routes.ts
new file mode 100644
index 00000000..9b9e77f1
--- /dev/null
+++ b/packages/provider-pollo/src/routes.ts
@@ -0,0 +1,120 @@
+import {
+ compileWireRequest,
+ selectWireModelForRequest,
+ generationTypes,
+ sealGeneratedImageSet,
+ sealGeneratedVideoSet,
+} from "@hypit/generation";
+import type { GenerationArtifactUrlResolver, GenerationRequest, GenerationWireMapping } 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 { polloMappings } from "./mapping.js";
+
+export type PolloPreparedRequest = {
+ /** Request path under the Pollo platform base URL. */
+ readonly path: string;
+ readonly compile: (resolve: GenerationArtifactUrlResolver) => Promise<Record<string, unknown>>;
+};
+
+export type PolloRoute = GenerationWireMapping & {
+ readonly key: string;
+ readonly returns: TypeRef;
+ readonly supports: (request: EndpointRequest) => EndpointSupport;
+ readonly prepare: (constraints: CanonicalValue) => PolloPreparedRequest;
+ readonly packageResult: (artifacts: readonly BlobRef[]) => StoredValue;
+};
+
+function scalar(request: GenerationRequest, port: string): string | number | boolean | undefined {
+ const value = request.ports[port]?.[0];
+ return typeof value === "string" || typeof value === "number" || typeof value === "boolean" ? value : undefined;
+}
+function count(request: GenerationRequest, port: string): number {
+ return request.ports[port]?.length ?? 0;
+}
+function strings(value: unknown): readonly string[] {
+ return Array.isArray(value) ? value.filter((item): item is string => typeof item === "string" && item.length > 0) : [];
+}
+
+const GPT_IMAGE_RATIOS = ["1:1", "3:2", "2:3", "16:9", "9:16", "4:3", "3:4", "21:9", "auto"];
+
+/** Pollo's documented input ranges for each mapped model, checked before any reference is resolved. */
+function rejection(mapping: GenerationWireMapping, request: GenerationRequest): string | undefined {
+ const { name } = mapping.capability;
+ const ratio = scalar(request, "aspectRatio");
+ if (name === "grok-imagine-video-1.5-preview") {
+ if (count(request, "images") !== 1) return "Pollo Grok Imagine 1.5 animates exactly one image";
+ if (ratio !== "auto") return `Pollo Grok Imagine 1.5 takes no aspect ratio; use auto, not ${String(ratio)}`;
+ }
+ if (name === "gpt-image-2" && !GPT_IMAGE_RATIOS.includes(String(ratio))) {
+ return `Pollo GPT Image 2 does not render ${String(ratio)}`;
+ }
+ if (mapping.capability.module.name === "@hypit/nano-banana" && ratio === "auto") {
+ return `Pollo ${name} takes an explicit aspect ratio, not auto`;
+ }
+ return undefined;
+}
+
+function ref(type: "image" | "video" | "audio") {
+ return (url: string) => ({ url, type });
+}
+
+/** Fields the model package requires that Pollo names differently or does not take. */
+function normalize(mapping: GenerationWireMapping, input: Record<string, unknown>): Record<string, unknown> {
+ const { name } = mapping.capability;
+ if (name === "minimax-h3") {
+ const refs = [
+ ...strings(input.refs_image).map(ref("image")),
+ ...strings(input.refs_video).map(ref("video")),
+ ...strings(input.refs_audio).map(ref("audio")),
+ ];
+ delete input.refs_image;
+ delete input.refs_video;
+ delete input.refs_audio;
+ if (refs.length > 0) input.refs = refs;
+ }
+ if (name === "grok-imagine-video-1.5-preview") {
+ input.image = strings(input.images)[0];
+ delete input.images;
+ delete input.aspect_ratio;
+ }
+ if (mapping.capability.module.name === "@hypit/nano-banana") delete input.output_format;
+ return input;
+}
+
+function capabilityKey(capability: CapabilityRef): string {
+ return `${capability.module.name}@${capability.module.version}#${capability.name}`;
+}
+
+export const polloRoutes: readonly PolloRoute[] = polloMappings.map((mapping) => ({
+ ...mapping,
+ key: capabilityKey(mapping.capability),
+ returns: mapping.result === "image" ? generationTypes.imageSet : generationTypes.videoSet,
+ supports: (request) => {
+ const reason = rejection(mapping, request.constraints as unknown as GenerationRequest);
+ return reason === undefined ? { status: "supported" } : { status: "unsupported", reason };
+ },
+ prepare: (constraints) => {
+ const request = constraints as unknown as GenerationRequest;
+ const reason = rejection(mapping, request);
+ if (reason !== undefined) throw new Error(reason);
+ return {
+ path: selectWireModelForRequest(mapping, request),
+ compile: async (resolve) => ({
+ input: normalize(mapping, (await compileWireRequest(mapping, request, resolve)).input as Record<string, unknown>),
+ }),
+ };
+ },
+ packageResult: (artifacts) => ({
+ kind: "inline",
+ value: canonicalize(mapping.result === "image"
+ ? sealGeneratedImageSet({ images: artifacts })
+ : sealGeneratedVideoSet({ videos: artifacts })),
+ }),
+}));
+
+const byCapability = new Map(polloRoutes.map((route) => [route.key, route]));
+
+export function polloRouteForCapability(capability: CapabilityRef): PolloRoute | undefined {
+ return byCapability.get(capabilityKey(capability));
+}
diff --git a/packages/provider-pollo/test/routes.test.ts b/packages/provider-pollo/test/routes.test.ts
new file mode 100644
index 00000000..59c3b944
--- /dev/null
+++ b/packages/provider-pollo/test/routes.test.ts
@@ -0,0 +1,50 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { assertMappingCoversPorts } from "@hypit/generation";
+import type { BlobRef, CanonicalValue } from "@hypit/protocol";
+import { gptImage2Ports } from "@hypit/gpt-image";
+import { grokImaginePorts, sealGrokImagineRequest } from "@hypit/grok-imagine";
+import { minimaxH3Ports, sealMinimaxH3Request } from "@hypit/minimax-h3";
+import { nanoBananaPorts } from "@hypit/nano-banana";
+
+import { polloMappings } from "../src/mapping.js";
+import { polloRouteForCapability } from "../src/routes.js";
+
+const image: BlobRef = { kind: "blob", resource: "res_pollo_1", size: 3, mediaType: "image/png" };
+const audio: BlobRef = { kind: "blob", resource: "res_pollo_2", size: 3, mediaType: "audio/wav" };
+const resolve = async (artifact: { resource: string }) => `https://example.test/${artifact.resource}`;
+const route = (module: string, name: string) => polloRouteForCapability({ module: { name: module, version: "1" }, name })!;
+const constraints = (request: unknown) => request as CanonicalValue;
+
+test("every Pollo mapping covers its model's ports", () => {
+ const tables = { ...grokImaginePorts, ...nanoBananaPorts, "minimax-h3": minimaxH3Ports, "gpt-image-2": gptImage2Ports };
+ for (const mapping of polloMappings) {
+ assertMappingCoversPorts(tables[mapping.capability.name as keyof typeof tables], mapping);
+ }
+});
+
+test("MiniMax H3 references become Pollo typed refs", async () => {
+ const minimax = route("@hypit/minimax-h3", "minimax-h3");
+ const request = sealMinimaxH3Request({
+ prompt: ["walk"], duration: [6], resolution: ["2K"], aspectRatio: ["9:16"],
+ referenceImage: [{ role: "image", artifact: image }], referenceAudio: [{ role: "audio", artifact: audio }],
+ });
+ const prepared = minimax.prepare(constraints(request));
+ assert.equal(prepared.path, "/v1/generation/minimax/minimax-h3/video");
+ assert.deepEqual(await prepared.compile(resolve), { input: {
+ prompt: "walk", duration: 6, resolution: "2K", aspectRatio: "9:16",
+ refs: [{ url: "https://example.test/res_pollo_1", type: "image" }, { url: "https://example.test/res_pollo_2", type: "audio" }],
+ } });
+});
+
+test("Grok Imagine 1.5 sends its single image and takes only aspect-ratio auto", async () => {
+ const grok = route("@hypit/grok-imagine", "grok-imagine-video-1.5-preview");
+ const request = sealGrokImagineRequest("grok-imagine-video-1.5-preview", {
+ prompt: ["spin"], aspectRatio: ["auto"], resolution: ["720p"], duration: [8], images: [{ role: "image", artifact: image }],
+ });
+ assert.deepEqual(await grok.prepare(constraints(request)).compile(resolve), { input: {
+ prompt: "spin", resolution: "720p", duration: 8, image: "https://example.test/res_pollo_1",
+ } });
+ const framed = sealGrokImagineRequest("grok-imagine-video-1.5-preview", { ...request.ports, aspectRatio: ["16:9"] });
+ assert.equal(grok.supports({ capability: grok.capability, returns: grok.returns, constraints: constraints(framed) }).status, "unsupported");
+});
diff --git a/packages/provider-tokendance/README.md b/packages/provider-tokendance/README.md
new file mode 100644
index 00000000..eca0c893
--- /dev/null
+++ b/packages/provider-tokendance/README.md
@@ -0,0 +1,67 @@
+# `@hypit/provider-tokendance`
+
+Hypit Runtime Provider for a [TokenDance](https://tokendance.space) account. It submits generation
+requests with a TokenDance API key through the gateway protocols TokenDance documents for each model
+and stores the returned files in the current Build.
+
+| Capability | TokenDance model | Protocol |
+| --- | --- | --- |
+| `@hypit/seedance@1#seedance-2` | `seedance-2.0` | Ark `POST /ark/v3/generations/tasks`, polled at `GET /ark/v3/generations/tasks/{id}` |
+| `@hypit/seedance@1#seedance-2-fast` | `seedance-2.0-fast` | same |
+| `@hypit/seedance@1#seedance-2-mini` | `seedance-2.0-mini` | same |
+| `@hypit/seedance@1#seedance-2.5` | `seedance-2.5` | same |
+| `@hypit/seedream@1#seedream-5-lite` | `seedream-5.0-lite` | Ark `POST /ark/v3/images/generations`, synchronous |
+| `@hypit/minimax-h3@1#minimax-h3` | `minimax-h3` | MiniMax `POST /minimax/v2/video_generation`, polled at `GET /minimax/v2/query/video_generation/{id}` |
+
+The TokenDance catalogue at `GET /gateway/v1/models` lists further models; this Provider maps only
+the models the Distribution already describes.
+
+Video requests write the prompt and each media input as one item of the protocol's `content`
+array with its `role` (`first_frame`, `last_frame`, `reference_image`, `reference_video`,
+`reference_audio`), then `resolution`, `ratio`, `duration` and, for Seedance, `generate_audio`;
+`web-search="true"` adds `tools: [{ "type": "web_search" }]`. Seedance visual references may carry
+`person-reference`; the Provider accepts the declaration and transmits nothing for it, since the Ark
+protocol has no such field. Seedance 2.0 and 2.5 reject reference images and videos that contain a
+real human face; TokenDance offers no way to register authorized portrait material, so such a request
+fails with the service's moderation error.
+
+Seedream requests send the Ark `size` in pixels: the authored `quality` selects the 2K, 3K or 4K
+tier and `aspect-ratio` the entry from the Ark reference table for Seedream 5.0 lite. Output uses
+`response_format: "url"` and `watermark: false`. `nsfw-check` has no Ark field and is not sent.
+
+Service limits this Provider reports as unsupported before submitting:
+
+- Seedance 2.5 frame mode (`first-frame` present) requires `aspect-ratio="adaptive"`.
+- MiniMax H3 text-to-video requires an explicit `aspect-ratio`; frame and reference modes may omit it.
+
+Reference media reach each protocol the way its documentation provides. Ark takes images under
+30 MB and audio up to 15 MB inline as `data:` URLs within a 64 MB request body; the Provider checks
+both before submitting. An Ark reference video takes a URL only; configure `publicAssetUrl` when
+embedding the Provider, otherwise such a request fails before submission. MiniMax inputs are
+uploaded through the gateway's `POST /minimax/v1/files/upload` with `purpose:
+video_generation_input` (images up to 30 MB, videos up to 50 MB, audio up to 15 MB) and referenced
+as `mm_file://{file_id}`; MiniMax keeps such files for seven days.
+
+Runtime Profile example:
+
+```json
+{
+ "endpoints": {
+ "tokendance.default": {
+ "use": "@hypit/provider-tokendance",
+ "pool": "tokendance.default",
+ "config": {
+ "apiKey": { "store": "platform", "key": "tokendance.api-key" },
+ "defaultConcurrency": 3,
+ "pollIntervalMs": 10000
+ }
+ }
+ }
+}
+```
+
+`baseUrl` defaults to `https://tokendance.space/gateway`. Store the API key with
+`hypit auth login tokendance.default --runtime hypit.runtime.json`. Optional `requestTimeoutMs`,
+`operationTimeoutMs` and `actionLimits` bound single HTTP calls, the whole remote task and action
+concurrency. Task and HTTP failures keep TokenDance's `error.code` and message, with any signed URL
+in the message redacted.
diff --git a/packages/provider-tokendance/package.json b/packages/provider-tokendance/package.json
new file mode 100644
index 00000000..78a714d6
--- /dev/null
+++ b/packages/provider-tokendance/package.json
@@ -0,0 +1,21 @@
+{
+ "name": "@hypit/provider-tokendance",
+ "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/endpoint-kit": "workspace:*",
+ "@hypit/generation": "workspace:*",
+ "@hypit/protocol": "workspace:*",
+ "@hypit/runtime": "workspace:*",
+ "@hypit/runtime-kit": "workspace:*"
+ },
+ "devDependencies": {
+ "@hypit/minimax-h3": "workspace:*",
+ "@hypit/seedance": "workspace:*",
+ "@hypit/seedream": "workspace:*"
+ }
+}
diff --git a/packages/provider-tokendance/src/activation.ts b/packages/provider-tokendance/src/activation.ts
new file mode 100644
index 00000000..2a2eec12
--- /dev/null
+++ b/packages/provider-tokendance/src/activation.ts
@@ -0,0 +1,62 @@
+import {
+ createRuntimeEndpointAdapterFacet,
+ runtimeConfigCredentialRef,
+ runtimeConfigActionLimits,
+ runtimeConfigExact,
+ runtimeConfigObject,
+ runtimeConfigPositiveInteger,
+ runtimeConfigString,
+} from "@hypit/runtime-kit";
+
+import { createTokenDanceProvider } from "./provider.js";
+
+const adapter = createRuntimeEndpointAdapterFacet({
+ use: "@hypit/provider-tokendance",
+ activate(context) {
+ if (context.pool === undefined) throw new Error("TokenDance Provider Pool is required");
+ const config = runtimeConfigObject(context.config, "TokenDance");
+ runtimeConfigExact(config, [
+ "baseUrl",
+ "apiKey",
+ "defaultConcurrency",
+ "actionLimits",
+ "pollIntervalMs",
+ "requestTimeoutMs",
+ "operationTimeoutMs",
+ ], "TokenDance");
+ const baseUrl = runtimeConfigString(config.baseUrl, "TokenDance baseUrl");
+ if (baseUrl !== undefined) {
+ const url = new URL(baseUrl);
+ if (url.protocol !== "https:" && url.hostname !== "localhost" && url.hostname !== "127.0.0.1") {
+ throw new Error("TokenDance baseUrl must use HTTPS or loopback");
+ }
+ }
+ const apiKey = runtimeConfigCredentialRef(config.apiKey, "TokenDance apiKey");
+ if (apiKey === undefined) throw new Error("TokenDance apiKey CredentialRef is required");
+ const actionLimits = runtimeConfigActionLimits(config.actionLimits);
+ const defaultConcurrency = runtimeConfigPositiveInteger(config.defaultConcurrency, "TokenDance defaultConcurrency");
+ const pollIntervalMs = runtimeConfigPositiveInteger(config.pollIntervalMs, "TokenDance pollIntervalMs");
+ const requestTimeoutMs = runtimeConfigPositiveInteger(config.requestTimeoutMs, "TokenDance requestTimeoutMs");
+ const operationTimeoutMs = runtimeConfigPositiveInteger(config.operationTimeoutMs, "TokenDance operationTimeoutMs");
+ return {
+ endpoint: createTokenDanceProvider({
+ instance: context.instance,
+ pool: context.pool,
+ ...(baseUrl === undefined ? {} : { baseUrl }),
+ apiKey,
+ ...(defaultConcurrency === undefined ? {} : { defaultConcurrency }),
+ ...(actionLimits === undefined ? {} : { actionLimits }),
+ ...(pollIntervalMs === undefined ? {} : { pollIntervalMs }),
+ ...(requestTimeoutMs === undefined ? {} : { requestTimeoutMs }),
+ ...(operationTimeoutMs === undefined ? {} : { operationTimeoutMs }),
+ }),
+ };
+ },
+});
+
+export const hypitPackage = {
+ format: "hypit.node-package@1" as const,
+ hostFacets: [adapter],
+};
+
+export default hypitPackage;
diff --git a/packages/provider-tokendance/src/errors.ts b/packages/provider-tokendance/src/errors.ts
new file mode 100644
index 00000000..078d83ff
--- /dev/null
+++ b/packages/provider-tokendance/src/errors.ts
@@ -0,0 +1,47 @@
+/** TokenDance relays each protocol's own error body; keep the code, the message and the HTTP facts. */
+function record(value: unknown): Record<string, unknown> | undefined {
+ return value !== null && typeof value === "object" && !Array.isArray(value)
+ ? value as Record<string, unknown> : undefined;
+}
+function text(value: unknown): string | undefined {
+ return typeof value === "string" && value.trim().length > 0 ? value.trim() : undefined;
+}
+
+// Responses may mention a signed asset URL. Keep the reason, not its access capability.
+export function safeTokenDanceReason(value: string): string {
+ return value.replace(/https?:\/\/\S+/giu, "[redacted-url]");
+}
+
+export class TokenDanceServiceError extends Error {
+ constructor(readonly code: string, message: string) { super(message); }
+}
+
+export class TokenDanceHttpError extends TokenDanceServiceError {
+ constructor(readonly status: number, response: { readonly headers: Headers }, bodyText: string,
+ request: { readonly method: string; readonly path: string; readonly model?: string }) {
+ let body: Record<string, unknown> | undefined;
+ try { body = record(JSON.parse(bodyText)); } catch { /* Non-JSON gateway failures still have HTTP evidence. */ }
+ const error = record(body?.error);
+ const code = text(error?.code) ?? text(error?.type) ?? text(body?.code) ?? "TOKENDANCE_HTTP_ERROR";
+ const reason = text(error?.message) ?? text(body?.message)
+ ?? (body === undefined ? text(bodyText.slice(0, 2000)) : undefined);
+ const requestId = text(response.headers.get("x-request-id"));
+ const facts = [
+ `TokenDance HTTP ${status}`, code, `${request.method} ${request.path}`,
+ ...(request.model === undefined ? [] : [`model=${request.model}`]),
+ ...(requestId === undefined ? [] : [`request=${requestId}`]),
+ ];
+ super(code, `${facts.join("; ")}${reason === undefined ? "" : `: ${safeTokenDanceReason(reason)}`}`);
+ }
+}
+
+/** A terminal task body from either protocol; `undefined` when the task did not fail. */
+export function tokenDanceTaskFailure(task: Record<string, unknown>, id: string): TokenDanceServiceError | undefined {
+ const status = String(task.status);
+ if (!["failed", "cancelled", "canceled", "expired"].includes(status)) return undefined;
+ const error = record(task.error);
+ const code = text(error?.code) ?? "TOKENDANCE_TASK_FAILED";
+ const reason = text(error?.message) ?? text(task.error);
+ return new TokenDanceServiceError(code,
+ `TokenDance task ${id} ${status}; ${code}${reason === undefined ? "" : `: ${safeTokenDanceReason(reason)}`}`);
+}
diff --git a/packages/provider-tokendance/src/index.ts b/packages/provider-tokendance/src/index.ts
new file mode 100644
index 00000000..fd660030
--- /dev/null
+++ b/packages/provider-tokendance/src/index.ts
@@ -0,0 +1,2 @@
+export { createTokenDanceProvider, tokenDanceProviderModuleRef } from "./provider.js";
+export type { CreateTokenDanceProviderOptions } from "./provider.js";
diff --git a/packages/provider-tokendance/src/mapping.ts b/packages/provider-tokendance/src/mapping.ts
new file mode 100644
index 00000000..b10f2c27
--- /dev/null
+++ b/packages/provider-tokendance/src/mapping.ts
@@ -0,0 +1,60 @@
+import type { ModuleRef } from "@hypit/protocol";
+import type { GenerationWireMapping } from "@hypit/generation";
+
+const SEEDANCE: ModuleRef = { name: "@hypit/seedance", version: "1" };
+const SEEDREAM: ModuleRef = { name: "@hypit/seedream", version: "1" };
+const MINIMAX: ModuleRef = { name: "@hypit/minimax-h3", version: "1" };
+
+/**
+ * TokenDance model IDs and the request fields they accept. Media fields name the `role` of an Ark
+ * or MiniMax `content` item; routes.ts folds them into that array. `personReference` is accepted
+ * on visual references and not transmitted: neither protocol has a field for it.
+ */
+const seedance = (name: string, model: string): GenerationWireMapping => ({
+ capability: { module: SEEDANCE, name }, result: "video", routes: [{ model }],
+ fields: {
+ prompt: { as: "value", field: "text" },
+ referenceImage: { as: "urlArray", field: "reference_image", resourceFields: ["personReference"] },
+ referenceVideo: { as: "urlArray", field: "reference_video", resourceFields: ["personReference"] },
+ referenceAudio: { as: "urlArray", field: "reference_audio" },
+ firstFrame: { as: "url", field: "first_frame", resourceFields: ["personReference"] },
+ lastFrame: { as: "url", field: "last_frame", resourceFields: ["personReference"] },
+ resolution: { as: "value", field: "resolution" },
+ aspectRatio: { as: "value", field: "ratio" },
+ duration: { as: "value", field: "duration" },
+ generateAudio: { as: "value", field: "generate_audio" },
+ webSearch: { as: "value", field: "web_search" },
+ },
+});
+
+export const tokenDanceMappings: readonly GenerationWireMapping[] = [
+ seedance("seedance-2", "seedance-2.0"),
+ seedance("seedance-2-fast", "seedance-2.0-fast"),
+ seedance("seedance-2-mini", "seedance-2.0-mini"),
+ seedance("seedance-2.5", "seedance-2.5"),
+ {
+ capability: { module: SEEDREAM, name: "seedream-5-lite" }, result: "image", routes: [{ model: "seedream-5.0-lite" }],
+ fields: {
+ prompt: { as: "value", field: "prompt" },
+ aspectRatio: { as: "value", field: "aspect_ratio" },
+ quality: { as: "value", field: "quality" },
+ outputFormat: { as: "value", field: "output_format" },
+ nsfwCheck: { as: "value", field: "nsfw_check" },
+ images: { as: "urlArray", field: "image" },
+ },
+ },
+ {
+ capability: { module: MINIMAX, name: "minimax-h3" }, result: "video", routes: [{ model: "minimax-h3" }],
+ fields: {
+ prompt: { as: "value", field: "text" },
+ duration: { as: "value", field: "duration" },
+ resolution: { as: "value", field: "resolution", whenAbsent: "2K" },
+ aspectRatio: { as: "value", field: "ratio" },
+ 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" },
+ },
+ },
+];
diff --git a/packages/provider-tokendance/src/provider.ts b/packages/provider-tokendance/src/provider.ts
new file mode 100644
index 00000000..3fee0ca2
--- /dev/null
+++ b/packages/provider-tokendance/src/provider.ts
@@ -0,0 +1,268 @@
+import { requestDeadline } from "@hypit/runtime-kit";
+import type { AsyncEndpoint, EndpointCredential, EndpointInvocationContext, EndpointOutcome, ImmediateEndpointHandler } from "@hypit/endpoint-kit";
+import { defineEndpointPackage, wakeAfter } from "@hypit/endpoint-kit";
+import type { GenerationArtifactUrlResolver } from "@hypit/generation";
+import { canonicalize } from "@hypit/protocol";
+import type { BlobRef, CapabilityRef } from "@hypit/protocol";
+import { credentialRef } from "@hypit/runtime";
+import type { CredentialRef, ResourceStore } from "@hypit/runtime";
+import { tokenDanceRouteForCapability, tokenDanceRoutes } from "./routes.js";
+import type { TokenDanceRoute } from "./routes.js";
+import { TokenDanceHttpError, TokenDanceServiceError, tokenDanceTaskFailure } from "./errors.js";
+
+export const tokenDanceProviderModuleRef = { name: "@hypit/provider-tokendance", version: "1" } as const;
+
+export type CreateTokenDanceProviderOptions = {
+ readonly instance?: string;
+ readonly pool?: string;
+ readonly baseUrl?: string;
+ readonly apiKey?: CredentialRef;
+ readonly defaultConcurrency?: number;
+ readonly actionLimits?: import("@hypit/endpoint-kit").EndpointActionLimits;
+ readonly pollIntervalMs?: number;
+ readonly requestTimeoutMs?: number;
+ readonly operationTimeoutMs?: number;
+ readonly fetch?: typeof globalThis.fetch;
+ /** Publish a referenced Resource at a URL the service can fetch; replaces inline data URLs. */
+ readonly publicAssetUrl?: (artifact: BlobRef, artifacts: ResourceStore, fields?: Readonly<Record<string, string | number | boolean>>) => Promise<string>;
+};
+
+type Handle = {
+ readonly contract: "hypit.tokendance-operation@1";
+ readonly taskId: string;
+ readonly route: string;
+ readonly startedAt: number;
+ readonly url?: string;
+};
+
+function assert(condition: unknown, message: string): asserts condition { if (!condition) throw new Error(message); }
+function object(value: unknown, subject: string): Record<string, unknown> {
+ assert(value !== null && typeof value === "object" && !Array.isArray(value), `${subject} must be an object`);
+ return value as Record<string, unknown>;
+}
+function capabilityKey(capability: CapabilityRef): string { return `${capability.module.name}@${capability.module.version}#${capability.name}`; }
+function apiBaseUrl(value: string): string {
+ let trimmed = value.trim();
+ while (trimmed.endsWith("/")) trimmed = trimmed.slice(0, -1);
+ assert(trimmed.length > 0, "TokenDance base URL is empty");
+ return trimmed;
+}
+function apiKey(credentials: Readonly<Record<string, EndpointCredential>>): string {
+ const value = credentials.apiKey?.secret;
+ assert(typeof value === "string" && value.length > 0, "TokenDance apiKey credential is unavailable; store a TokenDance API key for this Endpoint");
+ return value;
+}
+function failureMessage(error: unknown): string {
+ return error instanceof Error ? error.message : String(error);
+}
+function failure(error: unknown): EndpointOutcome {
+ return { status: "failed", failure: { code: error instanceof TokenDanceServiceError ? error.code : "TOKENDANCE_ERROR", message: failureMessage(error) } };
+}
+function httpsUrl(value: unknown, subject: string): string {
+ assert(typeof value === "string" && /^https?:\/\//u.test(value), `${subject} has no download URL`);
+ return value;
+}
+
+class TokenDanceClient {
+ constructor(readonly baseUrl: string, readonly timeout: number, readonly fetcher: typeof globalThis.fetch) {}
+ async json(path: string, key: string, init: RequestInit = {}): Promise<Record<string, unknown>> {
+ const deadline = requestDeadline(this.timeout);
+ try {
+ const response = await deadline.wait(this.fetcher(`${this.baseUrl}${path}`, {
+ ...init, signal: deadline.signal, headers: { authorization: `Bearer ${key}`, ...(init.headers ?? {}) },
+ }));
+ const text = await deadline.wait(response.text());
+ if (!response.ok) {
+ const input = typeof init.body === "string" ? JSON.parse(init.body) as Record<string, unknown> : undefined;
+ throw new TokenDanceHttpError(response.status, response, text, {
+ method: init.method ?? "GET", path, ...(typeof input?.model === "string" ? { model: input.model } : {}),
+ });
+ }
+ let body: unknown;
+ try { body = text.length === 0 ? {} : JSON.parse(text); } catch { throw new Error(`TokenDance returned invalid JSON (${response.status})`); }
+ return object(body, "TokenDance response");
+ } finally { deadline.finish(); }
+ }
+ /** MiniMax's file API through the gateway; the returned id is referenced as `mm_file://{file_id}`. */
+ async uploadMiniMaxInput(bytes: Uint8Array, artifact: BlobRef, key: string): Promise<string> {
+ const form = new FormData();
+ form.set("purpose", "video_generation_input");
+ form.set("file", new Blob([new Uint8Array(bytes)], { type: artifact.mediaType }), `${artifact.resource}.${artifact.mediaType.split("/")[1] ?? "bin"}`);
+ const response = await this.json("/minimax/v1/files/upload", key, { method: "POST", body: form });
+ const status = object(response.base_resp ?? {}, "TokenDance upload base_resp").status_code;
+ assert(status === undefined || status === 0, `TokenDance MiniMax upload rejected: ${String(object(response.base_resp, "TokenDance upload base_resp").status_msg ?? status)}`);
+ const id = object(response.file, "TokenDance upload file").file_id;
+ assert((typeof id === "string" && id.length > 0) || typeof id === "number", "TokenDance MiniMax upload returned no file_id");
+ return `mm_file://${String(id)}`;
+ }
+ async download(url: string): Promise<{ readonly bytes: Uint8Array; readonly mediaType: string }> {
+ const deadline = requestDeadline(this.timeout);
+ try {
+ const response = await deadline.wait(this.fetcher(url, { signal: deadline.signal }));
+ if (!response.ok) throw new Error(`TokenDance asset returned HTTP ${response.status}`);
+ return { bytes: new Uint8Array(await deadline.wait(response.arrayBuffer())), mediaType: response.headers.get("content-type")?.split(";", 1)[0] ?? "application/octet-stream" };
+ } finally { deadline.finish(); }
+ }
+}
+
+function mediaKind(mediaType: string): "image" | "video" | "audio" | undefined {
+ const kind = mediaType.split("/", 1)[0];
+ return kind === "image" || kind === "video" || kind === "audio" ? kind : undefined;
+}
+
+function resolverFor(client: TokenDanceClient, route: TokenDanceRoute, context: EndpointInvocationContext, publicAssetUrl: CreateTokenDanceProviderOptions["publicAssetUrl"]): GenerationArtifactUrlResolver {
+ const resolved = new Map<string, Promise<string>>();
+ return (artifact, fields) => {
+ const existing = resolved.get(artifact.resource);
+ if (existing !== undefined) return existing;
+ const promise = (async () => {
+ if (publicAssetUrl !== undefined) return await publicAssetUrl(artifact, context.resources, fields);
+ const kind = mediaKind(artifact.mediaType);
+ const limit = kind === undefined ? undefined : route.mediaLimits[kind];
+ assert(limit !== undefined,
+ `TokenDance ${route.protocol} accepts ${artifact.mediaType} references only by public URL; configure publicAssetUrl for this Endpoint`);
+ assert(artifact.size <= limit,
+ `TokenDance ${route.protocol} accepts ${kind} references up to ${limit / 1_000_000} MB; ${artifact.resource} is ${artifact.size} bytes`);
+ const bytes = await context.resources.get(artifact.resource);
+ assert(bytes !== undefined && bytes.byteLength === artifact.size, `Reference Resource ${artifact.resource} is unavailable or has changed`);
+ if (route.protocol === "minimax-video") return await client.uploadMiniMaxInput(bytes, artifact, apiKey(context.credentials));
+ return `data:${artifact.mediaType};base64,${Buffer.from(bytes).toString("base64")}`;
+ })();
+ resolved.set(artifact.resource, promise);
+ return promise;
+ };
+}
+
+async function prepare(client: TokenDanceClient, context: EndpointInvocationContext, publicAssetUrl: CreateTokenDanceProviderOptions["publicAssetUrl"]) {
+ const route = tokenDanceRouteForCapability(context.need.capability);
+ assert(route !== undefined, "TokenDance does not implement this exact capability");
+ const request = route.prepare(context.need.constraints);
+ await context.reportProgress?.({ phase: `Preparing TokenDance request: ${request.model}` });
+ let body: string;
+ try {
+ body = JSON.stringify(await request.compile(resolverFor(client, route, context, publicAssetUrl)));
+ const cap = route.mediaLimits.body;
+ assert(cap === undefined || Buffer.byteLength(body) <= cap,
+ `TokenDance ${route.protocol} accepts request bodies up to ${(cap ?? 0) / 1_000_000} MB; inline references make this one ${Buffer.byteLength(body)} bytes`);
+ } catch (error) {
+ throw new TokenDanceServiceError(error instanceof TokenDanceServiceError ? error.code : "TOKENDANCE_ERROR",
+ `TokenDance request preparation failed; model=${request.model}; generation not submitted: ${failureMessage(error)}`);
+ }
+ return { route, model: request.model, body };
+}
+
+async function store(client: TokenDanceClient, urls: readonly string[], resources: ResourceStore): Promise<BlobRef[]> {
+ const blobs: BlobRef[] = [];
+ for (const url of urls) {
+ const downloaded = await client.download(url);
+ blobs.push(await resources.put(downloaded.bytes, downloaded.mediaType));
+ }
+ return blobs;
+}
+
+const paths = {
+ "ark-video": { submit: "/ark/v3/generations/tasks", task: (id: string) => `/ark/v3/generations/tasks/${encodeURIComponent(id)}` },
+ "minimax-video": { submit: "/minimax/v2/video_generation", task: (id: string) => `/minimax/v2/query/video_generation/${encodeURIComponent(id)}` },
+} as const;
+
+function taskId(protocol: keyof typeof paths, response: Record<string, unknown>): string {
+ const id = protocol === "ark-video" ? response.id : response.task_id;
+ assert(typeof id === "string" && id.length > 0, "TokenDance response has no task id");
+ return id;
+}
+
+/** Ark answers the task itself; MiniMax wraps it in `task`. */
+function taskBody(protocol: keyof typeof paths, response: Record<string, unknown>): Record<string, unknown> {
+ return protocol === "ark-video" ? response : object(response.task, "TokenDance task");
+}
+
+function taskVideoUrl(protocol: keyof typeof paths, task: Record<string, unknown>): string {
+ const content = object(task.content, "TokenDance task content");
+ return httpsUrl(protocol === "ark-video" ? content.video_url : content.url, "TokenDance task");
+}
+
+function endpoint(client: TokenDanceClient, pollIntervalMs: number, maxOperationMs: number, publicAssetUrl: CreateTokenDanceProviderOptions["publicAssetUrl"]): AsyncEndpoint {
+ return {
+ async start(context) {
+ try {
+ const { route, model, body } = await prepare(client, context, publicAssetUrl);
+ assert(route.protocol !== "ark-image", "TokenDance image capabilities use an immediate endpoint");
+ await context.reportProgress?.({ phase: `Submitting TokenDance request: ${model}` });
+ const response = await client.json(paths[route.protocol].submit, apiKey(context.credentials), {
+ method: "POST", headers: { "content-type": "application/json" }, body,
+ });
+ const handle: Handle = { contract: "hypit.tokendance-operation@1", taskId: taskId(route.protocol, response), route: route.key, startedAt: Date.now() };
+ const receipt = { id: handle.taskId };
+ await context.checkpoint?.({ handle: canonicalize(handle), receipt });
+ return { ...wakeAfter(canonicalize(handle), pollIntervalMs, Date.now(), { phase: "submitted" }), receipt };
+ } catch (error) {
+ return failure(error);
+ }
+ },
+ async poll(context) {
+ try {
+ const handle = object(context.handle, "TokenDance handle") as unknown as Handle;
+ const route = tokenDanceRouteForCapability(context.need.capability);
+ assert(route !== undefined && handle.contract === "hypit.tokendance-operation@1" && handle.route === route.key && route.protocol !== "ark-image", "TokenDance handle is invalid");
+ const receipt = { id: handle.taskId };
+ if (Date.now() - handle.startedAt > maxOperationMs) {
+ return { status: "failed", receipt, failure: { code: "TOKENDANCE_OPERATION_TIMEOUT", message: `TokenDance task ${handle.taskId} exceeded this Provider's operationTimeoutMs (${maxOperationMs}); remote outcome is unknown` } };
+ }
+ const task = taskBody(route.protocol, await client.json(paths[route.protocol].task(handle.taskId), apiKey(context.credentials)));
+ const status = String(task.status);
+ if (status === "queued" || status === "running") return { ...wakeAfter(canonicalize(handle), pollIntervalMs, Date.now(), { phase: status }), receipt };
+ const rejected = tokenDanceTaskFailure(task, handle.taskId);
+ if (rejected !== undefined) return { ...failure(rejected), receipt };
+ assert(status === "succeeded", `TokenDance returned unknown task status ${status}`);
+ return { status: "ready", handle: canonicalize({ ...handle, url: taskVideoUrl(route.protocol, task) }), receipt };
+ } catch (error) {
+ return failure(error);
+ }
+ },
+ async collect(context) {
+ try {
+ const handle = object(context.handle, "TokenDance handle") as unknown as Handle;
+ const route = tokenDanceRouteForCapability(context.need.capability);
+ assert(route !== undefined && handle.route === route.key, "TokenDance collection route differs");
+ await context.reportProgress?.({ phase: "Receiving generated video" });
+ const blobs = await store(client, [httpsUrl(handle.url, "TokenDance handle")], context.resources);
+ return { status: "completed", result: { value: route.packageResult(blobs) }, receipt: { id: handle.taskId } };
+ } catch (error) {
+ return failure(error);
+ }
+ },
+ };
+}
+
+export function createTokenDanceProvider(options: CreateTokenDanceProviderOptions = {}) {
+ const requestTimeoutMs = options.requestTimeoutMs ?? 300_000;
+ const operationTimeoutMs = options.operationTimeoutMs ?? 30 * 60_000;
+ for (const [name, value] of Object.entries({ requestTimeoutMs, operationTimeoutMs })) {
+ assert(Number.isSafeInteger(value) && value > 0, `TokenDance ${name} must be a positive integer`);
+ }
+ const client = new TokenDanceClient(apiBaseUrl(options.baseUrl ?? "https://tokendance.space/gateway"), requestTimeoutMs, options.fetch ?? globalThis.fetch);
+ const asyncEndpoint = endpoint(client, options.pollIntervalMs ?? 10_000, operationTimeoutMs, options.publicAssetUrl);
+ const imageEndpoint: ImmediateEndpointHandler = async (context) => {
+ const { route, model, body } = await prepare(client, context, options.publicAssetUrl);
+ assert(route.protocol === "ark-image", "TokenDance video capabilities use an asynchronous endpoint");
+ await context.reportProgress?.({ phase: `Submitting TokenDance request: ${model}` });
+ const response = await client.json("/ark/v3/images/generations", apiKey(context.credentials), {
+ method: "POST", headers: { "content-type": "application/json" }, body,
+ });
+ assert(Array.isArray(response.data) && response.data.length > 0, "TokenDance image response has no data");
+ const urls = response.data.map((item, index) => httpsUrl(object(item, `TokenDance image ${index + 1}`).url, `TokenDance image ${index + 1}`));
+ await context.reportProgress?.({ phase: "Receiving generated images" });
+ return { value: route.packageResult(await store(client, urls, context.resources)) };
+ };
+ return defineEndpointPackage({
+ module: tokenDanceProviderModuleRef, facet: "gateway", instance: options.instance ?? "tokendance.default", pool: options.pool ?? options.instance ?? "tokendance.default",
+ pricing: { kind: "page", url: "https://tokendance.space/models" },
+ credentials: { apiKey: options.apiKey ?? credentialRef("os", "tokendance.api-key") },
+ credentialInputs: { apiKey: { label: "TokenDance API key" } },
+ defaultConcurrency: options.defaultConcurrency ?? 4,
+ ...(options.actionLimits === undefined ? {} : { actionLimits: options.actionLimits }),
+ capabilities: tokenDanceRoutes.map((route) => route.protocol === "ark-image"
+ ? { capability: route.capability, returns: route.returns, lifecycle: "immediate" as const, handler: imageEndpoint, capacity: route.capability.name, supports: route.supports }
+ : { capability: route.capability, returns: route.returns, lifecycle: "asynchronous" as const, endpoint: asyncEndpoint, capacity: route.capability.name, supports: route.supports }),
+ });
+}
diff --git a/packages/provider-tokendance/src/routes.ts b/packages/provider-tokendance/src/routes.ts
new file mode 100644
index 00000000..5b0809a3
--- /dev/null
+++ b/packages/provider-tokendance/src/routes.ts
@@ -0,0 +1,192 @@
+import {
+ compileWireRequest,
+ selectWireModelForRequest,
+ generationTypes,
+ sealGeneratedImageSet,
+ sealGeneratedVideoSet,
+} from "@hypit/generation";
+import type { GenerationArtifactUrlResolver, GenerationRequest, GenerationWireMapping } 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 { tokenDanceMappings } from "./mapping.js";
+
+/** Which TokenDance protocol a capability submits through. */
+export type TokenDanceProtocol = "ark-video" | "ark-image" | "minimax-video";
+
+export type TokenDancePreparedRequest = {
+ readonly model: string;
+ readonly protocol: TokenDanceProtocol;
+ readonly compile: (resolve: GenerationArtifactUrlResolver) => Promise<Record<string, unknown>>;
+};
+
+/** Documented byte limits for one protocol's media inputs; an absent kind is not accepted inline. */
+export type TokenDanceMediaLimits = {
+ readonly image?: number;
+ readonly video?: number;
+ readonly audio?: number;
+ /** Documented cap on the whole JSON request body, when inline media count toward it. */
+ readonly body?: number;
+};
+
+const MB = 1_000_000;
+
+/**
+ * Ark: images under 30 MB and audio at most 15 MB may travel as Base64 within a 64 MB request body;
+ * videos take URLs only. MiniMax: every kind is uploaded through its file API within these sizes.
+ */
+export const tokenDanceMediaLimits: Readonly<Record<TokenDanceProtocol, TokenDanceMediaLimits>> = {
+ "ark-video": { image: 30 * MB, audio: 15 * MB, body: 64 * MB },
+ "ark-image": { image: 30 * MB },
+ "minimax-video": { image: 30 * MB, video: 50 * MB, audio: 15 * MB },
+};
+
+export type TokenDanceRoute = GenerationWireMapping & {
+ readonly key: string;
+ readonly returns: TypeRef;
+ readonly protocol: TokenDanceProtocol;
+ readonly mediaLimits: TokenDanceMediaLimits;
+ readonly supports: (request: EndpointRequest) => EndpointSupport;
+ readonly prepare: (constraints: CanonicalValue) => TokenDancePreparedRequest;
+ readonly packageResult: (artifacts: readonly BlobRef[]) => StoredValue;
+};
+
+function scalar(request: GenerationRequest, port: string): string | number | boolean | undefined {
+ const value = request.ports[port]?.[0];
+ return typeof value === "string" || typeof value === "number" || typeof value === "boolean" ? value : undefined;
+}
+function present(request: GenerationRequest, port: string): boolean {
+ return (request.ports[port]?.length ?? 0) > 0;
+}
+function strings(value: unknown): readonly string[] {
+ return Array.isArray(value) ? value.filter((item): item is string => typeof item === "string" && item.length > 0) : [];
+}
+
+/** Seedream 5.0 lite pixel sizes for each resolution tier and aspect ratio, from the Ark image API reference. */
+const SEEDREAM_SIZES: Readonly<Record<string, Readonly<Record<string, string>>>> = {
+ basic: { "1:1": "2048x2048", "4:3": "2304x1728", "3:4": "1728x2304", "16:9": "2848x1600", "9:16": "1600x2848", "3:2": "2496x1664", "2:3": "1664x2496", "21:9": "3136x1344" },
+ high: { "1:1": "3072x3072", "4:3": "3456x2592", "3:4": "2592x3456", "16:9": "4096x2304", "9:16": "2304x4096", "3:2": "3744x2496", "2:3": "2496x3744", "21:9": "4704x2016" },
+ ultra: { "1:1": "4096x4096", "4:3": "4704x3520", "3:4": "3520x4704", "16:9": "5504x3040", "9:16": "3040x5504", "3:2": "4992x3328", "2:3": "3328x4992", "21:9": "6240x2656" },
+};
+
+function rejection(mapping: GenerationWireMapping, request: GenerationRequest): string | undefined {
+ const ratio = scalar(request, "aspectRatio");
+ if (mapping.capability.module.name === "@hypit/seedance") {
+ if (mapping.capability.name === "seedance-2.5" && present(request, "firstFrame") && ratio !== "adaptive") {
+ return `Seedance 2.5 frame mode on TokenDance takes only aspect-ratio adaptive, not ${String(ratio)}`;
+ }
+ return undefined;
+ }
+ if (mapping.capability.module.name === "@hypit/seedream") {
+ const quality = String(scalar(request, "quality"));
+ if (SEEDREAM_SIZES[quality]?.[String(ratio)] === undefined) {
+ return `TokenDance Seedream 5.0 lite has no size for quality ${quality} at ${String(ratio)}`;
+ }
+ return undefined;
+ }
+ if (mapping.capability.module.name === "@hypit/minimax-h3") {
+ const hasMedia = ["referenceImage", "referenceVideo", "referenceAudio", "firstFrame", "lastFrame"]
+ .some((port) => present(request, port));
+ if (!hasMedia && (ratio === undefined || ratio === "adaptive")) {
+ return "MiniMax H3 text-to-video on TokenDance requires an explicit aspect-ratio";
+ }
+ }
+ return undefined;
+}
+
+function contentItem(type: "image_url" | "video_url" | "audio_url", url: string, role: string) {
+ return { type, [type]: { url }, role };
+}
+
+/** Ark and MiniMax both take one `content` array of typed, role-tagged items. */
+function contentArray(input: Record<string, unknown>) {
+ const first = input.first_frame;
+ const last = input.last_frame;
+ return [
+ { type: "text", text: input.text },
+ ...(typeof first === "string" ? [contentItem("image_url", first, "first_frame")] : []),
+ ...(typeof last === "string" ? [contentItem("image_url", last, "last_frame")] : []),
+ ...strings(input.reference_image).map((url) => contentItem("image_url", url, "reference_image")),
+ ...strings(input.reference_video).map((url) => contentItem("video_url", url, "reference_video")),
+ ...strings(input.reference_audio).map((url) => contentItem("audio_url", url, "reference_audio")),
+ ];
+}
+
+function arkVideoBody(model: string, input: Record<string, unknown>): Record<string, unknown> {
+ return {
+ model,
+ content: contentArray(input),
+ resolution: input.resolution,
+ ratio: input.ratio,
+ duration: input.duration,
+ generate_audio: input.generate_audio,
+ ...(input.web_search === true ? { tools: [{ type: "web_search" }] } : {}),
+ };
+}
+
+function arkImageBody(model: string, input: Record<string, unknown>): Record<string, unknown> {
+ const images = strings(input.image);
+ return {
+ model,
+ prompt: input.prompt,
+ ...(images.length === 1 ? { image: images[0] } : images.length > 1 ? { image: images } : {}),
+ size: SEEDREAM_SIZES[String(input.quality)]![String(input.aspect_ratio)]!,
+ output_format: input.output_format,
+ response_format: "url",
+ watermark: false,
+ };
+}
+
+function minimaxVideoBody(model: string, input: Record<string, unknown>): Record<string, unknown> {
+ return {
+ model,
+ content: contentArray(input),
+ resolution: input.resolution,
+ duration: input.duration,
+ ...(typeof input.ratio === "string" ? { ratio: input.ratio } : {}),
+ };
+}
+
+function capabilityKey(capability: CapabilityRef): string {
+ return `${capability.module.name}@${capability.module.version}#${capability.name}`;
+}
+
+export const tokenDanceRoutes: readonly TokenDanceRoute[] = tokenDanceMappings.map((mapping) => {
+ const protocol: TokenDanceProtocol = mapping.capability.module.name === "@hypit/minimax-h3" ? "minimax-video"
+ : mapping.result === "image" ? "ark-image" : "ark-video";
+ const body = protocol === "ark-video" ? arkVideoBody : protocol === "ark-image" ? arkImageBody : minimaxVideoBody;
+ return {
+ ...mapping,
+ key: capabilityKey(mapping.capability),
+ returns: mapping.result === "image" ? generationTypes.imageSet : generationTypes.videoSet,
+ protocol,
+ mediaLimits: tokenDanceMediaLimits[protocol],
+ supports: (request) => {
+ const reason = rejection(mapping, request.constraints as unknown as GenerationRequest);
+ return reason === undefined ? { status: "supported" } : { status: "unsupported", reason };
+ },
+ prepare: (constraints) => {
+ const request = constraints as unknown as GenerationRequest;
+ const reason = rejection(mapping, request);
+ if (reason !== undefined) throw new Error(reason);
+ const model = selectWireModelForRequest(mapping, request);
+ return {
+ model,
+ protocol,
+ compile: async (resolve) => body(model, (await compileWireRequest(mapping, request, resolve)).input as Record<string, unknown>),
+ };
+ },
+ packageResult: (artifacts) => ({
+ kind: "inline",
+ value: canonicalize(mapping.result === "image"
+ ? sealGeneratedImageSet({ images: artifacts })
+ : sealGeneratedVideoSet({ videos: artifacts })),
+ }),
+ };
+});
+
+const byCapability = new Map(tokenDanceRoutes.map((route) => [route.key, route]));
+
+export function tokenDanceRouteForCapability(capability: CapabilityRef): TokenDanceRoute | undefined {
+ return byCapability.get(capabilityKey(capability));
+}
diff --git a/packages/provider-tokendance/test/routes.test.ts b/packages/provider-tokendance/test/routes.test.ts
new file mode 100644
index 00000000..eee5fbca
--- /dev/null
+++ b/packages/provider-tokendance/test/routes.test.ts
@@ -0,0 +1,55 @@
+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 { seedream5LitePorts, sealSeedreamRequest } from "@hypit/seedream";
+
+import { tokenDanceMappings } from "../src/mapping.js";
+import { tokenDanceRouteForCapability } from "../src/routes.js";
+
+const image: BlobRef = { kind: "blob", resource: "res_td_1", size: 3, mediaType: "image/png" };
+const resolve = async () => "data:image/png;base64,AQID";
+const SEEDANCE = { name: "@hypit/seedance", version: "1" };
+const route = (module: { name: string; version: string }, name: string) => tokenDanceRouteForCapability({ module, name })!;
+
+test("every TokenDance mapping covers its model's ports", () => {
+ const tables = { ...seedancePorts, "seedream-5-lite": seedream5LitePorts, "minimax-h3": minimaxH3Ports };
+ for (const mapping of tokenDanceMappings) {
+ assertMappingCoversPorts(tables[mapping.capability.name as keyof typeof tables], mapping);
+ }
+});
+
+test("Seedance frame requests become Ark content items with roles", async () => {
+ const request = sealSeedanceRequest("seedance-2-mini", {
+ prompt: ["turn"], firstFrame: [{ role: "image", artifact: image, fields: { personReference: true } }],
+ resolution: ["720p"], aspectRatio: ["adaptive"], duration: [5], generateAudio: [true], webSearch: [false],
+ });
+ const body = await route(SEEDANCE, "seedance-2-mini").prepare(request as unknown as CanonicalValue).compile(resolve);
+ assert.deepEqual(body, {
+ model: "seedance-2.0-mini",
+ content: [
+ { type: "text", text: "turn" },
+ { type: "image_url", image_url: { url: "data:image/png;base64,AQID" }, role: "first_frame" },
+ ],
+ resolution: "720p", ratio: "adaptive", duration: 5, generate_audio: true,
+ });
+});
+
+test("Seedream quality and ratio select the Ark pixel size", async () => {
+ const request = sealSeedreamRequest({
+ prompt: ["a cup"], aspectRatio: ["9:16"], quality: ["ultra"], outputFormat: ["png"], nsfwCheck: [true],
+ });
+ const body = await route({ name: "@hypit/seedream", version: "1" }, "seedream-5-lite").prepare(request as unknown as CanonicalValue).compile(resolve);
+ assert.deepEqual(body, {
+ model: "seedream-5.0-lite", prompt: "a cup", size: "3040x5504", output_format: "png", response_format: "url", watermark: false,
+ });
+});
+
+test("MiniMax text-to-video without an aspect ratio is reported unsupported", () => {
+ const request = sealMinimaxH3Request({ prompt: ["a kite"], duration: [5] });
+ const minimax = route({ name: "@hypit/minimax-h3", version: "1" }, "minimax-h3");
+ const support = minimax.supports({ capability: minimax.capability, returns: minimax.returns, constraints: request as unknown as CanonicalValue });
+ assert.equal(support.status, "unsupported");
+});
diff --git a/packages/video-cli/package.json b/packages/video-cli/package.json
index e9c407e4..54c45b2f 100644
--- a/packages/video-cli/package.json
+++ b/packages/video-cli/package.json
@@ -23,7 +23,11 @@
"@hypit/package-loader-node": "workspace:*",
"@hypit/project-context-node": "workspace:*",
"@hypit/protocol": "workspace:*",
+ "@hypit/provider-hiapi": "workspace:*",
"@hypit/provider-hypihub": "workspace:*",
+ "@hypit/provider-monid": "workspace:*",
+ "@hypit/provider-pollo": "workspace:*",
+ "@hypit/provider-tokendance": "workspace:*",
"@hypit/runtime": "workspace:*",
"@hypit/runtime-kit": "workspace:*",
"@hypit/runtime-host-node": "workspace:*",
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index aecd89af..9ee15624 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -183,6 +183,9 @@ importers:
'@hypit/protocol':
specifier: workspace:*
version: link:packages/protocol
+ '@hypit/provider-hiapi':
+ specifier: workspace:*
+ version: link:packages/provider-hiapi
'@hypit/provider-hyperframes-local':
specifier: workspace:*
version: link:packages/provider-hyperframes-local
@@ -195,6 +198,15 @@ importers:
'@hypit/provider-media-local':
specifier: workspace:*
version: link:packages/provider-media-local
+ '@hypit/provider-monid':
+ specifier: workspace:*
+ version: link:packages/provider-monid
+ '@hypit/provider-pollo':
+ specifier: workspace:*
+ version: link:packages/provider-pollo
+ '@hypit/provider-tokendance':
+ specifier: workspace:*
+ version: link:packages/provider-tokendance
'@hypit/provider-whisperx-local':
specifier: workspace:*
version: link:packages/provider-whisperx-local
@@ -2206,6 +2218,43 @@ importers:
packages/protocol: {}
+ packages/provider-hiapi:
+ dependencies:
+ '@hypit/endpoint-kit':
+ specifier: workspace:*
+ version: link:../endpoint-kit
+ '@hypit/generation':
+ specifier: workspace:*
+ version: link:../generation
+ '@hypit/protocol':
+ specifier: workspace:*
+ version: link:../protocol
+ '@hypit/runtime':
+ specifier: workspace:*
+ version: link:../runtime
+ '@hypit/runtime-kit':
+ specifier: workspace:*
+ version: link:../runtime-kit
+ devDependencies:
+ '@hypit/gpt-image':
+ specifier: workspace:*
+ version: link:../gpt-image
+ '@hypit/grok-imagine':
+ specifier: workspace:*
+ version: link:../grok-imagine
+ '@hypit/minimax-h3':
+ specifier: workspace:*
+ version: link:../minimax-h3
+ '@hypit/nano-banana':
+ specifier: workspace:*
+ version: link:../nano-banana
+ '@hypit/seedance':
+ specifier: workspace:*
+ version: link:../seedance
+ '@hypit/seedream':
+ specifier: workspace:*
+ version: link:../seedream
+
packages/provider-hyperframes-local:
dependencies:
'@hyperframes/engine':
@@ -2378,6 +2427,87 @@ importers:
specifier: workspace:*
version: link:../driver-node
+ packages/provider-monid:
+ dependencies:
+ '@hypit/endpoint-kit':
+ specifier: workspace:*
+ version: link:../endpoint-kit
+ '@hypit/generation':
+ specifier: workspace:*
+ version: link:../generation
+ '@hypit/protocol':
+ specifier: workspace:*
+ version: link:../protocol
+ '@hypit/runtime':
+ specifier: workspace:*
+ version: link:../runtime
+ '@hypit/runtime-kit':
+ specifier: workspace:*
+ version: link:../runtime-kit
+ devDependencies:
+ '@hypit/seedance':
+ specifier: workspace:*
+ version: link:../seedance
+
+ packages/provider-pollo:
+ dependencies:
+ '@hypit/endpoint-kit':
+ specifier: workspace:*
+ version: link:../endpoint-kit
+ '@hypit/generation':
+ specifier: workspace:*
+ version: link:../generation
+ '@hypit/protocol':
+ specifier: workspace:*
+ version: link:../protocol
+ '@hypit/runtime':
+ specifier: workspace:*
+ version: link:../runtime
+ '@hypit/runtime-kit':
+ specifier: workspace:*
+ version: link:../runtime-kit
+ devDependencies:
+ '@hypit/gpt-image':
+ specifier: workspace:*
+ version: link:../gpt-image
+ '@hypit/grok-imagine':
+ specifier: workspace:*
+ version: link:../grok-imagine
+ '@hypit/minimax-h3':
+ specifier: workspace:*
+ version: link:../minimax-h3
+ '@hypit/nano-banana':
+ specifier: workspace:*
+ version: link:../nano-banana
+
+ packages/provider-tokendance:
+ dependencies:
+ '@hypit/endpoint-kit':
+ specifier: workspace:*
+ version: link:../endpoint-kit
+ '@hypit/generation':
+ specifier: workspace:*
+ version: link:../generation
+ '@hypit/protocol':
+ specifier: workspace:*
+ version: link:../protocol
+ '@hypit/runtime':
+ specifier: workspace:*
+ version: link:../runtime
+ '@hypit/runtime-kit':
+ specifier: workspace:*
+ version: link:../runtime-kit
+ devDependencies:
+ '@hypit/minimax-h3':
+ specifier: workspace:*
+ version: link:../minimax-h3
+ '@hypit/seedance':
+ specifier: workspace:*
+ version: link:../seedance
+ '@hypit/seedream':
+ specifier: workspace:*
+ version: link:../seedream
+
packages/provider-whisperx-local:
dependencies:
'@hypit/endpoint-kit':
@@ -3436,9 +3566,21 @@ importers:
'@hypit/protocol':
specifier: workspace:*
version: link:../protocol
+ '@hypit/provider-hiapi':
+ specifier: workspace:*
+ version: link:../provider-hiapi
'@hypit/provider-hypihub':
specifier: workspace:*
version: link:../provider-hypihub
+ '@hypit/provider-monid':
+ specifier: workspace:*
+ version: link:../provider-monid
+ '@hypit/provider-pollo':
+ specifier: workspace:*
+ version: link:../provider-pollo
+ '@hypit/provider-tokendance':
+ specifier: workspace:*
+ version: link:../provider-tokendance
'@hypit/runtime':
specifier: workspace:*
version: link:../runtime
diff --git a/skills/hypit/references/environment/model-and-provider.md b/skills/hypit/references/environment/model-and-provider.md
index 51ef8ae5..7756eb76 100644
--- a/skills/hypit/references/environment/model-and-provider.md
+++ b/skills/hypit/references/environment/model-and-provider.md
@@ -97,7 +97,7 @@ Model and Provider extension or a release containing them. A missing model or un
is a capability question, while an expired credential is an account question.
A user's existing service or deployment remains a normal choice. Its Provider does not need to be
-officially bundled. When an execution-service choice remains open, the maintained
+officially bundled. When the user names a partner service, the maintained
[model and deployment service page](https://github.com/hypit-ai/hypit/blob/main/docs/guide/service-partners.md)
introduces independent partners and links their own documentation. Use an introduction when its
capabilities help this production. Partners have their own accounts, pricing and APIs and use the
diff --git a/skills/hypit/references/environment/profile.md b/skills/hypit/references/environment/profile.md
index e7e17db7..f124aef6 100644
--- a/skills/hypit/references/environment/profile.md
+++ b/skills/hypit/references/environment/profile.md
@@ -66,7 +66,10 @@ describe availability; the user's request and recorded choices establish what to
When the path is undecided, share the practical alternatives and your recommendation before a new
account connection, substantial installation or paid call. Ask for the choice that is actually
-unresolved. Once the route is agreed, carry out ordinary setup and work with progress updates.
+unresolved: the recommended HypiHub, which continues this flow unchanged, or a partner API, which
+the user picks from [this page](https://github.com/hypit-ai/hypit/blob/main/docs/guide/service-partners.md)
+([中文](https://github.com/hypit-ai/hypit/blob/main/docs/zh/guide/service-partners.md)) without a list from you.
+Once the route is agreed, carry out ordinary setup and work with progress updates.
Their decision can cover preparation as a whole. Record it in
[Brief](../creation/brief.md#brief-preserves-user-authority); the Profile implements that choice.
[Paid scope](../production/builds.md#work-within-the-agreed-paid-scope) explains how the commission