# Models API Reference

Complete API specification for defining LLM model configurations

## Overview

The `defineModel` function creates LLM model configurations that specify provider, model ID, fallback models, and pricing for Standard Agents.

```typescript
import { defineModel } from '@standardagents/spec';
import { openrouter } from '@standardagents/openrouter';

export default defineModel({
  name: 'tool-reasoning',
  provider: openrouter,
  model: 'nvidia/nemotron-3-ultra-550b-a55b',
  inputPrice: 0.5,
  outputPrice: 2.5,
});
```

The Builder admin model API validates provider-tool lists and capability fields before generating a model file.
A malformed value returns a field error with HTTP 400.
A generated model file keeps the `providerOptions` of its input, including nested objects.

## Configuration Options

- name (string), required

  Unique identifier for this model configuration. Used to reference the model in prompts. Use snake_case or kebab-case.

  ```typescript
  name: 'tool-reasoning'
  ```

* provider (ProviderFactory), required

  Provider factory function imported from a provider package or a local `agents/providers/*` file.

  | Provider              | Import                                                   | API Key Environment Variable                       |
  | --------------------- | -------------------------------------------------------- | -------------------------------------------------- |
  | Cloudflare Workers AI | `cloudflare` from `@standardagents/cloudflare`           | `CLOUDFLARE_API_TOKEN` and `CLOUDFLARE_ACCOUNT_ID` |
  | Cerebras              | `cerebras` from `@standardagents/cerebras`               | `CEREBRAS_API_KEY`                                 |
  | DeepInfra             | `deepinfra` from `@standardagents/deepinfra`             | `DEEPINFRA_API_KEY`                                |
  | Google                | `google` from `@standardagents/google`                   | `GOOGLE_API_KEY`                                   |
  | Groq                  | `groq` from `@standardagents/groq`                       | `GROQ_API_KEY`                                     |
  | Novita AI             | `novita` from `@standardagents/novita`                   | `NOVITA_API_KEY`                                   |
  | OpenAI                | `openai` from `@standardagents/openai`                   | `OPENAI_API_KEY`                                   |
  | Anthropic             | `anthropic` from `@standardagents/anthropic`             | `ANTHROPIC_API_KEY`                                |
  | OpenRouter            | `openrouter` from `@standardagents/openrouter`           | `OPENROUTER_API_KEY`                               |
  | Baseten Model APIs    | local `baseten` provider from `agents/providers/baseten` | `BASETEN_API_KEY`                                  |
  | xAI                   | `xai` from `@standardagents/xai`                         | `XAI_API_KEY`                                      |
  | TypeSafe AI           | `typesafe` from `@standardagents/typesafe`               | `TYPESAFE_AI_API_KEY`                              |

  ```typescript
  import { openrouter } from '@standardagents/openrouter';

  provider: openrouter
  ```

  Use `defineProvider` for local sub-providers with custom keys/endpoints, then default-import the provider into the model.

- model (string), required

  The actual model ID sent to the provider API. Format varies by provider.

  **Examples by provider:**

  | Provider              | Example Model IDs                                                                              |
  | --------------------- | ---------------------------------------------------------------------------------------------- |
  | Cloudflare Workers AI | `'@cf/google/gemma-4-26b-a4b-it'`, `'@cf/openai/gpt-oss-120b'`, `'@cf/qwen/qwen3-30b-a3b-fp8'` |
  | OpenAI                | `'gpt-6.1-sol'`, `'gpt-6-luna'`, `'gpt-6-astra'`                                               |
  | Anthropic             | `'claude-opus-5-5'`, `'claude-sonnet-5-5'`, `'claude-haiku-5-5'`                               |
  | Cerebras              | `'qwen-3.8-27b'`, `'gpt-oss-120b'`                                                             |
  | Google                | `'gemini-3.1-pro-preview'`, `'gemini-3.8-flash'`, `'imagen-4.0-generate-001'`                  |
  | Groq                  | `'llama-3.1-8b-instant'`, `'openai/gpt-oss-120b'`, `'qwen/qwen3-32b'`                          |
  | Novita AI             | `'zai-org/glm-5.2'`, `'deepseek/deepseek-v3.2'`, `'moonshotai/kimi-k2.7-code'`                 |
  | OpenRouter            | `'google/gemma-4-31b-it'`, `'nvidia/nemotron-3-ultra-550b-a55b'`, `'minimax/minimax-m3'`       |
  | Baseten Model APIs    | `'deepseek-ai/DeepSeek-V4-Pro'`, `'openai/gpt-oss-120b'`                                       |
  | xAI                   | `'grok-4-0709'`, `'grok-code-fast-1'`, `'grok-imagine-image'`                                  |

  ```typescript
  model: 'google/gemma-4-31b-it'
  ```

