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(provider-hypihub): upload media through presigned S3 multipart

rpone7a5de0ddb515
diff --git a/packages/provider-hypihub/README.md b/packages/provider-hypihub/README.md
index 6d9b90b1..9638f7c7 100644
--- a/packages/provider-hypihub/README.md
+++ b/packages/provider-hypihub/README.md
@@ -37,9 +37,18 @@ callers can still use the exported `createHypiHubGeminiGenerator`. Run `hypit au
an existing `/v1`/`/v1beta` base is accepted) only when choosing HypiHub. The Runtime Provider also
accepts the origin or either versioned base and normalizes it to `/v1`; missing or insufficient user
credentials should be resolved at [hypit.ai](https://hypit.ai). Referenced image, audio and video
-Artifacts are uploaded automatically through `POST /v1/files`, then their returned HTTPS capability
-URLs are used in image and video requests. Uploads are deduplicated by Artifact digest within one
-Runtime operation. Embedded callers may override that transport with `publicAssetUrl`.
+Artifacts are uploaded automatically. The Provider first sends the file size and SHA-256 to
+`POST /v1/files/uploads`; HypiHub keeps small files on the established `POST /v1/files` route and
+returns a private S3 multipart policy for large files. Large parts are then uploaded concurrently
+through short-lived S3 Transfer Acceleration URLs, so the media bytes do not make an extra trip
+through the HypiHub application server. A failed part alone is retried with a fresh signed URL.
+
+The server owns the size threshold, part size, concurrency, and URL lifetime. Clients do not need
+to duplicate that policy. `uploadPartTimeoutMs` (default five minutes) and `uploadPartAttempts`
+(default three) only control client retry behavior. During a rolling server upgrade, an exact 404
+from the policy endpoint falls back to the established multipart API. Signed S3 URLs are never
+included in Provider error messages. Uploads remain deduplicated by Artifact digest within one
+Runtime operation. Embedded callers may override the entire transport with `publicAssetUrl`.
The provider also serves `@hypit/whisperx#whisperx-alignment` through HypiHub's synchronous
`/v1/audio/transcriptions` endpoint using `victor-upmeet/whisperx`. It always requests
diff --git a/packages/provider-hypihub/src/provider.ts b/packages/provider-hypihub/src/provider.ts
index b2fe6820..e0a40b65 100644
--- a/packages/provider-hypihub/src/provider.ts
+++ b/packages/provider-hypihub/src/provider.ts
@@ -1,3 +1,5 @@
+import { createHash } from "node:crypto";
+
import type { AsyncEndpoint, EndpointFulfillment, EndpointInvocationContext, EndpointPollContext, EndpointStartContext, EndpointOutcome, ImmediateEndpointHandler } from "@hypit/endpoint-kit";
import { defineEndpointPackage, wakeAfter } from "@hypit/endpoint-kit";
import { geminiCapabilities, geminiModels, verifyGeminiRequest } from "@hypit/gemini";
@@ -24,6 +26,10 @@ export type CreateHypiHubProviderOptions = {
readonly defaultConcurrency?: number;
readonly pollIntervalMs?: number;
readonly requestTimeoutMs?: number;
+ /** Timeout for one S3 multipart PUT. Defaults to five minutes. */
+ readonly uploadPartTimeoutMs?: number;
+ /** Attempts per S3 part; only a failed part is retried. Defaults to three. */
+ readonly uploadPartAttempts?: number;
/** Expose HypiHub VoiceDesign. Defaults to enabled; set false only for an explicit alternate Provider. */
readonly audio?: boolean;
/** HypiHub transcription model used for the WhisperX alignment capability. */
@@ -85,6 +91,15 @@ function dataUrl(bytes: Uint8Array, mediaType: string): string {
return `data:${mediaType};base64,${Buffer.from(bytes).toString("base64")}`;
}
+function requiredString(value: unknown, subject: string): string {
+ assert(typeof value === "string" && value.length > 0, `${subject} is missing`);
+ return value;
+}
+function requiredInteger(value: unknown, subject: string): number {
+ assert(typeof value === "number" && Number.isSafeInteger(value) && value > 0, `${subject} is invalid`);
+ return value;
+}
+
async function resolveArtifactInline(artifacts: ArtifactStore, artifact: BlobRef): Promise<string> {
const bytes = await artifacts.get(artifact.digest);
assert(bytes !== undefined, `HypiHub reference artifact ${artifact.digest} is unavailable`);
@@ -104,8 +119,12 @@ class HypiHubClient {
readonly baseUrl: string;
readonly timeout: number;
readonly fetcher: typeof globalThis.fetch;
- constructor(options: { readonly baseUrl: string; readonly timeout: number; readonly fetcher: typeof globalThis.fetch }) {
- this.baseUrl = options.baseUrl.replace(/\/$/u, ""); this.timeout = options.timeout; this.fetcher = options.fetcher;
+ readonly uploadPartTimeout: number;
+ readonly uploadPartAttempts: number;
+ constructor(options: { readonly baseUrl: string; readonly timeout: number; readonly uploadPartTimeout: number; readonly uploadPartAttempts: number; readonly fetcher: typeof globalThis.fetch }) {
+ this.baseUrl = options.baseUrl.replace(/\/$/u, ""); this.timeout = options.timeout;
+ this.uploadPartTimeout = options.uploadPartTimeout; this.uploadPartAttempts = options.uploadPartAttempts;
+ this.fetcher = options.fetcher;
}
async json(path: string, apiKey: string, init: RequestInit = {}): Promise<Record<string, unknown>> {
const controller = new AbortController(); const timer = setTimeout(() => controller.abort(), this.timeout);
@@ -131,21 +150,131 @@ class HypiHubClient {
}
throw lastError instanceof Error ? lastError : new Error(String(lastError));
}
- async upload(artifact: BlobRef, artifacts: ArtifactStore, apiKey: string): Promise<string> {
- const bytes = await artifacts.get(artifact.digest);
- assert(bytes !== undefined, `HypiHub reference artifact ${artifact.digest} is unavailable`);
- assert(bytes.byteLength === artifact.size, `HypiHub reference artifact ${artifact.digest} size differs`);
+ private async uploadForm(artifact: BlobRef, bytes: Uint8Array, apiKey: string): Promise<string> {
+ const filename = `${artifact.digest.slice("sha256:".length)}.${mediaExtension(artifact.mediaType)}`;
const form = new FormData();
const copy = new ArrayBuffer(bytes.byteLength);
new Uint8Array(copy).set(bytes);
- form.append("file", new Blob([copy], { type: artifact.mediaType }),
- `${artifact.digest.slice("sha256:".length)}.${mediaExtension(artifact.mediaType)}`);
+ form.append("file", new Blob([copy], { type: artifact.mediaType }), filename);
form.append("purpose", "reference");
const response = await this.json("/files", apiKey, { method: "POST", body: form });
assert(typeof response.url === "string" && /^https:\/\//iu.test(response.url),
"HypiHub file upload returned no HTTPS URL");
return response.url;
}
+ private async signParts(uploadId: string, declarations: readonly { readonly part_number: number; readonly bytes: number; readonly checksum_sha256: string }[], apiKey: string): Promise<Map<number, Record<string, unknown>>> {
+ const response = await this.json(`/files/uploads/${encodeURIComponent(uploadId)}/parts`, apiKey, {
+ method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify({ parts: declarations }),
+ });
+ assert(Array.isArray(response.parts), "HypiHub part signing response has no parts");
+ const signed = new Map<number, Record<string, unknown>>();
+ for (const raw of response.parts) {
+ const item = object(raw, "HypiHub signed upload part");
+ const partNumber = requiredInteger(item.part_number, "HypiHub signed upload part number");
+ requiredString(item.url, "HypiHub signed upload URL");
+ object(item.headers, "HypiHub signed upload headers");
+ signed.set(partNumber, item);
+ }
+ assert(signed.size === declarations.length, "HypiHub signed an incomplete part set");
+ return signed;
+ }
+ private async putPart(uploadId: string, declaration: { readonly part_number: number; readonly bytes: number; readonly checksum_sha256: string }, initial: Record<string, unknown>, body: Uint8Array, apiKey: string): Promise<{ readonly part_number: number; readonly etag: string; readonly checksum_sha256: string }> {
+ let capability = initial;
+ for (let attempt = 0; attempt < this.uploadPartAttempts; attempt += 1) {
+ if (attempt > 0) {
+ const refreshed = await this.signParts(uploadId, [declaration], apiKey);
+ capability = refreshed.get(declaration.part_number) ?? {};
+ }
+ const controller = new AbortController(); const timer = setTimeout(() => controller.abort(), this.uploadPartTimeout);
+ try {
+ const url = requiredString(capability.url, "HypiHub signed upload URL");
+ const headers = object(capability.headers, "HypiHub signed upload headers");
+ // Copy the view into a plain ArrayBuffer so this stays compatible with
+ // both Node's fetch implementation and the DOM BodyInit type.
+ const payload = new ArrayBuffer(body.byteLength);
+ new Uint8Array(payload).set(body);
+ const response = await this.fetcher(url, { method: "PUT", headers: headers as Record<string, string>, body: payload, signal: controller.signal });
+ if (!response.ok) throw new Error(`S3 rejected upload part ${declaration.part_number} with HTTP ${response.status}`);
+ const etag = response.headers.get("etag");
+ assert(etag !== null && etag.length > 0, `S3 upload part ${declaration.part_number} returned no ETag`);
+ const verified = response.headers.get("x-amz-checksum-sha256");
+ assert(verified === null || verified === declaration.checksum_sha256,
+ `S3 upload part ${declaration.part_number} returned a different checksum`);
+ return { part_number: declaration.part_number, etag, checksum_sha256: declaration.checksum_sha256 };
+ } catch {
+ if (attempt + 1 < this.uploadPartAttempts) await new Promise((resolve) => setTimeout(resolve, 500 * (attempt + 1)));
+ } finally { clearTimeout(timer); }
+ }
+ // Never bubble up a fetch implementation's URL-bearing error: the signed
+ // URL is a short-lived credential and must not enter agent logs/reports.
+ throw new Error(`S3 upload part ${declaration.part_number} failed after ${this.uploadPartAttempts} attempts`);
+ }
+ private async uploadDirect(bytes: Uint8Array, apiKey: string, policy: Record<string, unknown>): Promise<string> {
+ const uploadId = requiredString(policy.upload_id, "HypiHub upload id");
+ const partSize = requiredInteger(policy.part_size, "HypiHub upload part size");
+ const partCount = requiredInteger(policy.part_count, "HypiHub upload part count");
+ const requestedConcurrency = requiredInteger(policy.concurrency, "HypiHub upload concurrency");
+ assert(requestedConcurrency <= 8, "HypiHub upload concurrency exceeds 8");
+ assert(partCount <= 10_000, "HypiHub upload part count exceeds 10000");
+ const concurrency = Math.min(requestedConcurrency, partCount);
+ assert(partCount === Math.ceil(bytes.byteLength / partSize), "HypiHub upload part count differs from the file size");
+ const declarations = Array.from({ length: partCount }, (_, index) => {
+ const start = index * partSize; const part = bytes.subarray(start, Math.min(start + partSize, bytes.byteLength));
+ return { part_number: index + 1, bytes: part.byteLength, checksum_sha256: createHash("sha256").update(part).digest("base64") };
+ });
+ try {
+ const signed = await this.signParts(uploadId, declarations, apiKey);
+ const completed = new Array<{ readonly part_number: number; readonly etag: string; readonly checksum_sha256: string }>(partCount);
+ let cursor = 0;
+ const worker = async (): Promise<void> => {
+ while (cursor < partCount) {
+ const index = cursor; cursor += 1;
+ const declaration = declarations[index];
+ assert(declaration !== undefined, "HypiHub upload part declaration is missing");
+ const start = index * partSize; const body = bytes.subarray(start, Math.min(start + partSize, bytes.byteLength));
+ const capability = signed.get(declaration.part_number);
+ assert(capability !== undefined, `HypiHub upload part ${declaration.part_number} was not signed`);
+ completed[index] = await this.putPart(uploadId, declaration, capability, body, apiKey);
+ }
+ };
+ await Promise.all(Array.from({ length: concurrency }, worker));
+ const response = await this.json(`/files/uploads/${encodeURIComponent(uploadId)}/complete`, apiKey, {
+ method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify({ parts: completed }),
+ });
+ assert(typeof response.url === "string" && /^https:\/\//iu.test(response.url),
+ "HypiHub direct upload returned no HTTPS URL");
+ return response.url;
+ } catch (error) {
+ try { await this.json(`/files/uploads/${encodeURIComponent(uploadId)}`, apiKey, { method: "DELETE" }); } catch { /* S3 lifecycle is the final abort fallback. */ }
+ throw error;
+ }
+ }
+ async upload(artifact: BlobRef, artifacts: ArtifactStore, apiKey: string): Promise<string> {
+ const bytes = await artifacts.get(artifact.digest);
+ assert(bytes !== undefined, `HypiHub reference artifact ${artifact.digest} is unavailable`);
+ assert(bytes.byteLength === artifact.size, `HypiHub reference artifact ${artifact.digest} size differs`);
+ const computed = createHash("sha256").update(bytes).digest("hex");
+ const declared = artifact.digest.startsWith("sha256:") ? artifact.digest.slice("sha256:".length) : "";
+ assert(declared === computed, `HypiHub reference artifact ${artifact.digest} failed its SHA-256 check`);
+ const filename = `${computed}.${mediaExtension(artifact.mediaType)}`;
+ let policy: Record<string, unknown>;
+ try {
+ policy = await this.json("/files/uploads", apiKey, {
+ method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify({
+ filename, bytes: bytes.byteLength, mime_type: artifact.mediaType, purpose: "reference",
+ sha256: computed, head_base64: Buffer.from(bytes.subarray(0, 512)).toString("base64"),
+ }),
+ });
+ } catch (error) {
+ // Rolling upgrades remain safe: an older HypiHub has no policy endpoint,
+ // so only its exact 404 falls back to the established multipart route.
+ if (!(error instanceof Error) || !/HypiHub returned HTTP 404:/u.test(error.message)) throw error;
+ return await this.uploadForm(artifact, bytes, apiKey);
+ }
+ if (policy.upload_mode === "api_multipart") return await this.uploadForm(artifact, bytes, apiKey);
+ assert(policy.upload_mode === "s3_multipart", "HypiHub returned an unknown upload mode");
+ return await this.uploadDirect(bytes, apiKey, policy);
+ }
async transcribe(body: Record<string, unknown>, apiKey: string): Promise<Record<string, unknown>> {
return this.json("/audio/transcriptions", apiKey, {
method: "POST",
@@ -233,7 +362,17 @@ function endpoint(client: HypiHubClient, pollIntervalMs: number, maxOperationMs:
}
export function createHypiHubProvider(options: CreateHypiHubProviderOptions = {}) {
- const client = new HypiHubClient({ baseUrl: apiBaseUrl(options.baseUrl ?? "https://hypit.ai/v1"), timeout: options.requestTimeoutMs ?? 300_000, fetcher: options.fetch ?? globalThis.fetch });
+ const uploadPartAttempts = options.uploadPartAttempts ?? 3;
+ assert(Number.isInteger(uploadPartAttempts) && uploadPartAttempts >= 1 && uploadPartAttempts <= 8,
+ "HypiHub uploadPartAttempts must be within 1..8");
+ const uploadPartTimeout = options.uploadPartTimeoutMs ?? 5 * 60_000;
+ assert(Number.isSafeInteger(uploadPartTimeout) && uploadPartTimeout > 0,
+ "HypiHub uploadPartTimeoutMs must be a positive integer");
+ const client = new HypiHubClient({
+ baseUrl: apiBaseUrl(options.baseUrl ?? "https://hypit.ai/v1"), timeout: options.requestTimeoutMs ?? 300_000,
+ uploadPartTimeout, uploadPartAttempts,
+ fetcher: options.fetch ?? globalThis.fetch,
+ });
const asyncEndpoint = endpoint(client, options.pollIntervalMs ?? 10_000, 20 * 60_000, options.publicAssetUrl);
const audioEndpoint: ImmediateEndpointHandler = async (context) => {
try {
diff --git a/packages/provider-hypihub/test/provider.test.ts b/packages/provider-hypihub/test/provider.test.ts
index 4633f609..0e88ada3 100644
--- a/packages/provider-hypihub/test/provider.test.ts
+++ b/packages/provider-hypihub/test/provider.test.ts
@@ -68,6 +68,13 @@ test("HypiHub uploads referenced Artifacts once, submits their HTTPS URLs, and p
const fakeFetch: typeof globalThis.fetch = async (input, init) => {
const url = String(input);
calls.push(url);
+ if (url.endsWith("/v1/files/uploads")) {
+ assert.equal(init?.method, "POST");
+ const body = JSON.parse(String(init?.body)) as Record<string, unknown>;
+ assert.equal(body.bytes, 3);
+ assert.equal(typeof body.sha256, "string");
+ return Response.json({ upload_mode: "api_multipart" });
+ }
if (url.endsWith("/v1/files")) {
assert.equal(init?.method, "POST");
assert.equal((init?.headers as Record<string, string>).authorization, "Bearer test-key");
@@ -114,7 +121,7 @@ test("HypiHub uploads referenced Artifacts once, submits their HTTPS URLs, and p
if (started.status !== "pending") return;
const completed = await endpoint.poll({ ...common, handle: started.handle });
assert.equal(completed.status, "completed");
- assert.equal(calls.length, 6);
+ assert.equal(calls.length, 7);
});
test("HypiHub fulfills Gemini through the Runtime endpoint and uploads every media Artifact", async () => {
@@ -136,6 +143,9 @@ test("HypiHub fulfills Gemini through the Runtime endpoint and uploads every med
const registry = new EndpointRegistry();
await createHypiHubProvider({ fetch: async (input, init) => {
const url = String(input);
+ if (url.endsWith("/v1/files/uploads")) {
+ return Response.json({ upload_mode: "api_multipart" });
+ }
if (url.endsWith("/v1/files")) {
assert.ok(init?.body instanceof FormData);
const file = init.body.get("file");
@@ -164,3 +174,62 @@ test("HypiHub fulfills Gemini through the Runtime endpoint and uploads every med
{ fileData: { mimeType: "video/mp4", fileUri: "https://hypit.ai/files/2" } },
] }]);
});
+
+test("HypiHub splits a large Artifact across accelerated S3 parts and retries only the failed part", async () => {
+ const artifacts = new MemoryArtifactStore();
+ const reference = await artifacts.put(new Uint8Array([1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12]), "video/mp4");
+ const request = need(sealSeedanceRequest("seedance-2-mini", {
+ prompt: ["Continue the motion."], referenceVideo: [{ role: "video", artifact: reference }],
+ resolution: ["720p"], aspectRatio: ["16:9"], duration: [5], generateAudio: [false], webSearch: [false],
+ }) as unknown as CanonicalValue);
+ const signedBatches: number[][] = [];
+ const putAttempts = new Map<number, number>();
+ let completedParts: unknown;
+ const fakeFetch: typeof globalThis.fetch = async (input, init) => {
+ const url = String(input);
+ if (url.endsWith("/v1/files/uploads")) {
+ const body = JSON.parse(String(init?.body)) as Record<string, unknown>;
+ assert.equal(body.bytes, 12);
+ assert.equal(body.mime_type, "video/mp4");
+ assert.equal(Buffer.from(String(body.head_base64), "base64").byteLength, 12);
+ return Response.json({
+ upload_mode: "s3_multipart", upload_id: "up_test", asset_id: "as_test",
+ part_size: 5, part_count: 3, concurrency: 2,
+ }, { status: 201 });
+ }
+ if (url.endsWith("/v1/files/uploads/up_test/parts")) {
+ const body = JSON.parse(String(init?.body)) as { parts: Array<{ part_number: number; checksum_sha256: string }> };
+ signedBatches.push(body.parts.map((part) => part.part_number));
+ return Response.json({ parts: body.parts.map((part) => ({
+ part_number: part.part_number,
+ url: `https://private.s3-accelerate.amazonaws.com/opaque-part-${part.part_number}?signature=secret`,
+ headers: { "content-length": part.part_number === 3 ? "2" : "5", "x-amz-checksum-sha256": part.checksum_sha256 },
+ })) });
+ }
+ if (url.startsWith("https://private.s3-accelerate.amazonaws.com/")) {
+ const match = /opaque-part-(\d+)/u.exec(url); assert.ok(match);
+ const partNumber = Number(match[1]); const attempt = (putAttempts.get(partNumber) ?? 0) + 1;
+ putAttempts.set(partNumber, attempt);
+ if (partNumber === 2 && attempt === 1) return new Response("retry", { status: 503 });
+ const headers = init?.headers as Record<string, string>;
+ return new Response(null, { status: 200, headers: { etag: `\"part-${partNumber}\"`, "x-amz-checksum-sha256": headers["x-amz-checksum-sha256"] ?? "" } });
+ }
+ if (url.endsWith("/v1/files/uploads/up_test/complete")) {
+ completedParts = (JSON.parse(String(init?.body)) as Record<string, unknown>).parts;
+ return Response.json({ url: "https://hypit.ai/files/as_reference.mp4" });
+ }
+ if (url.endsWith("/v1/models/bytedance%2Fseedance-2-mini")) return Response.json({ endpoints: ["videos"] });
+ if (url.endsWith("/v1/videos")) return Response.json({ id: "job_direct_upload", status: "queued" });
+ throw new Error(`Unexpected URL ${url}`);
+ };
+ const endpoint = await endpointFor(request, fakeFetch);
+ const started = await endpoint.start({
+ command: { kind: "fulfill-need", id: "command:direct-upload", need: request },
+ need: request, artifacts, credentials: { apiKey: { secret: "test-key" } }, operation: "operation:direct-upload",
+ });
+ assert.equal(started.status, "pending");
+ assert.deepEqual(signedBatches, [[1, 2, 3], [2]]);
+ assert.deepEqual([...putAttempts.entries()].sort(), [[1, 1], [2, 2], [3, 1]]);
+ assert.ok(Array.isArray(completedParts));
+ assert.equal(completedParts.length, 3);
+});