ark

What it does

Provider. ark talks to ByteDance's own API, without a reseller in between. One plugin instance is one region and one account. It registers three handlers with the registry in onInit:

Video and asset are submit + poll: the runner journals the task or asset id before it waits, so a crash or Ctrl-C resumes by polling the same job. Image is one call: once sent, it runs to the end, so a paid image is not lost to a pause.

ark registers after fal, so fal stays the default video provider. Put provider: ark on the items that should go to Ark.

Setup

Regions

Each region serves only its own model ids. A model from the other region fails before any call.

Keys and entitlements

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

export const app = createApp({
  pluginConfigs: {
    ark: { region: "intl", groupId: "group-20260929120000-abcde" }
  }
});

Tasks it serves

version: 1
name: mira
items:
  - id: key-01
    task: image
    provider: ark
    input: { prompt: "Vertical 9:16 photo. Close-up, Akari lifts a cake box lid", aspect: "9:16" }
  - 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"

• video: model is an id from the table below, for the configured region. image is the first frame, endImage the last frame, refs the reference images and assets, in request order. A local image goes out as a data URI, an asset ref as asset://<id>. seconds defaults to 5, resolution to 720p, aspect to 9:16. audio: true turns on generate_audio. negative is dropped with one warning.
• image: model defaults to seedream-5-0-lite-260128. aspect picks the size: 9:16 is 1440×2560, 16:9 2560×1440, 1:1 2048×2048, 3:4 1728×2304, 4:3 2304×1728. refs are local images, up to 14, cited by position in the prompt ("image 1"). params.images: N asks for a group of up to N consistent images; refs plus N is at most 15.
• asset: image is the portrait, PNG, JPEG or WebP, under 30 MB, 300 to 6000 px per side. url is required: a public https URL of the same bytes. Ark fetches the portrait from there and never uploads it. groupName picks a group other than config.groupName.

The prompt cites refs by position. The handler never rewrites it.

Video params

params is an allowlist. Any other key fails before any call.

On Seedance 2.5 with a first or last frame, the output ratio follows the image and ratio is not sent. An explicit aspect is checked but cannot be honoured: one ark:ratio:ignored warning.

Models and prices

These are the bundled tables. priceOverrides changes a row by model id, and a model with no price fails the estimate instead of counting as $0. app.ark.info() lists the configured region's ids.

Video

Prices are per 1M output tokens, "no video input / with video input". intl prices are list prices from the official price page. cn prices come from summaries of the rate card and are divided by cnyPerUsd to report USD. Check them in the console before a paid run.

Cost is usage.completion_tokens / 1e6 × price. The "with video input" price applies when refUrls holds a video URL. The estimate is width × height × (24 × seconds + 1) / 1024 tokens at the base price, with 480p as 864×496, 720p as 1280×720 and 1080p as 1920×1080. This matched live bills exactly: 480p 5 s is 50,638 tokens, 1080p 5 s is 245,025 tokens.

Enterprise discounts are not in the catalog. Set them with priceOverrides.

Image

There is no cn image model. costUsd is the price per image times usage.generated_images. A group's estimate prices N images, an upper bound; Ark bills each image it made.

Asset

An asset registration estimates at $0: the fee is part of the entitlement.

Draft and final

Seedance 2.5 makes a cheap 480p draft with params.draft: true. A final renders the same draft again at 1080p: same frames, motion, seed and audio. Only the draft task goes to Ark.

version: 1
name: e01
items:
  - id: s04.key
    task: image
    provider: ark
    input: { prompt: "Vertical 9:16 photo. Close-up, Akari lifts a cake box lid", aspect: "9:16" }
  - id: s04.draft
    task: video
    provider: ark
    input:
      model: dreamina-seedance-2-5-260628
      prompt: "Akari lifts the lid, smiles"
      image: { $ref: s04.key }
      seconds: 5
      audio: true
    params: { draft: true }
  - id: s04.final
    task: video
    provider: ark
    input:
      model: dreamina-seedance-2-5-260628
      fromDraft: { $ref: s04.draft }

