@hypit/hypit 0.2.9 → 0.2.10

package/README.md

@@ -209,6 +209,12 @@ commands and the repository layout.
     </td>
     <td><a href="https://api.pollo.ai/?utm_source=hypit">Pollo API</a> gives developers access to 300+ AI image and video models through a single API, with competitive rates. One API key connects you to multiple model providers and scales from 10 to 10,000+ requests.</td>
   </tr>
+  <tr>
+    <td width="220" align="center">
+      <a href="https://beatapi.io"><img alt="BeatAPI" src="./docs/public/beatapi.png" width="165"></a>
+    </td>
+    <td><a href="https://beatapi.io">BeatAPI</a> is the professional capability layer for any agent. We provide AI models, real-world data, task-ready capabilities, and professional workspaces that help agents complete real-world tasks.</td>
+  </tr>
 </table>
 
 ## ⭐ Star History

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hypit/hypit",
-  "version": "0.2.9",
+  "version": "0.2.10",
   "homepage": "https://hypit.ai",
   "repository": {
     "type": "git",
@@ -236,8 +236,9 @@
     "@hypit/program-space": "workspace:*",
     "@hypit/project-context-node": "workspace:*",
     "@hypit/protocol": "workspace:*",
-    "@hypit/provider-hyperframes-local": "workspace:*",
+    "@hypit/provider-beatapi": "workspace:*",
     "@hypit/provider-hiapi": "workspace:*",
+    "@hypit/provider-hyperframes-local": "workspace:*",
     "@hypit/provider-hypihub": "workspace:*",
     "@hypit/provider-image-opencv-local": "workspace:*",
     "@hypit/provider-media-local": "workspace:*",

package/packages/provider-beatapi/README.md

@@ -0,0 +1,84 @@
+# `@hypit/provider-beatapi`
+
+Hypit Runtime Provider for a [BeatAPI](https://docs.beatapi.io/quick-guide) account. Each capability
+posts one task to `https://api.beatapi.io` with a `Bearer` API key, polls `GET /v1/tasks/{task_id}`
+until it reaches `succeeded`, downloads every entry of `output.media` and stores the files in the
+current Build.
+
+| Capability | BeatAPI model | Task path |
+| --- | --- | --- |
+| `@hypit/seedance@1#seedance-2` | `seedance-2` | `/v1/videos/tasks` |
+| `@hypit/seedance@1#seedance-2-fast` | `seedance-2-fast` | `/v1/videos/tasks` |
+| `@hypit/seedance@1#seedance-2-mini` | `seedance-2-mini` | `/v1/videos/tasks` |
+| `@hypit/seedance@1#seedance-2.5` | `seedance-2.5` | `/v1/videos/tasks` |
+| `@hypit/minimax-h3@1#minimax-h3` | `minimax-h3` | `/v1/videos/tasks` |
+| `@hypit/grok-imagine@1#grok-imagine-video-1.5-preview` | `grok-imagine-video-1.5` | `/v1/videos/tasks` |
+| `@hypit/gpt-image@1#gpt-image-2` | `gpt-image-2` | `/v1/images/tasks` |
+| `@hypit/nano-banana@1#nano-banana-2` | `nano-banana-2` | `/v1/images/tasks` |
+| `@hypit/nano-banana@1#nano-banana-pro` | `nano-banana-pro` | `/v1/images/tasks` |
+
+BeatAPI documents further models, including Veo, Kling, Wan 3.0 and HappyHorse; this Provider maps
+only the models the Distribution already describes.
+
+One BeatAPI alias serves every input mode, so the request shape alone decides which arrays travel:
+`reference_images`, `reference_videos` and `reference_audios` carry subject references, while the
+opening and closing frames travel as one ordered `images` array. `duration`, `aspect_ratio`,
+`resolution` and Seedance's `generate_audio` keep their authored values. Nano Banana 2 spells its
+JPEG output `jpeg`, so an authored `output-format="jpg"` is sent as that.
+
+Service limits this Provider reports as unsupported before uploading any reference:
+
+- Seedance has no `web_search` field, and `seedance-2-mini` renders no generated audio. An authored
+  `false` is dropped; an authored `true` is refused.
+- Seedance 2 does not render 1080p together with reference images.
+- Seedance 2.5 takes 4 to 30 seconds, so `duration="-1"` for an automatic length is refused.
+- MiniMax H3 orders its two frames first then last, so a last frame needs a first frame.
+- Grok Imagine 1.5 accepts at most one image at 1080p.
+- GPT Image 2 has no `background` field.
+- Nano Banana 2 accepts up to ten reference images and does not render `1:4`, `4:1`, `1:8` or `8:1`.
+
+Seedance visual references carry `person-reference`; the Provider accepts the declaration and
+transmits nothing for it, since BeatAPI's task body has no field for it.
+
+Referenced Resources are uploaded to `POST /v1/files` with `purpose=input`, and the returned HTTPS
+URL travels in the task body. The service accepts PNG, JPEG and WebP images and MP3, WAV, AAC and
+M4A audio up to 50 MB each, and MP4 and MOV video up to 100 MB; a reference outside those types or
+sizes is reported before submission. One Resource is uploaded once per Runtime operation. Embedded
+callers may replace that transport with `publicAssetUrl(artifact, resources, fields)`, which must
+return a URL BeatAPI can fetch.
+
+Runtime Profile example:
+
+```json
+{
+  "format": "hypit.runtime-local@1",
+  "dataRoot": ".hypit/runtimes/local",
+  "credentials": {
+    "platform": {
+      "use": "@hypit/credential-store-platform"
+    }
+  },
+  "endpoints": {
+    "beatapi.default": {
+      "use": "@hypit/provider-beatapi",
+      "pool": "beatapi.default",
+      "config": {
+        "apiKey": { "store": "platform", "key": "beatapi.api-key" },
+        "defaultConcurrency": 3,
+        "pollIntervalMs": 10000
+      }
+    }
+  },
+  "bindings": {}
+}
+```
+
+`baseUrl` defaults to `https://api.beatapi.io`. Store the API key with
+`hypit auth login beatapi.default --runtime hypit.runtime.json`. Optional `requestTimeoutMs`,
+`operationTimeoutMs` and `actionLimits` bound single HTTP calls, the whole remote task and action
+concurrency. Each submission sends the Runtime operation as its `Idempotency-Key`, so a retried
+submission of the same body resolves to the same task.
+
+HTTP failures keep BeatAPI's `error.code`, message, `request_id` and any `retry_after_seconds`; a
+`failed` task keeps its `error_code` and `error_message`. Any URL inside a surfaced reason is
+redacted, since a hosted result URL is an access capability rather than diagnostic content.

package/packages/provider-beatapi/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "@hypit/provider-beatapi",
+  "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:*"
+  }
+}

