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(examples): add a project video Provider to the extension example (#250)

panxyingyyi02b37f0d0262
diff --git a/docs/guide/providers.md b/docs/guide/providers.md
index 66beffd9..7495c357 100644
--- a/docs/guide/providers.md
+++ b/docs/guide/providers.md
@@ -91,7 +91,36 @@ under `endpoints` and select it in `bindings` in the [Runtime Profile](./runtime
The [complete project Provider example](https://github.com/hypit-ai/hypit/tree/main/examples/provider-package)
demonstrates reference uploads, task receipts, collection and pricing using an illustrative API.
-It also ships with the executable, so the Agent can adapt it without a repository checkout.
+It also ships with the executable, so the Agent can adapt it without a repository checkout. It holds
+two packages: `provider-images` for a generated image, and `provider-videos` for a generated video
+whose service receives the wider reference vocabulary — images, videos, audio and first/last frames —
+and returns its result through a separate collection step.
+
+Implement the capability that matches your service's request shape; a service that renders both
+images and video can declare both capabilities in one package. A service often supports a narrower
+range than the Model's vocabulary allows, such as fewer resolutions or a lower maximum duration.
+That difference belongs to the Provider: report it from the capability's `supports` so `plan` refuses
+the request with a reason, rather than editing the shared Model or silently narrowing the author's
+request.
+
+## Model a remote video task
+
+A service that renders video usually submits a job, polls it and then downloads the result, which
+the Endpoint SDK expresses as three separate actions:
+
+- `start` submits the request and returns `pending` with the service's task id. The HTTP bound covers
+ the API call, not the render, so `start` returns as soon as the service accepts the job. Record the
+ task id through `checkpoint` before returning, so an interrupted Build still names the remote work
+ it began.
+- `poll` returns `pending` while the job runs, `ready` when it finishes, or `failed` with the
+ service's own error code. Return `wakeAfter(handle, delayMs)` to schedule the next check.
+- `collect` downloads the finished media and stores it through `context.resources`, returning the
+ Model's declared result value. Keeping collection separate from polling lets download capacity be
+ configured independently of task capacity.
+
+Inputs whose bytes do not exist until an upstream step runs stay ordinary graph edges. The URL
+resolver passed to `compileWireRequest` is where your Provider uploads a reference and returns the
+service's URL for it, so no other part of the system learns the service's upload protocol.
## Prices and permission
diff --git a/docs/zh/guide/providers.md b/docs/zh/guide/providers.md
index 5dc0a14d..cbdf75c7 100644
--- a/docs/zh/guide/providers.md
+++ b/docs/zh/guide/providers.md
@@ -57,7 +57,19 @@ import type { AsyncEndpoint, CredentialRef, EndpointRequest } from "@hypit/hypit
[Endpoint SDK](https://github.com/hypit-ai/hypit/blob/main/packages/endpoint-kit/README.md) 维护处理接口、activation、资源声明和价格 API。将包编译为 JavaScript,由项目包管理器安装。在 [Runtime Profile](./runtime.md) 的 `endpoints` 中配置实例,并通过 `bindings` 选择它。
-[完整项目 Provider 示例](https://github.com/hypit-ai/hypit/tree/main/examples/provider-package) 使用示意 API 展示参考上传、任务回执、结果收集与价格读取。示例随执行包分发,Agent 无需仓库 checkout 就能读取和改写。
+[完整项目 Provider 示例](https://github.com/hypit-ai/hypit/tree/main/examples/provider-package) 使用示意 API 展示参考上传、任务回执、结果收集与价格读取。示例随执行包分发,Agent 无需仓库 checkout 就能读取和改写。它包含两个包:`provider-images` 对应生成图像,`provider-videos` 对应生成视频——后者的服务接收更宽的参考词汇(图像、视频、音频以及首尾帧),并通过独立的结果收集步骤返回产物。
+
+实现与服务请求形态相匹配的那个 Capability;同时生成图像和视频的服务可以在同一个包里声明两个 Capability。服务实际支持的范围常常比 Model 词汇表更窄,例如分辨率更少或最长时长更低。这个差异属于 Provider:在 Capability 的 `supports` 中报告它,让 `plan` 带原因拒绝请求,而不是修改共享 Model 或悄悄收窄作者的请求。
+
+## 为远程视频任务建模
+
+渲染视频的服务通常先提交任务、再轮询、最后下载结果,Endpoint SDK 将其表达为三个独立动作:
+
+- `start` 提交请求并以该服务的任务 id 返回 `pending`。HTTP 超时约束的是这次 API 调用而非渲染本身,因此 `start` 在服务受理任务后立即返回。返回前通过 `checkpoint` 记录任务 id,这样即使 Build 被中断,也能指出它已发起的远程工作。
+- `poll` 在任务运行期间返回 `pending`,完成时返回 `ready`,失败时带服务自身的错误码返回 `failed`。用 `wakeAfter(handle, delayMs)` 安排下一次检查。
+- `collect` 下载已完成的素材,通过 `context.resources` 存储,并返回 Model 声明的结果值。把收集与轮询分离,可以让下载并发与任务并发分别配置。
+
+字节尚不存在、要等上游步骤产出的输入,仍是普通图边。`compileWireRequest` 接收的 URL resolver 就是 Provider 上传参考并返回服务 URL 的位置,系统的其他部分因此无需了解该服务的上传协议。
## 价格与授权
diff --git a/examples/provider-package/README.md b/examples/provider-package/README.md
index 19afa7f3..99ae5cea 100644
--- a/examples/provider-package/README.md
+++ b/examples/provider-package/README.md
@@ -1,10 +1,23 @@
# A project-owned Provider
-This complete package demonstrates an asynchronous image service through the public Hypit SDK.
-The service protocol below is **illustrative**, not a live vendor API. Replace its mapping and
-transport with the selected service's documented operations. The lifecycle test exercises the
-example without a paid request. Implement the capabilities needed by the production; a service's
-entire catalogue is not required.
+This example shows a service that Hypit's official Distribution does not ship, implemented as a
+project package through the public Hypit SDK. Two packages cover the two request shapes a service
+usually differs on:
+
+| Package | Model | Request | Lifecycle |
+| --- | --- | --- | --- |
+| `packages/provider-images` | `@hypit/gpt-image@1#gpt-image-2` | one image, optional references | asynchronous |
+| `packages/provider-videos` | `@hypit/seedance@1#seedance-2-mini` | one video, references and frames | asynchronous |
+
+Both service protocols are **illustrative**, not live vendor APIs. Replace the mapping and transport
+with the selected service's documented operations. The lifecycle tests exercise the examples without
+a paid request. Implement the capabilities needed by the production; a service's entire catalogue is
+not required.
+
+The video example is the one to read when the service renders **video**. A video request carries the
+whole reference vocabulary — images, videos, audio and first/last frames — and the result is a large
+remote task rather than a returned file. This is the shape most third-party video services use, and
+the shape the official Distribution cannot supply for a service it does not know.
## Follow one request
@@ -46,25 +59,84 @@ does not claim remote cancellation.
source and preserves the response with a concise description. It reads no graph and invents no
future media duration. Rates and credentials do not supply spending permission.
+## Follow a video request
+
+A Seedance request reaches `@hypit/seedance@1#seedance-2-mini` and returns a generated video-set.
+The Model declares the request; this Provider decides how the service receives it. Four things
+differ from the image example, and each is the reason the video example exists.
+
+**The reference vocabulary is wider, and each role maps to its own field.** The Model declares
+`referenceImage`, `referenceVideo` and `referenceAudio` as separate ports precisely so each can map
+to one wire field — a service that mixes them into one array cannot tell the roles apart. An image
+reference also carries an optional `personReference` classification, which is why those ports use
+`itemObject` rather than `urlArray`: the item field travels with the URL it belongs to.
+
+```json
+{ "references": [{ "url": "https://…/reference.png", "person": true }] }
+```
+
+`firstFrame` and `lastFrame` accept at most one item each, so their body fields are URLs.
+This illustrative service accepts their optional person classification on `POST /uploads` through
+`x-person-reference: true` or `false`. Their mappings declare `resourceFields: ["personReference"]`,
+and the URL resolver sends that header when supplied. Replace this with the real service’s
+documented transport; a field that the service cannot carry must be refused, never discarded.
+
+**The service's range is narrower than the Model's, and the Provider states that.** Seedance 2 Mini
+admits 480p/720p and 4–15 seconds; this illustrative service renders 720p up to 10 seconds. The
+Model is not edited for that. `supports` reports the difference before submission, so `plan` refuses
+the request with a reason instead of failing a paid job downstream:
+
+```
+This service renders at most 10 seconds, not 12
+```
+
+Do not widen the Model to fit one service. Do not silently clamp the author's number either — the
+author wrote 12 seconds, and a 10-second result is a different video.
+
+**Submission is an enqueue, not the render.** `start` returns as soon as the service acknowledges a
+task, and the HTTP bound covers the API call, not the minutes the render may take. `poll` returns
+`pending` while the task is `queued` or `running`, and the task id is checkpointed before `start`
+returns, so an interrupted Build still names the remote work it began.
+
+**The result is fetched in a separate `collect` step.** A finished task carries a signed URL; the
+account key goes only to the service's own API. `collect` downloads the media, stores it through
+`context.resources` and returns the Model's declared value. Because `poll` and `collect` are
+separate actions, download capacity is configured independently of task capacity.
+
+A task that reports `succeeded` without an output URL is a service contract violation, not a pending
+job, and fails loudly. A `failed` task keeps the service's own error code and the received task id
+as evidence, and redacts URLs from the message it republishes.
+
+`assertMappingCoversPorts` checks declared ports and required item fields. Optional fields need
+request-level checks and transport tests as well:
+a mapping that forgets a reference role or an item field fails at load rather than after a paid
+generation returns the wrong video. Where a Model port is genuinely optional, `whenAbsent` states
+what the service should receive when the author omits it — the service then gets the value the
+author's request implies, not a field left to its own default. The lifecycle test asserts the
+mapping against the Model's own port table.
+
## Make it a package in the production
-Copy `packages/provider-images` into the video's `packages/`. Choose your own package name and change
-`providerModule.name` with it. Implement the actual service protocol, including its request limits,
-upload/download limits and any OAuth or cancellation behavior it really offers. Configure the
-selected service address; `images.example` is a placeholder that cannot generate media.
+Copy the package matching your service's request shape — `packages/provider-images` or
+`packages/provider-videos` — into the video's `packages/`. Choose your own package name and change
+`providerModule.name` with it. A service that renders both images and video can implement both
+capabilities in one package; `defineEndpointPackage` accepts several. Implement the actual service
+protocol, including its request limits, upload/download limits and any OAuth or cancellation
+behavior it really offers. Configure the selected service address; `images.example` and
+`videos.example` are placeholders that cannot generate media.
Use the active `@hypit/hypit` version as a development dependency. Build and install with the
-project's package manager. In this repository the example uses `workspace:*` for that dependency;
-replace it with your selected release when copying it out. The `@hypit/driver-node` and
-`@hypit/gpt-image` development dependencies serve the repository test only and can be removed from
-the copied package. For example:
+project's package manager. In this repository the examples use `workspace:*` for that dependency;
+replace it with your selected release when copying it out. The `@hypit/driver-node` and model
+development dependencies (`@hypit/gpt-image`, `@hypit/seedance`) serve the repository tests only and
+can be removed from the copied package. For example:
```bash
-cd packages/provider-images
+cd packages/provider-videos
npm install
npm run build
cd ../..
-npm install ./packages/provider-images
+npm install ./packages/provider-videos
```
The package ships JavaScript. Its `hypit.activation` exports a Profile-selected Runtime facet;
@@ -73,10 +145,14 @@ loading project packages. Keep the chosen package version and lockfile with the
Merge the endpoint, credential store and binding from `hypit.runtime.json` into the project's
chosen Profile. Preserve its other services and resolve bindings explicitly. Once the user chooses
-that account, `hypit auth login images.personal` securely enters the key into its declared store.
+that account, `hypit auth login videos.personal` securely enters the key into its declared store.
`plan` checks the requested parameters; `pricing` supplies the service's rates. Submitting a real
generation follows the agreed production scope and spending authority.
+The service decides whether an Endpoint needs its own credential slot at all. A service that
+authenticates through the platform it runs on, or one reached at a private address, may declare no
+credentials or a non-secret account name; `defineEndpointPackage` takes whichever the service has.
+
## Owners
- `src/provider.ts`: exact capability, mapping, service support, task lifecycle, pricing and capacity.
diff --git a/examples/provider-package/hypit.runtime.json b/examples/provider-package/hypit.runtime.json
index c414c7c1..7fbbf88d 100644
--- a/examples/provider-package/hypit.runtime.json
+++ b/examples/provider-package/hypit.runtime.json
@@ -6,7 +6,14 @@
"images.personal": {
"use": "@example/provider-images",
"config": { "baseUrl": "https://images.example", "apiKey": { "store": "platform", "key": "images.personal" } }
+ },
+ "videos.personal": {
+ "use": "@example/provider-videos",
+ "config": { "baseUrl": "https://videos.example", "apiKey": { "store": "platform", "key": "videos.personal" } }
}
},
- "bindings": { "@hypit/gpt-image@1#gpt-image-2": "images.personal" }
+ "bindings": {
+ "@hypit/gpt-image@1#gpt-image-2": "images.personal",
+ "@hypit/seedance@1#seedance-2-mini": "videos.personal"
+ }
}
diff --git a/examples/provider-package/packages/provider-videos/package.json b/examples/provider-package/packages/provider-videos/package.json
new file mode 100644
index 00000000..1020edf2
--- /dev/null
+++ b/examples/provider-package/packages/provider-videos/package.json
@@ -0,0 +1,11 @@
+{
+ "name": "@example/provider-videos",
+ "version": "0.0.0",
+ "private": true,
+ "type": "module",
+ "hypit": { "activation": "./dist/activation.js" },
+ "exports": { ".": "./dist/provider.js" },
+ "files": ["dist"],
+ "scripts": { "build": "tsc -p tsconfig.json" },
+ "devDependencies": { "@hypit/hypit": "workspace:*", "typescript": "5.9.3", "@hypit/driver-node": "workspace:*", "@hypit/seedance": "workspace:*" }
+}
diff --git a/examples/provider-package/packages/provider-videos/src/activation.ts b/examples/provider-package/packages/provider-videos/src/activation.ts
new file mode 100644
index 00000000..d236fac6
--- /dev/null
+++ b/examples/provider-package/packages/provider-videos/src/activation.ts
@@ -0,0 +1,24 @@
+import {
+ createRuntimeEndpointAdapterFacet, runtimeConfigCredentialRef, runtimeConfigExact,
+ runtimeConfigObject, runtimeConfigPositiveInteger, runtimeConfigString,
+} from "@hypit/hypit/runtime-kit";
+import { createVideoProvider, providerModule } from "./provider.js";
+
+export default {
+ format: "hypit.node-package@1" as const,
+ hostFacets: [createRuntimeEndpointAdapterFacet({
+ use: providerModule.name,
+ activate(context) {
+ const config = runtimeConfigObject(context.config, "Video service");
+ runtimeConfigExact(config, ["baseUrl", "apiKey", "concurrency", "pollIntervalMs"], "Video service");
+ const baseUrl = runtimeConfigString(config.baseUrl, "Video service baseUrl");
+ const apiKey = runtimeConfigCredentialRef(config.apiKey, "Video service apiKey");
+ if (!baseUrl || !apiKey || !context.pool) throw new Error("Video service requires baseUrl, apiKey and pool");
+ return { endpoint: createVideoProvider({
+ instance: context.instance, pool: context.pool, baseUrl, apiKey,
+ concurrency: runtimeConfigPositiveInteger(config.concurrency, "concurrency") ?? 1,
+ pollIntervalMs: runtimeConfigPositiveInteger(config.pollIntervalMs, "pollIntervalMs") ?? 5_000,
+ }) };
+ },
+ })],
+};
diff --git a/examples/provider-package/packages/provider-videos/src/provider.ts b/examples/provider-package/packages/provider-videos/src/provider.ts
new file mode 100644
index 00000000..daf58742
--- /dev/null
+++ b/examples/provider-package/packages/provider-videos/src/provider.ts
@@ -0,0 +1,181 @@
+import { canonicalize, defineEndpointPackage, wakeAfter } from "@hypit/hypit/endpoint-kit";
+import type { AsyncEndpoint, CredentialRef, EndpointRequest } from "@hypit/hypit/endpoint-kit";
+import {
+ compileWireRequest, generationTypes, mappingSupportsRequest,
+ sealGeneratedVideoSet, selectWireModelForRequest,
+} from "@hypit/hypit/generation";
+import type { GenerationRequest, GenerationWireMapping } from "@hypit/hypit/generation";
+
+export const providerModule = { name: "@example/provider-videos", version: "1" } as const;
+export const capability = { module: { name: "@hypit/seedance", version: "1" }, name: "seedance-2-mini" } as const;
+
+// This example service implements only this subset of the model. Its API is described in README.
+export const mapping: GenerationWireMapping = {
+ capability, result: "video", routes: [{ model: "seedance-2-mini" }],
+ fields: {
+ prompt: { as: "value", field: "prompt" },
+ duration: { as: "value", field: "duration" },
+ resolution: { as: "value", field: "resolution" },
+ aspectRatio: { as: "value", field: "ratio" },
+ generateAudio: { as: "value", field: "audio" },
+ webSearch: { as: "value", field: "search" },
+ referenceImage: { as: "itemObject", field: "references", urlKey: "url", fieldKeys: { personReference: "person" } },
+ referenceVideo: { as: "itemObject", field: "videoReferences", urlKey: "url", fieldKeys: { personReference: "person" } },
+ referenceAudio: { as: "urlArray", field: "audioReferences" },
+ firstFrame: { as: "url", field: "firstFrame", resourceFields: ["personReference"] },
+ lastFrame: { as: "url", field: "lastFrame", resourceFields: ["personReference"] },
+ },
+};
+
+// This service renders a narrower band than the model vocabulary allows, which it reports rather
+// than widening: Seedance 2 Mini declares 480p/720p and 4–15 seconds, and this service renders 720p
+// up to 10 seconds. The Model is unchanged; the difference belongs to this Endpoint.
+const SUPPORTED_RESOLUTION = "720p";
+const SUPPORTED_SECONDS = 10;
+
+function object(value: unknown): Record<string, unknown> {
+ if (value === null || typeof value !== "object" || Array.isArray(value)) throw new Error("Expected service object");
+ return value as Record<string, unknown>;
+}
+function text(value: unknown): string {
+ if (typeof value !== "string" || value.length === 0) throw new Error("Expected nonempty service text");
+ return value;
+}
+// This illustrative service documents these fields as its public failure evidence.
+function publicFailure(value: unknown): { code: string; message: string } | undefined {
+ if (value === null || typeof value !== "object" || Array.isArray(value)) return undefined;
+ const error = value as Record<string, unknown>;
+ if (typeof error.code !== "string" || typeof error.message !== "string") return undefined;
+ return { code: error.code, message: error.message.replace(/https?:\/\/\S+/giu, "[redacted-url]") };
+}
+function address(value: string): string {
+ const url = new URL(value);
+ if (url.protocol !== "https:" && !(url.protocol === "http:" && ["localhost", "127.0.0.1"].includes(url.hostname))) {
+ throw new Error("Service URLs require HTTPS or loopback HTTP");
+ }
+ return url.href;
+}
+
+function serviceSupport(request: EndpointRequest) {
+ const ports = (request.constraints as unknown as GenerationRequest).ports;
+ const duration = ports.duration?.[0];
+ if (typeof duration === "number" && duration > SUPPORTED_SECONDS) {
+ return { status: "unsupported" as const,
+ reason: `This service renders at most ${SUPPORTED_SECONDS} seconds, not ${duration}` };
+ }
+ const resolution = ports.resolution?.[0];
+ if (resolution !== undefined && String(resolution) !== SUPPORTED_RESOLUTION) {
+ return { status: "unsupported" as const,
+ reason: `This service renders at ${SUPPORTED_RESOLUTION}, not ${String(resolution)}` };
+ }
+ return mappingSupportsRequest(mapping, request.constraints)
+ ? { status: "supported" as const }
+ : { status: "unsupported" as const, reason: "This service does not accept one of the requested inputs" };
+}
+
+export function createVideoProvider(options: {
+ instance: string; pool: string; baseUrl: string; apiKey: CredentialRef;
+ concurrency?: number; pollIntervalMs?: number; fetch?: typeof globalThis.fetch;
+}) {
+ const base = address(options.baseUrl).replace(/\/$/u, "");
+ const fetcher = options.fetch ?? globalThis.fetch;
+ const interval = options.pollIntervalMs ?? 5_000;
+ const key = (credentials: Readonly<Record<string, { secret: string }>>) => text(credentials.apiKey?.secret);
+ async function json(path: string, secret: string, init: RequestInit = {}) {
+ const response = await fetcher(`${base}${path}`, {
+ ...init, headers: { ...init.headers, authorization: `Bearer ${secret}` },
+ // Submission enqueues a remote job and answers immediately; the bound is for the API, not the render.
+ signal: AbortSignal.timeout(120_000),
+ });
+ if (!response.ok) {
+ let error: ReturnType<typeof publicFailure>;
+ try { error = publicFailure(object(await response.json()).error); }
+ catch { /* A missing public error body leaves the HTTP evidence intact. */ }
+ const requestId = response.headers.get("x-request-id");
+ throw Object.assign(new Error(`Video service ${init.method ?? "GET"} ${path} returned HTTP ${response.status}`
+ + (requestId === null ? "" : `; request=${requestId}`)
+ + (error === undefined ? "" : `; ${error.code}: ${error.message}`)),
+ error === undefined ? {} : { code: error.code });
+ }
+ return object(await response.json());
+ }
+ const endpoint: AsyncEndpoint = {
+ async start(context) {
+ const supported = serviceSupport(context.need);
+ if (supported.status === "unsupported") throw new Error(supported.reason);
+ const secret = key(context.credentials);
+ const authored = context.need.constraints as unknown as GenerationRequest;
+ const model = selectWireModelForRequest(mapping, authored);
+ // This service has no catalogue query; its known request limits were checked above.
+ await context.reportProgress?.({ phase: `Preparing video request: ${model}` });
+ const request = await compileWireRequest(mapping, authored,
+ async (artifact, fields) => {
+ const bytes = await context.resources.get(artifact.resource);
+ if (bytes === undefined) throw new Error("Reference media is unavailable");
+ const upload = await fetcher(`${base}/uploads`, {
+ method: "POST", headers: { "content-type": artifact.mediaType, authorization: `Bearer ${secret}`,
+ ...(fields?.personReference === undefined ? {} : { "x-person-reference": String(fields.personReference) }),
+ },
+ body: new Blob([new Uint8Array(bytes)]), signal: AbortSignal.timeout(120_000),
+ });
+ if (!upload.ok) throw new Error(`Video service POST /uploads returned HTTP ${upload.status}`);
+ return address(text(object(await upload.json()).url));
+ });
+ await context.reportProgress?.({ phase: `Submitting video request: ${model}` });
+ const task = await json("/videos", secret, {
+ method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify(request),
+ });
+ const id = text(task.id), handle = { id }, receipt = { id };
+ await context.checkpoint?.({ handle, receipt });
+ return { ...wakeAfter(handle, interval), receipt };
+ },
+ async poll(context) {
+ const id = text(object(context.handle).id);
+ const task = await json(`/videos/${encodeURIComponent(id)}`, key(context.credentials));
+ const status = text(task.status);
+ if (status === "queued" || status === "running") {
+ return wakeAfter({ id }, interval, Date.now(), { phase: status });
+ }
+ if (status === "failed") {
+ const error = publicFailure(task.error);
+ return { status: "failed", receipt: { id }, failure: {
+ code: error?.code ?? "VIDEO_SERVICE_FAILED",
+ message: `Video service task ${id} failed${error === undefined ? "" : `: ${error.message}`}`,
+ } };
+ }
+ if (status !== "succeeded") throw new Error("Video service returned an unknown task state");
+ // A completed task without a result URL is a service contract violation, not a pending job.
+ return { status: "ready", handle: { id, url: address(text(task.output)) } };
+ },
+ async collect(context) {
+ // The service returns a signed asset URL; account credentials go only to its API.
+ const url = address(text(object(context.handle).url));
+ await context.reportProgress?.({ phase: "Receiving generated video" });
+ // One delivered video is bounded here; a larger file belongs with a streaming resource port.
+ const response = await fetcher(url, { signal: AbortSignal.timeout(600_000) });
+ if (!response.ok) throw new Error(`Video download returned HTTP ${response.status}`);
+ const mediaType = response.headers.get("content-type")?.split(";")[0]?.trim();
+ if (!mediaType?.startsWith("video/")) throw new Error("Video service returned a non-video result");
+ const artifact = await context.resources.put(new Uint8Array(await response.arrayBuffer()), mediaType);
+ return { status: "completed", result: { value: {
+ kind: "inline", value: canonicalize(sealGeneratedVideoSet({ videos: [artifact] })),
+ } } };
+ },
+ };
+ return defineEndpointPackage({
+ module: providerModule, facet: "videos", instance: options.instance, pool: options.pool,
+ credentials: { apiKey: options.apiKey }, credentialInputs: { apiKey: { label: "Video service API key" } },
+ defaultConcurrency: options.concurrency ?? 1,
+ actionLimits: { submit: { concurrency: 1 }, poll: { concurrency: 4 }, collect: { concurrency: 2 } },
+ pricing: { kind: "page", url: `${base}/pricing` },
+ async readPricing(context) {
+ const model = selectWireModelForRequest(mapping, context.request.constraints as unknown as GenerationRequest,
+ context.request.pendingInputs?.map((input) => input.input));
+ const path = `/rates?model=${encodeURIComponent(model)}`;
+ const source = `${base}${path}`;
+ const rates = await json(path, key(await context.credentials()));
+ return [{ source, data: canonicalize(rates), summary: text(rates.description) }];
+ },
+ capabilities: [{ capability, returns: generationTypes.videoSet, lifecycle: "asynchronous", supports: serviceSupport, endpoint }],
+ });
+}
diff --git a/examples/provider-package/packages/provider-videos/test/provider.test.ts b/examples/provider-package/packages/provider-videos/test/provider.test.ts
new file mode 100644
index 00000000..18ff39c6
--- /dev/null
+++ b/examples/provider-package/packages/provider-videos/test/provider.test.ts
@@ -0,0 +1,201 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { EndpointRegistry, MemoryResourceStore } from "@hypit/driver-node";
+import { sealSeedanceRequest } from "@hypit/seedance";
+import type { BlobRef, EndpointStartContext } from "@hypit/hypit/endpoint-kit";
+import { canonicalize } from "@hypit/hypit/endpoint-kit";
+import { generationTypes } from "@hypit/hypit/generation";
+import { assertMappingCoversPorts } from "@hypit/hypit/generation";
+import { seedancePorts } from "@hypit/seedance";
+import { capability, createVideoProvider, mapping } from "../src/provider.js";
+
+test("project video Provider accounts for every port the Seedance Model declares", () => {
+ // The check that turns a forgotten reference role or item field into a load-time failure
+ // instead of a paid generation returning the wrong video.
+ assertMappingCoversPorts(seedancePorts["seedance-2-mini"], mapping);
+});
+
+test("project video Provider uploads a reference, retains its receipt and collects the generated video", async () => {
+ const resources = new MemoryResourceStore();
+ const source = await resources.put(new Uint8Array([1, 2, 3]), "image/png");
+ const calls: string[] = [];
+ const progress: string[] = [];
+ let checkpoint: unknown;
+ const provider = createVideoProvider({
+ instance: "videos.personal", pool: "videos.personal", baseUrl: "https://videos.example",
+ apiKey: { store: "os", key: "videos.personal" }, pollIntervalMs: 0,
+ fetch: async (input, init) => {
+ const url = new URL(String(input)); calls.push(url.pathname);
+ if (url.hostname === "assets.example") {
+ assert.equal(init?.signal === undefined, false);
+ assert.equal(progress.at(-1), "Receiving generated video");
+ return new Response(new Uint8Array([4, 5, 6]), { headers: { "content-type": "video/mp4" } });
+ }
+ assert.equal((init?.headers as Record<string, string>).authorization, "Bearer test-key");
+ if (url.pathname === "/rates") return Response.json({ description: "$0.40 per second of video", unit: "second", usd: 0.4 });
+ if (url.pathname === "/uploads") {
+ assert.equal(progress.at(-1), "Preparing video request: seedance-2-mini");
+ assert.deepEqual(new Uint8Array(await (init?.body as Blob).arrayBuffer()), new Uint8Array([1, 2, 3]));
+ return Response.json({ url: "https://assets.example/reference.png" });
+ }
+ if (url.pathname === "/videos") {
+ assert.equal(progress.at(-1), "Submitting video request: seedance-2-mini");
+ assert.deepEqual(JSON.parse(String(init?.body)), {
+ model: "seedance-2-mini",
+ input: {
+ prompt: "A slow push-in", duration: 5, resolution: "720p", ratio: "9:16",
+ audio: true, search: false,
+ references: [{ url: "https://assets.example/reference.png", person: true }],
+ },
+ });
+ return Response.json({ id: "received-job" });
+ }
+ if (url.pathname === "/videos/received-job") {
+ assert.deepEqual(checkpoint, { handle: { id: "received-job" }, receipt: { id: "received-job" } });
+ return Response.json({ status: "succeeded", output: "https://assets.example/output.mp4" });
+ }
+ throw new Error(`Unexpected path ${url.pathname}`);
+ },
+ });
+ const constraints = canonicalize(sealSeedanceRequest("seedance-2-mini", {
+ prompt: ["A slow push-in"],
+ duration: [5],
+ resolution: ["720p"],
+ aspectRatio: ["9:16"],
+ generateAudio: [true],
+ webSearch: [false],
+ referenceImage: [{ role: "image", artifact: source, fields: { personReference: true } }],
+ }));
+ const need = { id: "need:example", capability, returns: generationTypes.videoSet, constraints, result: "record:example" } as const;
+ const registry = new EndpointRegistry(); await provider.install(registry);
+ const resolution = registry.resolve(need);
+ assert.equal(resolution.status, "resolved");
+ assert.equal(resolution.registration.kind, "asynchronous");
+ const endpoint = resolution.registration.endpoint;
+ const context: EndpointStartContext = {
+ need, command: { kind: "fulfill-need", id: "command:example", need }, operation: "operation:example",
+ resources, credentials: { apiKey: { secret: "test-key" } },
+ checkpoint: async (value) => { checkpoint = value; },
+ reportProgress: async (value) => { progress.push(value.phase); },
+ };
+ const pricing = await provider.readPricing!({ request: need, credentials: async () => context.credentials });
+ assert.equal(pricing[0]?.summary, "$0.40 per second of video");
+ const start = await endpoint.start(context); assert.equal(start.status, "pending");
+ const ready = await endpoint.poll({ ...context, handle: start.handle }); assert.equal(ready.status, "ready");
+ const collected = await endpoint.collect!({ ...context, handle: ready.handle }); assert.equal(collected.status, "completed");
+ assert.equal(collected.result.value.kind, "inline");
+ const videos = (collected.result.value.value as unknown as { videos: BlobRef[] }).videos;
+ assert.equal(videos[0]?.mediaType, "video/mp4");
+ assert.deepEqual(await resources.get(videos[0]!.resource), new Uint8Array([4, 5, 6]));
+ assert.deepEqual(calls, ["/rates", "/uploads", "/videos", "/videos/received-job", "/output.mp4"]);
+ assert.deepEqual(progress, ["Preparing video request: seedance-2-mini", "Submitting video request: seedance-2-mini", "Receiving generated video"]);
+});
+
+test("project video Provider reports its narrower service range without changing the model", async () => {
+ const provider = createVideoProvider({
+ instance: "videos.personal", pool: "videos.personal", baseUrl: "https://videos.example",
+ apiKey: { store: "os", key: "videos.personal" },
+ });
+ const need = (ports: Parameters<typeof sealSeedanceRequest>[1]) => ({
+ id: "need:range", capability, returns: generationTypes.videoSet,
+ constraints: canonicalize(sealSeedanceRequest("seedance-2-mini", ports)), result: "record:range",
+ });
+ const prompted = { prompt: ["A slow push-in"], generateAudio: [true], webSearch: [false] };
+ const supported = provider.offers[0]!.supports!(
+ need({ ...prompted, duration: [5], resolution: ["720p"], aspectRatio: ["9:16"] }));
+ assert.equal(supported.status, "supported");
+ // The Model admits both of these; this Endpoint is what narrows them.
+ const tooLong = provider.offers[0]!.supports!(need({ ...prompted, duration: [12], resolution: ["720p"], aspectRatio: ["9:16"] }));
+ assert.equal(tooLong.status, "unsupported");
+ assert.match(tooLong.status === "unsupported" ? tooLong.reason : "", /at most 10 seconds, not 12/u);
+ const tooSmall = provider.offers[0]!.supports!(need({ ...prompted, duration: [5], resolution: ["480p"], aspectRatio: ["9:16"] }));
+ assert.equal(tooSmall.status, "unsupported");
+ assert.match(tooSmall.status === "unsupported" ? tooSmall.reason : "", /renders at 720p, not 480p/u);
+});
+
+test("project video Provider keeps the received task id when the render fails remotely", async () => {
+ const calls: string[] = [];
+ let checkpointed = false;
+ const provider = createVideoProvider({
+ instance: "videos.personal", pool: "videos.personal", baseUrl: "https://videos.example",
+ apiKey: { store: "os", key: "videos.personal" }, pollIntervalMs: 0,
+ fetch: async (input) => {
+ const path = new URL(String(input)).pathname;
+ calls.push(path);
+ if (path === "/videos") return Response.json({ id: "job-one" });
+ return Response.json({
+ status: "failed",
+ error: { code: "content_filtered", message: "Rejected; see https://videos.example/private?token=hidden" },
+ debug: { secret: "not-public" },
+ });
+ },
+ });
+ const need = {
+ id: "need:failure", capability, returns: generationTypes.videoSet,
+ constraints: canonicalize(sealSeedanceRequest("seedance-2-mini", {
+ prompt: ["A slow push-in"], duration: [5], resolution: ["720p"], aspectRatio: ["9:16"],
+ generateAudio: [true], webSearch: [false],
+ })),
+ result: "record:failure",
+ };
+ const registry = new EndpointRegistry();
+ await provider.install(registry);
+ const resolved = registry.resolve(need);
+ assert.equal(resolved.status, "resolved");
+ assert.equal(resolved.registration.kind, "asynchronous");
+ const endpoint = resolved.registration.endpoint;
+ const context: EndpointStartContext = {
+ command: { kind: "fulfill-need", id: "command:failure", need }, need, operation: "operation:failure",
+ resources: new MemoryResourceStore(), credentials: { apiKey: { secret: "test-key" } },
+ checkpoint: async () => { checkpointed = true; },
+ };
+ const started = await endpoint.start(context);
+ assert.equal(started.status, "pending");
+ const failed = await endpoint.poll({ ...context, handle: started.handle });
+ assert.equal(failed.status, "failed");
+ assert.equal(failed.status === "failed" ? failed.failure.code : "", "content_filtered");
+ assert.match(failed.status === "failed" ? failed.failure.message : "", /task job-one failed/u);
+ // Public evidence is preserved and the redacted URL is not republished.
+ assert.doesNotMatch(failed.status === "failed" ? failed.failure.message : "", /not-public|token=hidden|test-key/u);
+ assert.deepEqual(failed.receipt, { id: "job-one" });
+ assert.equal(checkpointed, true);
+ assert.deepEqual(calls, ["/videos", "/videos/job-one"]);
+});
+
+test("first and last frame person flags reach the upload API, including false", async () => {
+ const resources = new MemoryResourceStore();
+ const image = await resources.put(new Uint8Array([1]), "image/png");
+ const flags: (string | null)[] = [];
+ const provider = createVideoProvider({
+ instance: "videos.personal", pool: "videos.personal", baseUrl: "https://videos.example",
+ apiKey: { store: "os", key: "example" },
+ fetch: async (input, init) => {
+ const path = new URL(String(input)).pathname;
+ if (path === "/uploads") {
+ flags.push(new Headers(init?.headers).get("x-person-reference"));
+ return Response.json({ url: `https://assets.example/frame-${flags.length}.png` });
+ }
+ assert.equal(path, "/videos");
+ const sent = JSON.parse(String(init?.body));
+ assert.equal(sent.input.firstFrame, "https://assets.example/frame-1.png");
+ assert.equal(sent.input.lastFrame, "https://assets.example/frame-2.png");
+ return Response.json({ id: "frames" });
+ },
+ });
+ const need = { id: "need:frames", capability, returns: generationTypes.videoSet, result: "record:frames",
+ constraints: canonicalize(sealSeedanceRequest("seedance-2-mini", {
+ prompt: ["A presenter"], duration: [5], resolution: ["720p"], aspectRatio: ["9:16"],
+ generateAudio: [true], webSearch: [false],
+ firstFrame: [{ role: "image", artifact: image, fields: { personReference: true } }],
+ lastFrame: [{ role: "image", artifact: image, fields: { personReference: false } }],
+ })),
+ };
+ const registry = new EndpointRegistry(); await provider.install(registry);
+ const selected = registry.resolve(need);
+ assert.equal(selected.status, "resolved");
+ assert.equal(selected.registration.kind, "asynchronous");
+ await selected.registration.endpoint.start({ need, command: { kind: "fulfill-need", id: "frames", need },
+ operation: "frames", resources, credentials: { apiKey: { secret: "test" } },
+ });
+ assert.deepEqual(flags, ["true", "false"]);
+});
diff --git a/examples/provider-package/packages/provider-videos/tsconfig.json b/examples/provider-package/packages/provider-videos/tsconfig.json
new file mode 100644
index 00000000..741d98f2
--- /dev/null
+++ b/examples/provider-package/packages/provider-videos/tsconfig.json
@@ -0,0 +1,9 @@
+{
+ "compilerOptions": {
+ "target": "ES2023", "module": "NodeNext", "moduleResolution": "NodeNext",
+ "lib": ["ES2023", "DOM"], "strict": true, "noUncheckedIndexedAccess": true,
+ "exactOptionalPropertyTypes": true, "verbatimModuleSyntax": true,
+ "declaration": true, "rootDir": "src", "outDir": "dist", "skipLibCheck": true
+ },
+ "include": ["src/**/*.ts"]
+}
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 265e81c9..aecd89af 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -364,6 +364,21 @@ importers:
specifier: 5.9.3
version: 5.9.3
+ examples/provider-package/packages/provider-videos:
+ devDependencies:
+ '@hypit/driver-node':
+ specifier: workspace:*
+ version: link:../../../../packages/driver-node
+ '@hypit/hypit':
+ specifier: workspace:*
+ version: link:../../../..
+ '@hypit/seedance':
+ specifier: workspace:*
+ version: link:../../../../packages/seedance
+ typescript:
+ specifier: 5.9.3
+ version: 5.9.3
+
examples/semantic-composition/packages/chat-scene:
devDependencies:
'@hypit/hypit':
diff --git a/skills/hypit/references/environment/model-and-provider.md b/skills/hypit/references/environment/model-and-provider.md
index ae9e606b..51ef8ae5 100644
--- a/skills/hypit/references/environment/model-and-provider.md
+++ b/skills/hypit/references/environment/model-and-provider.md
@@ -164,6 +164,14 @@ actual protocol. It demonstrates reference upload, receipt, polling, collection,
without introducing a second scheduler. For a new Model, the Model SDK README includes the definition
and author-package activation example.
+It ships two packages, and the request shape decides which one to follow: `provider-images` for a
+generated image, `provider-videos` for a generated video. A video service usually receives a wider
+reference vocabulary — images, videos, audio and first/last frames, each role mapping to its own wire
+field — and returns its result through a separate `collect` step after `poll` reports the job ready.
+A service that only supports part of the Model's declared range, such as fewer resolutions or a lower
+maximum duration, reports that from `supports` so `plan` refuses the request with a reason; the shared
+Model stays unchanged and the author's number is never silently narrowed.
+
## Use the public SDK
| Import | Responsibility |