When a draft succeeds, ark keeps its task id in the journal as a draft provider record, keyed by the sha256 of the clip, scoped to this region and API key. A $ref to the draft item finds it. Every check runs before any call; each failure is a plain terminal error, nothing billed.

The 7-day rule. Ark keeps a draft id valid for 7 days from the draft's created_at. After that, bump params.generation on the draft item: the draft renders again, and so does the final.

Price of a final. Ark bills a final at 1080p, at the rate of its draft: "with video input" when the draft had a reference video, base when it had none. The final's own request sends no video, so the rate comes from the draft record. On dreamina-seedance-2-5-260628 a 5 s final is 341,880 tokens: $2.39 with video input, $4.00 without. A record without the field, written by an older version, gets the base price with an ark:cost:draft-input-unknown warning.

Faces

Seedance refuses a real face in an image from outside, for example a Codex keyframe. The item is flagged and the task is not billed. There is no raw-photo fallback and no registration after a refusal. Two routes work.

The handler never decodes, resizes, crops or re-encodes a Seedream image, so the bytes stay trusted. The guide Faces in video walks both routes.

Asset preflight

Before a video POST, every asset ref is checked. The POST happens only when all checks pass: the record was registered by ark, it belongs to this account, and GetAsset says Active. An asset seen Active is not checked again in the same process.

An asset id is valid only in the account that registered it. The record carries a one-way fingerprint, sha256("moku-ai:" + region + ":" + accessKey) cut to 12 characters. It never contains the key. When the keys change, bump params.generation on the asset items to register the portraits in the new account.

A dead asset

A stored record is reused as long as the item's input is unchanged. When the asset was deleted in the console, or the preflight reports it as not Active, bump params.generation on the asset item. The new key registers the portrait again, and the clips that use it render again.

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

Config

pluginConfigs.ark.

API

Mounted at app.ark, reachable with ctx.require(arkPlugin). The four library methods use the signed asset OpenAPI and need the access key and secret key. opts.signal cancels their calls.

ArkDraftRecord is { taskId, model, seed, createdAt, withVideoInput }. createdAt is ms since the epoch; the draft id is valid 7 days from there. ArkAsset is { assetId, name, groupId, status, createTime?, updateTime?, lastInferenceTime? }, ArkAssetGroup is { groupId, name, createTime? }. Both are exported as Ark.ArkAsset and Ark.ArkAssetGroup.

draftRecord does not check the age or the model. Compare createdAt yourself before a final:

import { app } from "./app";

const SEVEN_DAYS_MS = 7 * 24 * 60 * 60 * 1000;
const draftSha256 = "a".repeat(64);

await app.start();
const record = app.ark.draftRecord(draftSha256);
const isFresh = record !== undefined && Date.now() - record.createdAt < SEVEN_DAYS_MS;

if (isFresh) {
  const final = await app.video.generate(
    { model: record.model, prompt: "", fromDraft: { path: "draft.mp4", mimeType: "video/mp4", hash: draftSha256 } },
    { provider: "ark" }
  );
  console.log(final.costUsd, final.meta);
}
await app.stop();

One group per series: register in series-01, list its assets, then delete one.

import { app } from "./app";

const image = { path: "faces/mira.png", mimeType: "image/png", hash: "a".repeat(64) };
const record = await app.asset.register(
  { image, url: "https://cdn.example/faces/mira.png", groupName: "series-01" },
  { provider: "ark" }
);

const assets = await app.ark.listAssets({ groupId: record.groupId });
const asset = assets[0];
if (asset !== undefined) await app.ark.deleteAsset(asset.assetId);

Errors

The classes are ArkErrors.RetryableProviderError, ArkErrors.TerminalProviderError and ArkErrors.FlaggedProviderError. Messages start with [ai] and never contain a key or a signed URL.

Events

Emits

None.

Listens to

None.

Depends on

• registry: the three register calls.

It reads and writes draft provider records through ctx.journal; before app.start() the journal is closed, a draft is still returned with one ark:journal:closed warning, and a final fails.

Related

• Faces in video: Seedream first, draft to final, asset registration.
• asset plugin: the AssetRecord that video items $ref.
• apimodels plugin: Seedance official through a reseller, with its own asset route.
• fal plugin: the default video provider, no faces.