apimodels

What it does

Provider. apimodels serves the video task over the apimodels.app task API. It registers ("video", "apimodels") with the registry in onInit.

Its reason to exist is faces. fal's Seedance endpoints refuse a real person and have no asset field. apimodels serves Seedance 2.5 and Seedance 2.0 official, which accept a real-person photo. It takes a face in two ways:

The handler is submit + poll. The job id is JSON { taskId, model, assetUsd }, journaled by the runner before it waits. A crash, Ctrl-C or restart polls the same task again. It is never submitted and paid twice. There is no execute: app.video.generate() drives the same loop.

Setup

Export APIMODELS_API_KEY, or put it in .env.local in the working directory. The shell wins over the file. The key is read at submit and poll time. Estimates never need it.

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

export const app = createApp({
  pluginConfigs: {
    video: { defaultProvider: "apimodels" },
    apimodels: { assetGroup: "series-01" }
  }
});

The framework ships the lane default video/apimodels: { concurrency: 2, rpm: 20 }. Upstream rate limits are not documented. The lane is held for the whole attempt, polling included.

Tasks it serves

version: 1
name: shot-03
items:
  - id: shot-03
    task: video
    provider: apimodels
    input:
      model: seedance-2.5
      prompt: "She turns to the window, slow push-in."
      image: { $file: cast/anna.png }
      seconds: 8
    params: { assets: ["image"] }

• video: model is one of the four aliases below. image is required on every alias. seconds defaults to 5, aspect to 9:16, resolution to 720p, audio to off. negative is not supported upstream: it is dropped and logged at debug level. params is merged last into the body, after assets is removed.

params.assets lists the inputs to send as asset:// ids: "image", "endImage" or "refs.<n>". Name only portraits. Props, locations and sketch sheets never need to be in an identity store. Each named input must be an image. A registration costs asset (0.01 USD) and the estimate adds it per named input, a worst case: the estimate cannot see the cache.

Models and prices

This is the bundled table. priceOverrides changes a row, and a model with no price fails the estimate instead of counting as $0. The aliases mirror fal's, so a build item switches provider only. Any other value fails with a terminal 400.

Price keys are <alias>@<resolution> in USD per second and asset in USD per registration. Refs are told apart by MIME type. A refused field, a resolution or length outside the table, or too many refs fails at estimate and at submit, before any upload or charge. input.fromDraft is refused: use ark with a Seedance 2.5 draft.

When the task is done, GET /records/<taskId> gives the real cost: when settled is true and the currency is USD, the cost is credits + assetUsd. Otherwise the table price plus assetUsd.

Config

pluginConfigs.apimodels.

API

Mounted at app.apimodels, reachable with ctx.require(apimodelsPlugin).

import { app } from "./app";

const { configured, models } = app.apimodels.info();
console.log(configured, models); // false, ["seedance-2.5", "seedance-2.5-ref", "seedance-2.0", "seedance-2.0-ref"]

const { usd } = app.video.estimate(
  { model: "seedance-2.5", prompt: "slow push-in", seconds: 8 },
  { provider: "apimodels" }
);
console.log(usd);

Errors

The classes are ApimodelsErrors.RetryableProviderError, ApimodelsErrors.TerminalProviderError and ApimodelsErrors.FlaggedProviderError. Messages start with [ai] apimodels and never contain the key or the prompt: both are cut out of any text apimodels sends back.

Events

Emits

None.

Listens to

None.

Depends on

• registry: the register call.

It also reads and writes provider records through ctx.journal for the asset cache. Before app.start() the journal is closed: app.video.generate() then uses the in-process cache only and logs apimodels:journal:closed once.

Related

• Faces in video: the routes that work for a real person.
• fal plugin: the same aliases, more models, no faces.
• ark plugin: Seedance straight from ByteDance, drafts and assets.
• video plugin: the request shape and the job contract.