asset

What it does

Some video providers refuse a plain photo of a real face. They take the same face when it is registered first, as an asset in the provider's own account, and the video request names the asset id instead of sending the image. asset is the task plugin for that registration step.

It owns the contract every asset provider implements: AssetRequest, AssetRecord, AssetResult, AssetJobPoll and AssetHandler. It exposes a small typed facade, app.asset.*.

Providers that serve this task today:

How it works

Registration is its own step. An asset item runs before any video item that uses it. It is not a retry after a refusal: no provider registers a face on the fly, and no provider falls back to sending the raw photo.

The stored record has the MIME type ASSET_MIME, application/vnd.moku.asset+json. When the runner resolves a $ref to a done asset item, the video handler gets a file with this MIME type. That is how a video provider tells an asset from an image. A .json $file stays application/json: it never becomes an asset. On export the record is written as <label>.json.

There is no execute. Every provider implements submit + poll. A refused registration is a failed poll, or a throw, whose error carries kind: "content-policy".

The plugin is stateless. No lifecycle hooks, no events.

Config

pluginConfigs.asset.

import { createApp } from "@moku-labs/ai";

const app = createApp({
  pluginConfigs: { asset: { defaultProvider: "ark", pollIntervalMs: 3000 } }
});

API

Mounted at app.asset, reachable with ctx.require(assetPlugin).

register parses a done poll's body with parseAssetRecord and returns the record. A failed poll throws its error unchanged. An abort during the wait rejects at once with the signal's reason.

AssetRequest

AssetFile is { path: string; mimeType: string; hash: string }, the shape of the runner's resolved file.

AssetRecord

Package exports

Example

The durable path is a build file. Register the portrait in an asset item, then $ref it from the video items:

version: 1
name: mira
items:
  - id: face-mira
    task: asset
    provider: ark
    input:
      image: { $file: faces/mira.png }
      url: "https://cdn.example/faces/mira.png"
  - id: clip-01
    task: video
    provider: ark
    input:
      model: dreamina-seedance-2-5-260628
      prompt: "image 1 walks into the rain"
      refs: [{ $ref: face-mira }]
      seconds: 10
      resolution: 720p
      aspect: "9:16"

• face-mira runs first. Its artifact is the AssetRecord JSON.
• clip-01 gets a ref with mimeType === ASSET_MIME. The video provider reads the record and sends the asset id, not the photo.
• A second run reuses both items at no cost. So does another build file with the same face and URL.
• If the provider refuses the portrait, face-mira is flagged and clip-01 stays queued. The runner logs runner:blocked.
• A video provider that cannot use assets refuses the ref before any upload. fal does this.

Register again

The artifact key covers the image hash, url, name, group, groupName and params. Unchanged input means the stored record is reused, even when the provider has since deleted the asset. To register the same portrait again, bump params.generation. params sits next to input in a build item:

  - id: face-mira
    task: asset
    provider: ark
    input:
      image: { $file: faces/mira.png }
      url: "https://cdn.example/faces/mira.png"
    params: { generation: 2 }

The new key misses the cache, so the item registers again. Every video item that $refs it gets a new key too, so those clips render again with the new asset.

The facade is the direct path. Nothing is journaled and nothing is cached:

import { app } from "./app";

await app.start();

const image = { path: "faces/mira.png", mimeType: "image/png", hash: "a".repeat(64) };

console.log(app.asset.estimate({ image })); // { usd: 0 }

const record = await app.asset.register({ image, url: "https://cdn.example/faces/mira.png" }, { provider: "ark" });
console.log(record.assetId, record.account, record.registeredAt);

console.log(app.asset.providers()); // ["ark"]
await app.stop();

A custom provider registers an AssetHandler under "asset":

import { ASSET_MIME, createPlugin, encodeAssetRecord, registryPlugin } from "@moku-labs/ai";
import type { Asset } from "@moku-labs/ai";

declare function acmeUpload(path: string): Promise<string>;
declare function acmeStatus(jobId: string): Promise<{ ready: boolean; id: string }>;
declare function acmeAccount(): string;

const handler: Asset.AssetHandler = {
  estimate: () => ({ usd: 0 }),
  submit: async request => ({ jobId: await acmeUpload(request.image.path) }),
  poll: async jobId => {
    const asset = await acmeStatus(jobId);
    if (!asset.ready) return { state: "pending" };
    const record = { assetId: asset.id, provider: "acme", account: acmeAccount(), groupId: "default", registeredAt: Date.now() };
    return { state: "done", body: encodeAssetRecord(record), mimeType: ASSET_MIME, costUsd: 0 };
  }
};

export const acmeAssetsPlugin = createPlugin("acmeAssets", {
  depends: [registryPlugin],
  onInit: ctx => {
    ctx.require(registryPlugin).register("asset", "acme", handler);
  }
});

Events

Emits

None.

Listens to

None.

Depends on

• registry: resolve("asset", provider) and providers("asset").

Related

• video: the task that uses the asset through refs.
• runner: the durable path. It stores the done body under ASSET_MIME.
• ark: the provider.