@hypit/hypit 0.2.3 → 0.2.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hypit/hypit",
-  "version": "0.2.3",
+  "version": "0.2.4",
   "homepage": "https://hypit.ai",
   "repository": {
     "type": "git",
@@ -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:*",

package/packages/media-execution/src/execute.ts

@@ -689,7 +689,7 @@ export async function executeNormalizeMedia(
       await runProcess({
         executable: env.ffmpegPath,
         argv: ["-y", ...visualInput, "-an", "-vf", filter,
-          "-frames:v", String(plan.frameCount), "-fps_mode", "cfr", ...encoderArgs, output],
+          "-frames:v", String(plan.frameCount), "-r", fps, "-fps_mode", "cfr", ...encoderArgs, output],
         timeoutMs: env.processTimeoutMs,
         maxStdoutBytes: 64 * 1024,
         ...(env.sharedLibraryPath === undefined ? {} : { sharedLibraryPath: env.sharedLibraryPath }),
@@ -951,7 +951,8 @@ export async function executeTransformMedia(
       argv.push("-map", "0:v:0", "-an", "-vf", plan.videoFilters.join(","));
     }
     argv.push(
-      "-frames:v", String(plan.frameCount), "-fps_mode", "cfr",
+      "-frames:v", String(plan.frameCount),
+      "-r", `${media.timeline.frameRate.numerator}/${media.timeline.frameRate.denominator}`, "-fps_mode", "cfr",
       "-c:v", "libx264", "-preset", "veryfast", "-pix_fmt", "yuv420p",
       "-movflags", "+faststart", output,
     );

package/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.

package/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:*"
+  }
+}

package/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;

package/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)}`}`);
+}

package/packages/provider-hiapi/src/index.ts

@@ -0,0 +1,2 @@
+export { createHiApiProvider, hiApiProviderModuleRef } from "./provider.js";
+export type { CreateHiApiProviderOptions } from "./provider.js";

package/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" },
+    },
+  },
+];

package/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,
+    })),
+  });
+}