API Reference

Complete documentation for all node-mlx functions and types.

Functions

generate()

One-shot text generation that loads, generates, and unloads automatically.

function generate(model: string, prompt: string, options?: GenerateOptions): GenerateResult

Parameters:

Parameter	Type	Description
`model`	`string`	Model name or HuggingFace path
`prompt`	`string`	Input text to generate from
`options`	`GenerateOptions`	Optional generation settings

Returns: GenerateResult object with generated text and metrics.

Example:

import { generate } from "node-mlx"

const result = generate("qwen", "Hello, world!", {
  maxTokens: 100,
  temperature: 0.7
})

console.log(result.text)
console.log(`${result.tokensPerSecond} tok/s`)

loadModel()

Load a model for multiple generations. More efficient when generating multiple responses.

function loadModel(model: string): Model

Parameters:

Parameter	Type	Description
`model`	`string`	Model name or HuggingFace path

Returns: Model instance with generate() and unload() methods.

Example:

import { loadModel } from "node-mlx"

const model = loadModel("phi")

const result1 = model.generate("What is 2+2?")
const result2 = model.generate("What is the capital of France?")

model.unload()

Types

GenerateOptions

Configuration options for text generation.

interface GenerateOptions {
  maxTokens?: number // Maximum tokens to generate (default: 256)
  temperature?: number // Sampling temperature 0-2 (default: 0.7)
  topP?: number // Nucleus sampling threshold (default: 0.9)
  repetitionPenalty?: number // Penalty for repeated tokens (default: 1.0)
  systemPrompt?: string // System prompt for chat models
}

GenerateResult

Result object returned from generation.

interface GenerateResult {
  text: string // Generated text
  tokensGenerated: number // Number of tokens generated
  tokensPerSecond: number // Generation speed
  promptTokens: number // Tokens in the prompt
  totalTime: number // Total generation time in ms
}

Model

Loaded model instance for multiple generations.

interface Model {
  generate(prompt: string, options?: GenerateOptions): GenerateResult
  unload(): void
}

Model Names

You can use short aliases or full HuggingFace paths:

Alias	Full Path
`qwen`	`lmstudio-community/Qwen3-4B-Instruct-2507-MLX-4bit`
`phi`	`mlx-community/phi-4-4bit`
`gemma`	`mlx-community/gemma-3-1b-it-4bit`
`llama`	`meta-llama/Llama-4-Scout-17B-16E-Instruct`
`mistral`	`mlx-community/Mistral-7B-Instruct-v0.3-4bit`

Or use any model from the mlx-community on HuggingFace:

const model = loadModel("mlx-community/DeepSeek-R1-Distill-Qwen-1.5B-4bit")

API Reference

On this page