Skip to content

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 ​

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

It prints three lines:

text
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 ​

ts
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:

ts
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 ​

bash
optimalai-model-tools add <model-id> \
  [--base-url URL] \
  [--models-dir DIR] \
  [--output FILE]
FlagPurpose
--base-urlOverride the CDN base URL for this run. Useful for staging.
--models-dirWhere the downloaded files land.
--outputWhere 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:

bash
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.