Model preparation

The model is not bundled in the npm packages. You download and verify it at development time with @optimalai/model-tools, which then generates a TypeScript module your app imports.

Run the installer

npx @optimalai/model-tools@beta add kokoro-82m-v1.1-zh-int8

It prints three lines:

Installed kokoro-82m-v1.1-zh-int8@1.1-zh-int8
Model: <models directory>
Generated: <path to optimalai-models.ts>

What it actually does

1. Reads the base URL from OPTIMALAI_MODELS_BASE_URL, or from --base-url.
2. Fetches <base>/<modelId>/manifest.json and validates it.
3. Downloads every file, verifying byte length and SHA-256 while streaming.
4. Installs atomically — it writes to a temporary directory first, then renames, so a failed download never leaves a half-written model behind.
5. Generates optimalai-models.ts containing static require(...) calls.

The full contract lives in the Model CDN notes; the short version is that the manifest is immutable per model version and records the runtime ABI, the 103 voices, minimum SDK versions, byte lengths, and SHA-256 hashes.

The generated module

import type { OptimalAIModel } from "@optimalai/react-native";

export const kokoroZhInt8 = {
  modelId: "kokoro-82m-v1.1-zh-int8",
  modelVersion: "1.1-zh-int8",
  assets: {
    model: require("./optimalai-models/model.int8.onnx") as number,
    voices: require("./optimalai-models/voices.bin") as number,
    tokens: require("./optimalai-models/tokens.txt") as number,
    lexicons: [
      require("./optimalai-models/lexicon-zh.txt") as number,
      require("./optimalai-models/lexicon-us-en.txt") as number,
    ],
  },
  manifest: {/* runtime manifest with voice entries */},
} satisfies OptimalAIModel;

Import the export and hand it to createTts:

import { kokoroZhInt8 } from "./optimalai-models";

The export name is derived from the model id (kokoro-82m-v1.1-zh-int8 → kokoroZhInt8) unless the manifest specifies an exportName.

Command-line options

optimalai-model-tools add <model-id> \
  [--base-url URL] \
  [--models-dir DIR] \
  [--output FILE]

Flag	Purpose
--base-url	Override the CDN base URL for this run. Useful for staging.
--models-dir	Where the downloaded files land.
--output	Where optimalai-models.ts is written.

Staging and the production CDN

The production CDN base URL is injected by OptimalAI at release time; the npm package deliberately contains no placeholder domain. Until that URL is live, pass --base-url or set the environment variable:

export OPTIMALAI_MODELS_BASE_URL="https://your-staging-host"

If neither is set, the CLI fails immediately rather than downloading from an unknown host.

Re-running the installer

Running add again is safe. If the model directory already exists and passes verification (byte length plus SHA-256 for every file), the CLI reuses it instead of re-downloading.

A failed verification is a stop sign

The CLI never overwrites an existing directory that fails verification. Investigate why it failed, then remove or move the directory yourself and run the command again.

Commit policy

Model files are large binaries. Treat the model directory as a build artifact: add it to .gitignore and let every checkout reproduce it with the installer.