package/packages/provider-beatapi/src/activation.ts

@@ -0,0 +1,62 @@
+import {
+  createRuntimeEndpointAdapterFacet,
+  runtimeConfigCredentialRef,
+  runtimeConfigActionLimits,
+  runtimeConfigExact,
+  runtimeConfigObject,
+  runtimeConfigPositiveInteger,
+  runtimeConfigString,
+} from "@hypit/runtime-kit";
+
+import { createBeatApiProvider } from "./provider.js";
+
+const adapter = createRuntimeEndpointAdapterFacet({
+  use: "@hypit/provider-beatapi",
+  activate(context) {
+    if (context.pool === undefined) throw new Error("BeatAPI Provider Pool is required");
+    const config = runtimeConfigObject(context.config, "BeatAPI");
+    runtimeConfigExact(config, [
+      "baseUrl",
+      "apiKey",
+      "defaultConcurrency",
+      "actionLimits",
+      "pollIntervalMs",
+      "requestTimeoutMs",
+      "operationTimeoutMs",
+    ], "BeatAPI");
+    const baseUrl = runtimeConfigString(config.baseUrl, "BeatAPI 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("BeatAPI baseUrl must use HTTPS or loopback");
+      }
+    }
+    const apiKey = runtimeConfigCredentialRef(config.apiKey, "BeatAPI apiKey");
+    if (apiKey === undefined) throw new Error("BeatAPI apiKey CredentialRef is required");
+    const actionLimits = runtimeConfigActionLimits(config.actionLimits);
+    const defaultConcurrency = runtimeConfigPositiveInteger(config.defaultConcurrency, "BeatAPI defaultConcurrency");
+    const pollIntervalMs = runtimeConfigPositiveInteger(config.pollIntervalMs, "BeatAPI pollIntervalMs");
+    const requestTimeoutMs = runtimeConfigPositiveInteger(config.requestTimeoutMs, "BeatAPI requestTimeoutMs");
+    const operationTimeoutMs = runtimeConfigPositiveInteger(config.operationTimeoutMs, "BeatAPI operationTimeoutMs");
+    return {
+      endpoint: createBeatApiProvider({
+        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-beatapi/src/errors.ts

@@ -0,0 +1,46 @@
+/** BeatAPI's `{ error: { code, message, request_id, retry_after_seconds } }` envelope and terminal task errors. */
+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 hosted result URL. Keep the reason, not its access capability.
+export function safeBeatApiReason(value: string): string {
+  return value.replace(/https?:\/\/\S+/giu, "[redacted-url]");
+}
+
+export class BeatApiServiceError extends Error {
+  constructor(readonly code: string, message: string) { super(message); }
+}
+
+export class BeatApiHttpError extends BeatApiServiceError {
+  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) ?? "BEATAPI_HTTP_ERROR";
+    const reason = text(error?.message) ?? (error === undefined ? text(bodyText.slice(0, 2000)) : undefined);
+    const requestId = text(error?.request_id) ?? text(response.headers.get("x-request-id"));
+    const retryAfter = typeof error?.retry_after_seconds === "number" ? error.retry_after_seconds : undefined;
+    const facts = [
+      `BeatAPI HTTP ${status}`, code, `${request.method} ${request.path}`,
+      ...(request.model === undefined ? [] : [`model=${request.model}`]),
+      ...(requestId === undefined ? [] : [`request=${requestId}`]),
+      ...(retryAfter === undefined ? [] : [`retry-after=${retryAfter}s`]),
+    ];
+    super(code, `${facts.join("; ")}${reason === undefined ? "" : `: ${safeBeatApiReason(reason)}`}`);
+  }
+}
+
+/** A terminal `failed` task; `undefined` otherwise. */
+export function beatApiTaskFailure(task: Record<string, unknown>, id: string): BeatApiServiceError | undefined {
+  if (task.status !== "failed") return undefined;
+  const code = text(task.error_code) ?? "BEATAPI_TASK_FAILED";
+  const reason = text(task.error_message);
+  return new BeatApiServiceError(code,
+    `BeatAPI task ${id} failed; ${code}${reason === undefined ? "" : `: ${safeBeatApiReason(reason)}`}`);
+}

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

@@ -0,0 +1,2 @@
+export { createBeatApiProvider, beatApiProviderModuleRef } from "./provider.js";
+export type { CreateBeatApiProviderOptions } from "./provider.js";

package/packages/provider-beatapi/src/mapping.ts

@@ -0,0 +1,89 @@
+import type { ModuleRef } from "@hypit/protocol";
+import type { GenerationWireMapping } from "@hypit/generation";
+
+const SEEDANCE: ModuleRef = { name: "@hypit/seedance", version: "1" };
+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" };
+
+/**
+ * BeatAPI model aliases and the body fields each one documents. One alias serves every input mode,
+ * so each Capability has a single route and the request shape alone decides which arrays travel.
+ *
+ * BeatAPI carries the opening and closing frames as one ordered `images` array rather than two
+ * fields. The mapping writes them to `first_frame` and `last_frame`, which routes.ts folds into
+ * that array; a mapping cannot write one wire field from two ports.
+ */
+const seedanceFields = {
+  prompt: { as: "value", field: "prompt" },
+  firstFrame: { as: "url", field: "first_frame", resourceFields: ["personReference"] },
+  lastFrame: { as: "url", field: "last_frame", resourceFields: ["personReference"] },
+  referenceImage: { as: "urlArray", field: "reference_images", resourceFields: ["personReference"] },
+  referenceVideo: { as: "urlArray", field: "reference_videos", resourceFields: ["personReference"] },
+  referenceAudio: { as: "urlArray", field: "reference_audios" },
+  duration: { as: "value", field: "duration" },
+  aspectRatio: { as: "value", field: "aspect_ratio" },
+  resolution: { as: "value", field: "resolution" },
+  generateAudio: { as: "value", field: "generate_audio" },
+  webSearch: { as: "value", field: "web_search" },
+} as const satisfies GenerationWireMapping["fields"];
+
+const seedance = (name: string): GenerationWireMapping => ({
+  capability: { module: SEEDANCE, name }, result: "video", routes: [{ model: name }], fields: seedanceFields,
+});
+
+export const beatApiMappings: readonly GenerationWireMapping[] = [
+  seedance("seedance-2"),
+  seedance("seedance-2-fast"),
+  seedance("seedance-2-mini"),
+  seedance("seedance-2.5"),
+  {
+    capability: { module: MINIMAX, name: "minimax-h3" }, result: "video",
+    routes: [{ model: "minimax-h3" }],
+    fields: {
+      prompt: { as: "value", field: "prompt" },
+      firstFrame: { as: "url", field: "first_frame" },
+      lastFrame: { as: "url", field: "last_frame" },
+      referenceImage: { as: "urlArray", field: "reference_images" },
+      referenceVideo: { as: "urlArray", field: "reference_videos" },
+      referenceAudio: { as: "urlArray", field: "reference_audios" },
+      duration: { as: "value", field: "duration" },
+      aspectRatio: { as: "value", field: "aspect_ratio" },
+      resolution: { as: "value", field: "resolution" },
+    },
+  },
+  {
+    capability: { module: GROK, name: "grok-imagine-video-1.5-preview" }, result: "video",
+    routes: [{ model: "grok-imagine-video-1.5" }],
+    fields: {
+      prompt: { as: "value", field: "prompt" },
+      images: { as: "urlArray", field: "reference_images" },
+      duration: { as: "value", field: "duration" },
+      aspectRatio: { as: "value", field: "aspect_ratio" },
+      resolution: { as: "value", field: "resolution" },
+    },
+  },
+  {
+    capability: { module: GPT_IMAGE, name: "gpt-image-2" }, result: "image",
+    routes: [{ model: "gpt-image-2" }],
+    fields: {
+      prompt: { as: "value", field: "prompt" },
+      images: { as: "urlArray", field: "images" },
+      aspectRatio: { as: "value", field: "aspect_ratio" },
+      resolution: { as: "value", field: "resolution" },
+      background: { as: "value", field: "background" },
+    },
+  },
+  ...(["nano-banana-2", "nano-banana-pro"] as const).map((model) => ({
+    capability: { module: NANO_BANANA, name: model }, result: "image" as const,
+    routes: [{ model }],
+    fields: {
+      prompt: { as: "value" as const, field: "prompt" },
+      images: { as: "urlArray" as const, field: "images" },
+      aspectRatio: { as: "value" as const, field: "aspect_ratio" },
+      resolution: { as: "value" as const, field: "resolution" },
+      outputFormat: { as: "value" as const, field: "output_format" },
+    },
+  })),
+];

package/packages/provider-beatapi/src/provider.ts

@@ -0,0 +1,238 @@
+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 { beatApiRouteForCapability, beatApiRoutes } from "./routes.js";
+import { BeatApiHttpError, BeatApiServiceError, beatApiTaskFailure } from "./errors.js";
+
+export const beatApiProviderModuleRef = { name: "@hypit/provider-beatapi", version: "1" } as const;
+
+export type CreateBeatApiProviderOptions = {
+  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 `/v1/files` upload. */
+  readonly publicAssetUrl?: (artifact: BlobRef, artifacts: ResourceStore, fields?: Readonly<Record<string, string | number | boolean>>) => Promise<string>;
+};
+
+type Handle = {
+  readonly contract: "hypit.beatapi-operation@1";
+  readonly taskId: string;
+  readonly route: string;
+  readonly startedAt: number;
+  readonly urls?: readonly string[];
+};
+
+const MB = 1_000_000;
+
+/** Per-file sizes and containers `POST /v1/files` accepts, by media kind. */
+const uploadLimits: Readonly<Record<string, { readonly bytes: number; readonly mediaTypes: readonly string[] }>> = {
+  image: { bytes: 50 * MB, mediaTypes: ["image/png", "image/jpeg", "image/jpg", "image/webp"] },
+  audio: { bytes: 50 * MB, mediaTypes: ["audio/mpeg", "audio/mp3", "audio/wav", "audio/x-wav", "audio/aac", "audio/mp4", "audio/x-m4a"] },
+  video: { bytes: 100 * MB, mediaTypes: ["video/mp4", "video/quicktime"] },
+};
+
+const extensions: Readonly<Record<string, string>> = {
+  "image/png": "png", "image/jpeg": "jpg", "image/jpg": "jpg", "image/webp": "webp",
+  "audio/mpeg": "mp3", "audio/mp3": "mp3", "audio/wav": "wav", "audio/x-wav": "wav",
+  "audio/aac": "aac", "audio/mp4": "m4a", "audio/x-m4a": "m4a",
+  "video/mp4": "mp4", "video/quicktime": "mov",
+};
+
+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, "BeatAPI 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, "BeatAPI apiKey credential is unavailable; store a BeatAPI API key for this Endpoint");
+  return value;
+}
+function httpsUrl(value: unknown, subject: string): string {
+  assert(typeof value === "string" && /^https:\/\//u.test(value), `${subject} has no HTTPS URL`);
+  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 BeatApiServiceError ? error.code : "BEATAPI_ERROR", message: failureMessage(error) } };
+}
+
+class BeatApiClient {
+  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 BeatApiHttpError(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(`BeatAPI returned invalid JSON (${response.status})`); }
+      return object(object(body, "BeatAPI response").data, "BeatAPI response data");
+    } finally { deadline.finish(); }
+  }
+  /** Upload one referenced Resource and return the HTTPS URL the task request carries. */
+  async upload(artifact: BlobRef, resources: ResourceStore, key: string): Promise<string> {
+    const kind = artifact.mediaType.split("/", 1)[0] ?? "";
+    const limits = uploadLimits[kind];
+    assert(limits !== undefined, `BeatAPI accepts image, audio and video references, not ${artifact.mediaType}`);
+    assert(limits.mediaTypes.includes(artifact.mediaType),
+      `BeatAPI accepts ${limits.mediaTypes.join(", ")} for ${kind} references, not ${artifact.mediaType}`);
+    assert(artifact.size <= limits.bytes,
+      `BeatAPI accepts ${kind} references up to ${limits.bytes / MB} MB; ${artifact.resource} is ${artifact.size} bytes`);
+    const bytes = await resources.get(artifact.resource);
+    assert(bytes !== undefined && bytes.byteLength === artifact.size, `Reference Resource ${artifact.resource} is unavailable or has changed`);
+    const form = new FormData();
+    form.append("file", new Blob([new Uint8Array(bytes)], { type: artifact.mediaType }),
+      `${artifact.resource}.${extensions[artifact.mediaType] ?? "bin"}`);
+    form.append("purpose", "input");
+    const file = await this.json("/v1/files", key, { method: "POST", body: form });
+    return httpsUrl(file.url, "BeatAPI file upload");
+  }
+  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(`BeatAPI 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: BeatApiClient, context: EndpointInvocationContext, publicAssetUrl: CreateBeatApiProviderOptions["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.upload(artifact, context.resources, apiKey(context.credentials))
+      : publicAssetUrl(artifact, context.resources, fields);
+    resolved.set(artifact.resource, promise);
+    return promise;
+  };
+}
+
+/** Statuses a queued image or video task passes through before it is terminal. */
+const pendingStatuses: readonly string[] = ["queued", "processing"];
+
+function endpoint(client: BeatApiClient, pollIntervalMs: number, maxOperationMs: number, publicAssetUrl: CreateBeatApiProviderOptions["publicAssetUrl"]): AsyncEndpoint {
+  return {
+    async start(context) {
+      try {
+        const route = beatApiRouteForCapability(context.need.capability);
+        assert(route !== undefined, "BeatAPI does not implement this exact capability");
+        const request = route.prepare(context.need.constraints);
+        await context.reportProgress?.({ phase: `Preparing BeatAPI request: ${request.model}` });
+        let body: Record<string, unknown>;
+        try {
+          body = await request.compile(resolverFor(client, context, publicAssetUrl));
+        } catch (error) {
+          throw new BeatApiServiceError(error instanceof BeatApiServiceError ? error.code : "BEATAPI_ERROR",
+            `BeatAPI request preparation failed; model=${request.model}; generation not submitted: ${failureMessage(error)}`);
+        }
+        await context.reportProgress?.({ phase: `Submitting BeatAPI request: ${request.model}` });
+        const response = await client.json(`/v1/${request.media}s/tasks`, apiKey(context.credentials), {
+          method: "POST",
+          headers: { "content-type": "application/json", "idempotency-key": context.operation },
+          body: JSON.stringify(body),
+        });
+        assert(typeof response.id === "string" && response.id.length > 0, "BeatAPI response has no task id");
+        const handle: Handle = { contract: "hypit.beatapi-operation@1", taskId: response.id, 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, "BeatAPI handle") as unknown as Handle;
+        const route = beatApiRouteForCapability(context.need.capability);
+        assert(route !== undefined && handle.contract === "hypit.beatapi-operation@1" && handle.route === route.key, "BeatAPI handle is invalid");
+        const receipt = { id: handle.taskId };
+        if (Date.now() - handle.startedAt > maxOperationMs) {
+          return { status: "failed", receipt, failure: { code: "BEATAPI_OPERATION_TIMEOUT", message: `BeatAPI 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 (pendingStatuses.includes(status)) {
+          return { ...wakeAfter(canonicalize(handle), pollIntervalMs, Date.now(), { phase: status }), receipt };
+        }
+        const rejected = beatApiTaskFailure(task, handle.taskId);
+        if (rejected !== undefined) return { ...failure(rejected), receipt };
+        assert(status === "succeeded", `BeatAPI returned unknown task status ${status}`);
+        const media = object(task.output, "BeatAPI task output").media;
+        assert(Array.isArray(media) && media.length > 0, "BeatAPI task succeeded without output media");
+        const urls = media.map((item, index) => httpsUrl(object(item, `BeatAPI output ${index + 1}`).url, `BeatAPI output ${index + 1}`));
+        return { status: "ready", handle: canonicalize({ ...handle, urls }), receipt };
+      } catch (error) {
+        return failure(error);
+      }
+    },
+    async collect(context) {
+      try {
+        const handle = object(context.handle, "BeatAPI handle") as unknown as Handle;
+        const route = beatApiRouteForCapability(context.need.capability);
+        assert(route !== undefined && handle.route === route.key && Array.isArray(handle.urls), "BeatAPI 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 createBeatApiProvider(options: CreateBeatApiProviderOptions = {}) {
+  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, `BeatAPI ${name} must be a positive integer`);
+  }
+  const client = new BeatApiClient(apiBaseUrl(options.baseUrl ?? "https://api.beatapi.io"), requestTimeoutMs, options.fetch ?? globalThis.fetch);
+  const asyncEndpoint = endpoint(client, options.pollIntervalMs ?? 10_000, operationTimeoutMs, options.publicAssetUrl);
+  return defineEndpointPackage({
+    module: beatApiProviderModuleRef, facet: "gateway", instance: options.instance ?? "beatapi.default", pool: options.pool ?? options.instance ?? "beatapi.default",
+    pricing: { kind: "page", url: "https://docs.beatapi.io/pricing" },
+    credentials: { apiKey: options.apiKey ?? credentialRef("os", "beatapi.api-key") },
+    credentialInputs: { apiKey: { label: "BeatAPI API key" } },
+    defaultConcurrency: options.defaultConcurrency ?? 4,
+    ...(options.actionLimits === undefined ? {} : { actionLimits: options.actionLimits }),
+    capabilities: beatApiRoutes.map((route) => ({
+      capability: route.capability, returns: route.returns, lifecycle: "asynchronous" as const, endpoint: asyncEndpoint, capacity: route.capability.name, supports: route.supports,
+    })),
+  });
+}