* fallbacks (string\[])

  Array of model names to try if this model fails. Fallbacks are tried in order after the primary model fails. Each model gets up
  to 2 attempts. A stream timeout or missing provider key skips the second attempt.
  A user stop cancels the request without trying fallbacks.

  ```typescript
  fallbacks: ['conversational', 'fast-response']
  ```

  **Fallback behavior:**

  1. Primary model tried up to 2 times
  2. First fallback tried up to 2 times
  3. Second fallback tried up to 2 times
  4. Continue until success or all fallbacks exhausted

- includedProviders (string\[])

  Provider prefixes for OpenRouter routing. Only applicable with the OpenRouter provider factory.

  ```typescript
  includedProviders: ['deepinfra']
  ```

  The runtime sends the list as OpenRouter's `provider.order`: OpenRouter tries these providers first, in list order, and falls back to other providers unless `providerOptions.provider.allow_fallbacks` is `false`. An explicit `providerOptions.provider.order` takes precedence; other `provider` routing options are kept. To restrict routing to the list, set `providerOptions.provider.only`. The admin pricing range shows the prices of the listed providers.

* inputPrice (number)

  Cost per 1 million input tokens in USD. Used for cost tracking.

  ```typescript
  // Nemotron 3 Ultra: USD per million input tokens.
  inputPrice: 0.5
  ```

- outputPrice (number)

  Cost per 1 million output tokens in USD. Used for cost tracking.

  ```typescript
  // Nemotron 3 Ultra: USD per million output tokens.
  outputPrice: 2.5
  ```

* cachedPrice (number)

  Cost per 1 million cached tokens in USD. This applies when a provider offers reduced pricing for cache reads.

  ```typescript
  // MiniMax M3: cache reads below the 512K input threshold.
  cachedPrice: 0.03
  ```

- capabilities (ModelCapabilities)

  Declares model features, reasoning levels, and context or output limits.

* providerOptions (provider-specific object)

  Options validated against the provider factory's schema. Prompt-level options
  override model-level values.

- providerTools (string\[])

  Built-in tool names from `provider.getTools()`. Add the desired provider tools
  to the model before referencing them from a prompt.

Provider-specific options appear in the [OpenAI](/docs/providers/openai), [Anthropic](/docs/providers/anthropic), [Google](/docs/providers/google), and [xAI](/docs/providers/xai) references.

## Open-weight model examples

