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.
TypeScript agentic-aiaiai-agentsai-videocompilerdslffmpeggenerative-aillmmarkup-languagemonorepoplugin-systemprogramming-languagetext-to-videotypescriptvideovideo-automationvideo-clonevideo-editingvideo-generation
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.mdindex 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/pacserves MiniMax H3, Grok Imagine 1.5, GPT Image 2 and Nano Banana. Pollo takes reference media bypublic 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.mdindex 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.jsonindex 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.mdnew file mode 100644index 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.jsonnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.yamlindex 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':