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(beatapi): serve the installed video and image models on BeatAPI (#331)

Sharky Wanga2d13d535d37
diff --git a/docs/guide/service-partners.md b/docs/guide/service-partners.md
index 97b0fb4f..ff980ab9 100644
--- a/docs/guide/service-partners.md
+++ b/docs/guide/service-partners.md
@@ -43,6 +43,16 @@ paths. [`@hypit/provider-pollo`](https://github.com/hypit-ai/hypit/blob/main/pac
serves MiniMax H3, Grok Imagine 1.5, GPT Image 2 and Nano Banana. Pollo takes reference media by
public URL only, so a request with reference media needs a URL the embedding caller supplies.
+### BeatAPI
+
+[BeatAPI](https://docs.beatapi.io/quick-guide) offers video and image models through one
+asynchronous task API.
+[`@hypit/provider-beatapi`](https://github.com/hypit-ai/hypit/blob/main/packages/provider-beatapi/README.md)
+serves the Seedance 2.0 and 2.5 models, MiniMax H3, Grok Imagine 1.5, GPT Image 2 and Nano Banana,
+and uploads reference media through BeatAPI's file endpoint. Its
+[video](https://docs.beatapi.io/video-api) and [image](https://docs.beatapi.io/image-api) model
+indexes list the rest.
+
### Monid
[Monid](https://monid.ai) is a Hypit service partner.
diff --git a/docs/zh/guide/service-partners.md b/docs/zh/guide/service-partners.md
index 92d6c4b0..0dc67119 100644
--- a/docs/zh/guide/service-partners.md
+++ b/docs/zh/guide/service-partners.md
@@ -37,6 +37,14 @@ HypiHub 是 Hypit 推荐的集成托管服务,提供已支持的生成与 Whis
提供 MiniMax H3、Grok Imagine 1.5、GPT Image 2 和 Nano Banana。
Pollo 只接受公网 URL 形式的参考素材,带参考素材的请求需要由嵌入方提供 URL。
+### BeatAPI
+
+[BeatAPI](https://docs.beatapi.io/quick-guide) 通过一个异步任务接口提供视频和图片模型。
+[`@hypit/provider-beatapi`](https://github.com/hypit-ai/hypit/blob/main/packages/provider-beatapi/README.md)
+提供 Seedance 2.0、2.5 系列、MiniMax H3、Grok Imagine 1.5、GPT Image 2 和 Nano Banana,
+并通过 BeatAPI 的文件接口上传参考素材。
+其余模型见它的[视频](https://docs.beatapi.io/video-api)与[图片](https://docs.beatapi.io/image-api)模型索引。
+
### Monid
[Monid](https://monid.ai) 是 Hypit 的服务合作方。
diff --git a/package.json b/package.json
index f999197c..a01d6795 100644
--- a/package.json
+++ b/package.json
@@ -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:*",
diff --git a/packages/provider-beatapi/README.md b/packages/provider-beatapi/README.md
new file mode 100644
index 00000000..1e3fa045
--- /dev/null
+++ b/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.
diff --git a/packages/provider-beatapi/package.json b/packages/provider-beatapi/package.json
new file mode 100644
index 00000000..0fe75a91
--- /dev/null
+++ b/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:*"
+ }
+}
diff --git a/packages/provider-beatapi/src/activation.ts b/packages/provider-beatapi/src/activation.ts
new file mode 100644
index 00000000..9645b5c0
--- /dev/null
+++ b/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;
diff --git a/packages/provider-beatapi/src/errors.ts b/packages/provider-beatapi/src/errors.ts
new file mode 100644
index 00000000..7ab0cd8a
--- /dev/null
+++ b/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)}`}`);
+}
diff --git a/packages/provider-beatapi/src/index.ts b/packages/provider-beatapi/src/index.ts
new file mode 100644
index 00000000..f608090b
--- /dev/null
+++ b/packages/provider-beatapi/src/index.ts
@@ -0,0 +1,2 @@
+export { createBeatApiProvider, beatApiProviderModuleRef } from "./provider.js";
+export type { CreateBeatApiProviderOptions } from "./provider.js";
diff --git a/packages/provider-beatapi/src/mapping.ts b/packages/provider-beatapi/src/mapping.ts
new file mode 100644
index 00000000..a56d2202
--- /dev/null
+++ b/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" },
+ },
+ })),
+];
diff --git a/packages/provider-beatapi/src/provider.ts b/packages/provider-beatapi/src/provider.ts
new file mode 100644
index 00000000..48b47eb0
--- /dev/null
+++ b/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,
+ })),
+ });
+}
diff --git a/packages/provider-beatapi/src/routes.ts b/packages/provider-beatapi/src/routes.ts
new file mode 100644
index 00000000..d60dd784
--- /dev/null
+++ b/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));
+}
diff --git a/packages/provider-beatapi/test/routes.test.ts b/packages/provider-beatapi/test/routes.test.ts
new file mode 100644
index 00000000..c9041de7
--- /dev/null
+++ b/packages/provider-beatapi/test/routes.test.ts
@@ -0,0 +1,66 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { assertMappingCoversPorts } from "@hypit/generation";
+import type { BlobRef, CanonicalValue } from "@hypit/protocol";
+import { gptImage2Ports } from "@hypit/gpt-image";
+import { grokImaginePorts } from "@hypit/grok-imagine";
+import { minimaxH3Ports, sealMinimaxH3Request } from "@hypit/minimax-h3";
+import { nanoBananaPorts } from "@hypit/nano-banana";
+import { seedancePorts, sealSeedanceRequest } from "@hypit/seedance";
+
+import { beatApiMappings } from "../src/mapping.js";
+import { beatApiRouteForCapability } from "../src/routes.js";
+
+const image: BlobRef = { kind: "blob", resource: "res_beatapi_1", size: 3, mediaType: "image/png" };
+const resolve = async (artifact: { resource: string }) => `https://media.beatapi.io/inputs/${artifact.resource}.png`;
+const route = (module: string, name: string) => beatApiRouteForCapability({ module: { name: module, version: "1" }, name })!;
+const constraints = (request: unknown) => request as CanonicalValue;
+
+test("every BeatAPI mapping covers its model's ports", () => {
+ const tables = {
+ ...seedancePorts, ...grokImaginePorts, ...nanoBananaPorts,
+ "minimax-h3": minimaxH3Ports, "gpt-image-2": gptImage2Ports,
+ };
+ for (const mapping of beatApiMappings) {
+ assertMappingCoversPorts(tables[mapping.capability.name as keyof typeof tables], mapping);
+ }
+});
+
+test("frames travel as one ordered images array", async () => {
+ const minimax = route("@hypit/minimax-h3", "minimax-h3");
+ const request = sealMinimaxH3Request({
+ prompt: ["Move smoothly from the opening portrait to the final product reveal."],
+ duration: [5], resolution: ["768P"],
+ firstFrame: [{ role: "image", artifact: image }],
+ lastFrame: [{ role: "image", artifact: { ...image, resource: "res_beatapi_2" } }],
+ });
+ assert.deepEqual(await minimax.prepare(constraints(request)).compile(resolve), {
+ model: "minimax-h3",
+ prompt: "Move smoothly from the opening portrait to the final product reveal.",
+ duration: 5,
+ resolution: "768P",
+ images: ["https://media.beatapi.io/inputs/res_beatapi_1.png", "https://media.beatapi.io/inputs/res_beatapi_2.png"],
+ });
+});
+
+test("Seedance ports BeatAPI has no field for are dropped when off and refused when on", async () => {
+ const mini = route("@hypit/seedance", "seedance-2-mini");
+ const ports = {
+ prompt: ["A handheld tracking shot through a crowded neon night market."],
+ duration: [5], resolution: ["720p"], aspectRatio: ["adaptive"],
+ generateAudio: [false], webSearch: [false],
+ };
+ assert.deepEqual(await mini.prepare(constraints(sealSeedanceRequest("seedance-2-mini", ports))).compile(resolve), {
+ model: "seedance-2-mini",
+ prompt: "A handheld tracking shot through a crowded neon night market.",
+ duration: 5,
+ resolution: "720p",
+ aspect_ratio: "adaptive",
+ });
+
+ for (const stated of [{ generateAudio: [true] }, { webSearch: [true] }]) {
+ const request = sealSeedanceRequest("seedance-2-mini", { ...ports, ...stated });
+ assert.equal(mini.supports({ capability: mini.capability, returns: mini.returns, constraints: constraints(request) }).status,
+ "unsupported");
+ }
+});
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index e379f8b4..0a93d843 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -186,6 +186,9 @@ importers:
'@hypit/protocol':
specifier: workspace:*
version: link:packages/protocol
+ '@hypit/provider-beatapi':
+ specifier: workspace:*
+ version: link:packages/provider-beatapi
'@hypit/provider-hiapi':
specifier: workspace:*
version: link:packages/provider-hiapi
@@ -2245,6 +2248,40 @@ importers:
packages/protocol: {}
+ packages/provider-beatapi:
+ dependencies:
+ '@hypit/endpoint-kit':
+ specifier: workspace:*
+ version: link:../endpoint-kit
+ '@hypit/generation':
+ specifier: workspace:*
+ version: link:../generation
+ '@hypit/protocol':
+ specifier: workspace:*
+ version: link:../protocol
+ '@hypit/runtime':
+ specifier: workspace:*
+ version: link:../runtime
+ '@hypit/runtime-kit':
+ specifier: workspace:*
+ version: link:../runtime-kit
+ devDependencies:
+ '@hypit/gpt-image':
+ specifier: workspace:*
+ version: link:../gpt-image
+ '@hypit/grok-imagine':
+ specifier: workspace:*
+ version: link:../grok-imagine
+ '@hypit/minimax-h3':
+ specifier: workspace:*
+ version: link:../minimax-h3
+ '@hypit/nano-banana':
+ specifier: workspace:*
+ version: link:../nano-banana
+ '@hypit/seedance':
+ specifier: workspace:*
+ version: link:../seedance
+
packages/provider-hiapi:
dependencies:
'@hypit/endpoint-kit':