Choose a model for the work in your prompt.
The priced examples use the maintained model guide's representative token prices.
OpenRouter supplies live pricing when explicit prices are omitted.
Check the [OpenRouter catalog](https://openrouter.ai/api/v1/models) before setting a price override.

### Conversation: Gemma 4 31B

```typescript agents/models/conversational.ts
import { defineModel } from '@standardagents/spec';
import { openrouter } from '@standardagents/openrouter';

export default defineModel({
  name: 'conversational',
  provider: openrouter,
  model: 'google/gemma-4-31b-it',
});
```

### Orchestration: Nemotron 3 Ultra

```typescript agents/models/tool_reasoning.ts
import { defineModel } from '@standardagents/spec';
import { openrouter } from '@standardagents/openrouter';

export default defineModel({
  name: 'tool-reasoning',
  provider: openrouter,
  model: 'nvidia/nemotron-3-ultra-550b-a55b',
});
```

### Low cost: GLM 4.7 Flash

```typescript agents/models/budget.ts
import { defineModel } from '@standardagents/spec';
import { openrouter } from '@standardagents/openrouter';

export default defineModel({
  name: 'budget',
  provider: openrouter,
  model: 'z-ai/glm-4.7-flash',
});
```

### Coding: MiniMax M3

```typescript agents/models/code_generation.ts
import { defineModel } from '@standardagents/spec';
import { openrouter } from '@standardagents/openrouter';

export default defineModel({
  name: 'code-generation',
  provider: openrouter,
  model: 'minimax/minimax-m3',
});
```

### OpenRouter routing

```typescript agents/models/openrouter_chat.ts
import { defineModel } from '@standardagents/spec';
import { openrouter } from '@standardagents/openrouter';

export default defineModel({
  name: 'openrouter-chat',
  provider: openrouter,
  model: 'google/gemma-4-31b-it',
  includedProviders: ['deepinfra'],  // Prefer DeepInfra endpoints.
});
```

### Cloudflare Workers AI Models

```typescript agents/models/workers_ai_fast.ts
import { defineModel } from '@standardagents/spec';
import { cloudflare } from '@standardagents/cloudflare';

export default defineModel({
  name: 'workers-fast',
  provider: cloudflare,
  model: '@cf/google/gemma-4-26b-a4b-it',
  // Prices change. Check https://developers.cloudflare.com/workers-ai/platform/pricing/
  inputPrice: 0.1,
  outputPrice: 0.3,
});
```

## Fallback Configurations

### Basic Fallback

```typescript
import { defineModel } from '@standardagents/spec';
import { openrouter } from '@standardagents/openrouter';

export default defineModel({
  name: 'primary-model',
  provider: openrouter,
  model: 'nvidia/nemotron-3-ultra-550b-a55b',
  fallbacks: ['conversational', 'fast-response'],
  inputPrice: 0.5,
  outputPrice: 2.5,
});
```

### Multi-Provider Resilience

```typescript
import { defineModel } from '@standardagents/spec';
import { openrouter } from '@standardagents/openrouter';

// Primary model
export default defineModel({
  name: 'resilient-primary',
  provider: openrouter,
  model: 'nvidia/nemotron-3-ultra-550b-a55b',
  fallbacks: ['deepinfra-fallback', 'conversational'],
});

```

```typescript agents/models/deepinfra_fallback.ts
import { defineModel } from '@standardagents/spec';
import { deepinfra } from '@standardagents/deepinfra';

export default defineModel({
  name: 'deepinfra-fallback',
  provider: deepinfra,
  model: 'nvidia/NVIDIA-Nemotron-3-Ultra-550B-A55B',
});
```

The `conversational`, `fast-response`, and `tool-reasoning` fallbacks use the definitions in [Example model choices](/docs/core-concepts/models#example-model-choices).

### Ordered Fallbacks

```typescript
import { defineModel } from '@standardagents/spec';
import { openrouter } from '@standardagents/openrouter';

// Start with GLM Flash. Try each fallback in order.
export default defineModel({
  name: 'cost-optimized',
  provider: openrouter,
  model: 'z-ai/glm-4.7-flash',
  fallbacks: ['conversational', 'fast-response', 'tool-reasoning'],
  inputPrice: 0.06,
  outputPrice: 0.4,
});
```

## Complete Examples

### Production Configuration

```typescript agents/models/production.ts
import { defineModel } from '@standardagents/spec';
import { openrouter } from '@standardagents/openrouter';

export default defineModel({
  name: 'production',
  provider: openrouter,
  model: 'nvidia/nemotron-3-ultra-550b-a55b',
  fallbacks: [
    'conversational',    // Try Gemma 4.
    'fast-response',     // Try Nemotron Super.
    'deepinfra-fallback', // Try a separate provider API.
  ],
  inputPrice: 0.5,
  outputPrice: 2.5,
});
```

### Budget Configuration

```typescript agents/models/budget.ts
import { defineModel } from '@standardagents/spec';
import { openrouter } from '@standardagents/openrouter';

export default defineModel({
  name: 'budget',
  provider: openrouter,
  model: 'z-ai/glm-4.7-flash',
  fallbacks: ['conversational', 'fast-response'],
  inputPrice: 0.06,
  outputPrice: 0.4,
});
```

### High-Performance Configuration

```typescript agents/models/high_performance.ts
import { defineModel } from '@standardagents/spec';
import { openrouter } from '@standardagents/openrouter';

export default defineModel({
  name: 'high-performance',
  provider: openrouter,
  model: 'moonshotai/kimi-k3',
  fallbacks: ['tool-reasoning'],
  inputPrice: 3,
  outputPrice: 15,
});
```

## Type Definitions

### ModelDefinition

```typescript
import type { ModelCapabilities, ProviderFactoryWithOptions, InferProviderOptions } from '@standardagents/spec';

interface ModelDefinition<
  N extends string = string,
  P extends ProviderFactoryWithOptions = ProviderFactoryWithOptions,
> {
  /**
   * Unique identifier for this model definition
   * Used to reference this model in prompts
   */
  name: N;

  /**
   * LLM provider for API requests
   */
  provider: P;

  /**
   * Actual model ID sent to the provider API
   * Format varies by provider
   */
  model: string;

  /**
   * Optional provider prefixes for OpenRouter routing
   * Only applicable when provider is the OpenRouter factory
   */
  includedProviders?: string[];

  /**
   * Fallback model names to try if this model fails
   * Must reference other defined models by name
   */
  fallbacks?: StandardAgentSpec.Models[];

  /**
   * Cost per 1 million input tokens in USD
   * Used for cost tracking
   */
  inputPrice?: number;

  /**
   * Cost per 1 million output tokens in USD
   * Used for cost tracking
   */
  outputPrice?: number;

  /**
   * Cost per 1 million cached tokens in USD
   * Reduced pricing for prompt caching features
   */
  cachedPrice?: number;
  capabilities?: ModelCapabilities;
  providerOptions?: InferProviderOptions<P>;
  providerTools?: string[];
}
```

### ModelProvider

```typescript
// Legacy type exported by @standardagents/spec.
type ModelProvider = 'openai' | 'openrouter' | 'anthropic' | 'google' | 'test';
```

This legacy alias does not constrain `ModelDefinition.provider`. Use a provider
factory import for a model definition.

### Generated Types

After you define models, Standard Agents populates `StandardAgentSpec.ModelRegistry`. `StandardAgentSpec.Models` resolves to its registered names:

```typescript
// Auto-generated
declare global {
  namespace StandardAgentSpec {
    interface ModelRegistry {
      'tool-reasoning': true;
      conversational: true;
      'fast-response': true;
    }
  }
}
export {};
```

## Best Practices

### Use Descriptive Names

```typescript
// Good - clear and descriptive
defineModel({ name: 'tool-reasoning', ... });
defineModel({ name: 'fast-response', ... });
defineModel({ name: 'budget-model', ... });

// Avoid - unclear
defineModel({ name: 'model1', ... });
defineModel({ name: 'm', ... });
```

### Configure Fallbacks for Production

Always configure fallbacks for production deployments:

```typescript
defineModel({
  name: 'production-model',
  provider: openrouter,
  model: 'nvidia/nemotron-3-ultra-550b-a55b',
  fallbacks: ['conversational', 'fast-response'],  // Multiple fallbacks
});
```

### Set Pricing for Cost Tracking

Configure pricing to monitor costs:

```typescript
defineModel({
  name: 'tracked-model',
  provider: openrouter,
  model: 'nvidia/nemotron-3-ultra-550b-a55b',
  inputPrice: 0.5,
  outputPrice: 2.5,
});
```

### Match Provider Format

Match the model ID format to the provider:

```typescript
// OpenRouter uses its developer/model format.
defineModel({ provider: openrouter, model: 'google/gemma-4-31b-it' });

// DeepInfra uses its own catalog ID for the same model.
defineModel({ provider: deepinfra, model: 'google/gemma-4-31B-it' });
```

### Organize by Purpose

Structure your models directory by use case:

```
agents/models/
├── tool_reasoning.ts   # Orchestration model
├── conversational.ts   # Conversation model
├── budget_model.ts     # Cost-effective option
├── fast_model.ts       # Low-latency option
└── fallback_model.ts   # Reliable fallback
```

## Environment Configuration

### Development

```bash .dev.vars
# Cloudflare Workers AI
CLOUDFLARE_API_TOKEN=...
CLOUDFLARE_ACCOUNT_ID=...

# Cerebras
CEREBRAS_API_KEY=...

# DeepInfra
DEEPINFRA_API_KEY=...

# Google
GOOGLE_API_KEY=...

# Groq
GROQ_API_KEY=...

# Novita AI
NOVITA_API_KEY=...

# Baseten Model APIs
BASETEN_API_KEY=...

# OpenAI
OPENAI_API_KEY=sk-...

# Anthropic
ANTHROPIC_API_KEY=sk-ant-...

# OpenRouter
OPENROUTER_API_KEY=sk-or-...

# xAI
XAI_API_KEY=...

# TypeSafe AI
TYPESAFE_AI_API_KEY=...
```

### Cloudflare Workers

For a deployed project, configure production provider keys in your project's
environment settings on the Standard Agents platform.

## File Structure

```
agents/
└── models/
    ├── tool_reasoning.ts      # export default defineModel({...})
    ├── conversational.ts     # export default defineModel({...})
    ├── fast_response.ts       # export default defineModel({...})
    └── budget.ts             # export default defineModel({...})
```

**Requirements:**

- Use snake_case for file names: `tool_reasoning.ts`, `conversational.ts`
- One model per file
- Default export required
- File placed in `agents/models/` directory

## Related Documentation

- [Models Overview](/docs/core-concepts/models)

  High-level model concepts

* [Prompts](/docs/api-reference/prompts)

  Define prompts that use models

- [Agents](/docs/api-reference/agents)

  Configure agents with models