modelbay

Modelbay

简体中文 · English

Modelbay is an open-source (MIT) TypeScript SDK, MCP server and CLI that give you one interface to Chinese and global AI model platforms: Volcengine Ark (Doubao, Seedream, Seedance), Alibaba Cloud Bailian / DashScope (Qwen, Wan), MiniMax, Doubao Speech and OpenAI. It covers chat, image, video, speech and music generation, and handles async job polling for you.

Install the SDK with npm i modelbay zod, or add an MCP server to Claude Code, Codex, Cursor or Claude Desktop with npx -y @modelbay/mcp ark. Packages are on npm as modelbay, @modelbay/mcp and @modelbay/cli. Design decisions live in docs/decisions/.

One TypeScript implementation serves the SDK, the MCP servers and the CLI. Model parameters, limits, defaults and lifecycle states are declared as data; the MCP tool schemas and UI forms are derived from those declarations, so an upstream change only needs one edit.

Packages

Three packages are published to npm:

Package	Role
modelbay	The SDK: core API, createModelbay(), platform registry, modelbay/node
@modelbay/mcp	MCP server generated from declarations; command modelbay-mcp <platform>
@modelbay/cli	CLI, command name modelbay

Platform-specific exports live on subpaths of modelbay: modelbay/ark, modelbay/bailian, modelbay/minimax, modelbay/doubao-speech, modelbay/openai, plus modelbay/<platform>/node for Node-only helpers.

Inside the repo, @modelbay/core, @modelbay/shared and the five platform packages stay separate private workspace packages that keep the layering honest; modelbay bundles them at build time. All packages are ESM-only, MIT licensed, and share one version number (changesets fixed group).

Quick start (10 lines)

External TypeScript projects only install modelbay and supply a key. Async polling is handled by the SDK (core's runJob()), so there is no polling loop to write.

import { createModelbay } from 'modelbay'

const mb = createModelbay({ secrets: { ARK_API_KEY: process.env.ARK_API_KEY ?? '' } })
const { outputs } = await mb.generate({
  capability: 'image.generate',
  input: { prompt: 'a cat wearing a hat' },
})
// outputs[0] is a URL or bytes; the host downloads and persists it

Swap the capability to video.generate or audio.speech (with input: { text: ... }) for video and dubbing. When model is omitted, the default is chosen from active declarations only, by ModelRegistry.defaultFor() — consumers never hardcode a default. Results are URLs or bytes; keys are supplied by the host and are never stored or printed by the SDK. createModelbay() also reads keys from process.env when secrets is omitted.

See packages/modelbay/README.md for the full API and key names.

CLI

modelbay models [platform]   # list models and their lifecycle status
modelbay capabilities        # list capabilities
modelbay doctor              # check key configuration (never prints keys)
modelbay generate --capability image.generate --prompt "a cat" --model ark:doubao-seedream

FAQ

What is Modelbay? A TypeScript SDK, MCP server and CLI for Volcengine Ark, Alibaba Bailian, MiniMax, Doubao Speech and OpenAI. One implementation serves all three entry points, driven by a single set of model declarations.

How do I use it in Claude Code, Codex, Cursor or Claude Desktop? Add an MCP server that runs npx -y @modelbay/mcp <platform> (ark, minimax, bailian, doubao-speech or openai) and pass the platform key through the server's environment, for example ARK_API_KEY. Each platform is a separate server. See packages/mcp/README.md.

Which platforms and capabilities are supported? Ark, Bailian, MiniMax, Doubao Speech and OpenAI; chat, image generation and editing, video generation, speech, music, voice cloning and design, and transcription, depending on the platform. Run modelbay models or modelbay capabilities for the current list, or see the goals.

Is it free? Which license? Free and open source under the MIT license. Model usage is billed by each platform on your own account.

Where do API keys go? The host supplies them through createModelbay({ secrets }) or environment variables such as ARK_API_KEY, BAILIAN_API_KEY (alias DASHSCOPE_API_KEY), MINIMAX_API_KEY, DOUBAO_API_KEY and OPENAI_API_KEY. The SDK never stores or prints them.

Does it run outside Node? The root modelbay entry only uses APIs available in Node, Bun, Deno and browsers; Node-only helpers are under the modelbay/node subpath.

When should I use something else? If you only call one platform and need every vendor-specific feature, that vendor's official SDK is the more direct choice. Modelbay is for working across several platforms, or exposing them as MCP tools.

Development

pnpm verify runs the full check: dedupe, lint, typecheck, tests with per-package coverage, an offline check of every declaration's official source, build, and package/license/core-runtime checks. Adding a model, platform, capability or MCP tool is described in docs/extending.md; conventions are in docs/engineering.md.

Releases are manual and maintainer-approved. A daily job fetches each platform's official docs, reconciles model lists and deprecation notices against the declarations in both directions, tracks gaps in an issue, and opens a draft PR for lifecycle patches (docs/upstream.md, in Chinese).

MIT © ikuyu