package/packages/provider-beatapi/src/routes.ts

@@ -0,0 +1,127 @@
+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 { beatApiMappings } from "./mapping.js";
+
+export type BeatApiPreparedRequest = {
+  readonly model: string;
+  readonly media: "image" | "video";
+  readonly compile: (resolve: GenerationArtifactUrlResolver) => Promise<Record<string, unknown>>;
+};
+
+export type BeatApiRoute = GenerationWireMapping & {
+  readonly key: string;
+  readonly returns: TypeRef;
+  readonly supports: (request: EndpointRequest) => EndpointSupport;
+  readonly prepare: (constraints: CanonicalValue) => BeatApiPreparedRequest;
+  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;
+}
+
+/** Ratios the Nano Banana 2 model package offers that BeatAPI's schema for it does not list. */
+const NANO_BANANA_2_UNAVAILABLE: readonly string[] = ["1:4", "4:1", "1:8", "8:1"];
+
+/** BeatAPI's documented input ranges per model, checked before any reference is uploaded. */
+function rejection(mapping: GenerationWireMapping, request: GenerationRequest): string | undefined {
+  const { name } = mapping.capability;
+  const model = selectWireModelForRequest(mapping, request);
+  const ratio = scalar(request, "aspectRatio");
+  const resolution = scalar(request, "resolution");
+  if (mapping.capability.module.name === "@hypit/seedance") {
+    if (scalar(request, "webSearch") === true) return `BeatAPI ${model} has no web_search field`;
+    if (name === "seedance-2-mini" && scalar(request, "generateAudio") === true) {
+      return "BeatAPI seedance-2-mini renders no generated audio";
+    }
+    if (name === "seedance-2" && resolution === "1080p" && count(request, "referenceImage") > 0) {
+      return "BeatAPI seedance-2 does not render 1080p with reference images";
+    }
+    if (name === "seedance-2.5" && scalar(request, "duration") === -1) {
+      return "BeatAPI seedance-2.5 takes a duration of 4 to 30 seconds, not automatic";
+    }
+  }
+  if (name === "minimax-h3" && count(request, "lastFrame") > 0 && count(request, "firstFrame") === 0) {
+    return "BeatAPI minimax-h3 orders its images first then last, so a last frame needs a first frame";
+  }
+  if (name === "grok-imagine-video-1.5-preview" && resolution === "1080p" && count(request, "images") > 1) {
+    return "BeatAPI grok-imagine-video-1.5 accepts at most one image at 1080p";
+  }
+  if (name === "gpt-image-2" && scalar(request, "background") !== undefined) {
+    return "BeatAPI gpt-image-2 has no background field";
+  }
+  if (name === "nano-banana-2") {
+    if (count(request, "images") > 10) return "BeatAPI nano-banana-2 accepts up to ten reference images";
+    if (NANO_BANANA_2_UNAVAILABLE.includes(String(ratio))) {
+      return `BeatAPI nano-banana-2 does not render ${String(ratio)}`;
+    }
+  }
+  return undefined;
+}
+
+/** Fields the model package states that BeatAPI names differently, spells differently or omits. */
+function normalize(mapping: GenerationWireMapping, input: Record<string, unknown>): Record<string, unknown> {
+  const { name } = mapping.capability;
+  // BeatAPI carries the opening and closing frames as one ordered array.
+  const frames = [input.first_frame, input.last_frame].filter((item): item is string => typeof item === "string");
+  delete input.first_frame;
+  delete input.last_frame;
+  if (frames.length > 0) input.images = frames;
+  if (input.web_search === false) delete input.web_search;
+  if (name === "seedance-2-mini" && input.generate_audio === false) delete input.generate_audio;
+  if (name === "nano-banana-2" && input.output_format === "jpg") input.output_format = "jpeg";
+  return input;
+}
+
+function capabilityKey(capability: CapabilityRef): string {
+  return `${capability.module.name}@${capability.module.version}#${capability.name}`;
+}
+
+export const beatApiRoutes: readonly BeatApiRoute[] = beatApiMappings.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,
+      media: mapping.result === "image" ? "image" : "video",
+      compile: async (resolve) => ({
+        model,
+        ...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(beatApiRoutes.map((route) => [route.key, route]));
+
+export function beatApiRouteForCapability(capability: CapabilityRef): BeatApiRoute | undefined {
+  return byCapability.get(capabilityKey(capability));
+}

package/packages/provider-hiapi/README.md

@@ -38,9 +38,7 @@ Service limits this Provider reports as unsupported before submitting:
 - Grok Imagine renders 480p or 720p; `grok-imagine-1.5/image-to-video` animates exactly one image.
 
 Seedance visual references require `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.
+transmits nothing for it, since HiAPI has no field for it.
 
 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

package/packages/provider-monid/README.md

@@ -27,8 +27,6 @@ The Seedance endpoints add `generate_audio`. Monid documents no web search field
 `web-search="true"` is unsupported, and Seedance 2.5 frame mode (`first-frame` present) requires
 `aspect-ratio="adaptive"`. Seedance visual references require `person-reference`; the Provider
 accepts the declaration and transmits nothing for it, since the endpoint has no field for it.
-Seedance rejects reference images and videos that contain a real human face; Monid offers no way to
-register authorized portrait material, so such a request fails with the upstream moderation error.
 
 MiniMax H3 names its model in the body and takes neither of those two fields. The endpoint requires
 a resolution, so a request that states none is sent at `2K`, the resolution the HypiHub Provider

package/packages/studio/src/server.ts

@@ -722,12 +722,27 @@ export function studioPlugin(options: StudioPluginOptions): Plugin {
             response.end();
             return;
           }
-          response.statusCode = 200;
+          const size = file.bytes.byteLength;
+          let range: BuildResultFileRange | undefined;
+          try {
+            range = requestedByteRange(request.headers.range, size);
+          } catch (error) {
+            if (!(error instanceof RangeError)) throw error;
+            response.statusCode = 416;
+            response.setHeader("content-range", `bytes */${size}`);
+            response.end();
+            return;
+          }
+          response.statusCode = range === undefined ? 200 : 206;
           response.setHeader("content-type", file.mediaType);
+          response.setHeader("content-length", String(range === undefined ? size : range.endExclusive - range.start));
           response.setHeader("cache-control", "no-store");
           response.setHeader("accept-ranges", "bytes");
+          if (range !== undefined) {
+            response.setHeader("content-range", `bytes ${range.start}-${range.endExclusive - 1}/${size}`);
+          }
           if (request.method === "HEAD") response.end();
-          else response.end(Buffer.from(file.bytes));
+          else response.end(range === undefined ? file.bytes : file.bytes.subarray(range.start, range.endExclusive));
           return;
         }
         if (url.pathname === "/__studio/artifact") {