Skip to content

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.

import { defineModel } from '@standardagents/spec';
import { openai } from '@standardagents/openai';

export default defineModel({
  name: 'gpt-6.1-sol',
  provider: openai,
  model: 'gpt-6.1-sol',
  // Prices change. Check https://developers.openai.com/api/docs/pricing
  // Standard rates apply to prompts up to 272K tokens.
  inputPrice: 2,
  outputPrice: 10,
});

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

namestringrequired

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

name: 'gpt-6.1-sol'
providerProviderFactoryrequired

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
import { openai } from '@standardagents/openai';

provider: openai

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

modelstringrequired

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 'openai/gpt-6.1-sol', 'anthropic/claude-opus-5.5', 'google/gemini-3.1-pro-preview'
Baseten Model APIs 'deepseek-ai/DeepSeek-V4-Pro', 'openai/gpt-oss-120b'
xAI 'grok-4-0709', 'grok-code-fast-1', 'grok-imagine-image'
model: 'gpt-6.1-sol'
fallbacksstring[]

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.

fallbacks: ['claude-sonnet', 'gemini-pro']

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
includedProvidersstring[]

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

includedProviders: ['anthropic']

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.

inputPricenumber

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

// GPT-6.1 Sol standard rates apply to prompts up to 272K tokens.
// Prices change. Check https://developers.openai.com/api/docs/pricing
inputPrice: 2
outputPricenumber

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

// GPT-6.1 Sol standard rates apply to prompts up to 272K tokens.
// Prices change. Check https://developers.openai.com/api/docs/pricing
outputPrice: 10
cachedPricenumber

Cost per 1 million cached tokens in USD. Reduced pricing for prompt caching features (Anthropic, OpenAI).

// GPT-6.1 Sol standard rates apply to prompts up to 272K tokens.
// Prices change. Check https://developers.openai.com/api/docs/pricing
cachedPrice: 0.1
capabilitiesModelCapabilities

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

providerOptionsprovider-specific object

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

providerToolsstring[]

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

Provider-Specific Examples

Examples below use provider factory imports such as openai, anthropic, google, openrouter, and cloudflare.

Model IDs and prices below are configuration examples. Check the provider catalog before you use an ID. Run npx @standardagents/cli@latest current-models for the maintained model guide. Run npx @standardagents/cli@latest available-models --provider=<name> for a provider catalog. Prices change. Each priced example links to the provider's live rates. Explicit prices override the runtime's pricing defaults. A flat override covers only the stated context range and billing units.

OpenAI Models

GPT-6.1 Sol

agents/models/gpt_6_1_sol.ts
import { defineModel } from '@standardagents/spec';
import { openai } from '@standardagents/openai';

export default defineModel({
  name: 'gpt-6.1-sol',
  provider: openai,
  model: 'gpt-6.1-sol',
  // Prices change. Check https://developers.openai.com/api/docs/pricing
  // Standard rates apply to prompts up to 272K tokens.
  inputPrice: 2,
  outputPrice: 10,
});

GPT-6 Luna

agents/models/gpt_6_luna.ts
import { defineModel } from '@standardagents/spec';
import { openai } from '@standardagents/openai';

export default defineModel({
  name: 'gpt-6-luna',
  provider: openai,
  model: 'gpt-6-luna',
  // Prices change. Check https://developers.openai.com/api/docs/pricing
  // Standard rates apply to prompts up to 272K tokens.
  inputPrice: 0.1,
  outputPrice: 0.5,
});

GPT-6 Astra

agents/models/gpt_6_astra.ts
import { defineModel } from '@standardagents/spec';
import { openai } from '@standardagents/openai';

export default defineModel({
  name: 'gpt-6-astra',
  provider: openai,
  model: 'gpt-6-astra',
  // Prices change. Check https://developers.openai.com/api/docs/pricing
  // Standard rates apply to prompts up to 272K tokens.
  inputPrice: 10,
  outputPrice: 50,
});

Anthropic Models

The Haiku example uses the short prompt tier. Check Anthropic pricing for longer prompts and cache writes.

Claude Sonnet 5.5

agents/models/claude_sonnet.ts
import { defineModel } from '@standardagents/spec';
import { anthropic } from '@standardagents/anthropic';

export default defineModel({
  name: 'claude-sonnet',
  provider: anthropic,
  model: 'claude-sonnet-5-5',
  // Prices change. Check https://platform.claude.com/docs/en/about-claude/pricing
  inputPrice: 2,
  outputPrice: 10,
});

Claude Opus 5.5

agents/models/claude_opus.ts
import { defineModel } from '@standardagents/spec';
import { anthropic } from '@standardagents/anthropic';

export default defineModel({
  name: 'claude-opus',
  provider: anthropic,
  model: 'claude-opus-5-5',
  // Prices change. Check https://platform.claude.com/docs/en/about-claude/pricing
  inputPrice: 4,
  outputPrice: 20,
});

Claude Haiku 5.5

agents/models/claude_haiku.ts
import { defineModel } from '@standardagents/spec';
import { anthropic } from '@standardagents/anthropic';

export default defineModel({
  name: 'claude-haiku',
  provider: anthropic,
  model: 'claude-haiku-5-5',
  // Prices change. Check https://platform.claude.com/docs/en/about-claude/pricing
  // These rates apply to prompts up to 100K tokens.
  inputPrice: 0.1,
  outputPrice: 0.5,
});

Google Models

Gemini 3.1 Pro Preview

agents/models/gemini_pro.ts
import { defineModel } from '@standardagents/spec';
import { google } from '@standardagents/google';

export default defineModel({
  name: 'gemini-pro',
  provider: google,
  model: 'gemini-3.1-pro-preview',
  // Prices change. Check https://ai.google.dev/gemini-api/docs/pricing
  // Text rates apply to prompts up to 200K tokens.
  inputPrice: 2,
  outputPrice: 12,
});

Gemini 3.8 Flash

agents/models/gemini_flash.ts
import { defineModel } from '@standardagents/spec';
import { google } from '@standardagents/google';

export default defineModel({
  name: 'gemini-flash',
  provider: google,
  model: 'gemini-3.8-flash',
  // Prices change. Check https://ai.google.dev/gemini-api/docs/pricing
  // These promotional rates end on December 31, 2026.
  inputPrice: 0.75,
  outputPrice: 3.75,
});

OpenRouter Models

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

export default defineModel({
  name: 'openrouter-claude',
  provider: openrouter,
  model: 'anthropic/claude-sonnet-5.5',
  includedProviders: ['anthropic'],  // Prefer Anthropic providers
});

Cloudflare Workers AI Models

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

import { defineModel } from '@standardagents/spec';
import { openai } from '@standardagents/openai';

export default defineModel({
  name: 'primary-model',
  provider: openai,
  model: 'gpt-6.1-sol',
  fallbacks: ['claude-sonnet', 'gemini-pro'],
  // Prices change. Check https://developers.openai.com/api/docs/pricing
  // Standard rates apply to prompts up to 272K tokens.
  inputPrice: 2,
  outputPrice: 10,
});

Multi-Provider Resilience

import { defineModel } from '@standardagents/spec';
import { openai } from '@standardagents/openai';

// Primary model
export default defineModel({
  name: 'resilient-primary',
  provider: openai,
  model: 'gpt-6.1-sol',
  fallbacks: ['anthropic-fallback', 'google-fallback'],
});

agents/models/anthropic_fallback.ts

agents/models/anthropic_fallback.ts
import { defineModel } from '@standardagents/spec';
import { anthropic } from '@standardagents/anthropic';

// Anthropic fallback
export default defineModel({
  name: 'anthropic-fallback',
  provider: anthropic,
  model: 'claude-sonnet-5-5',
});

agents/models/google_fallback.ts

agents/models/google_fallback.ts
import { defineModel } from '@standardagents/spec';
import { google } from '@standardagents/google';

// Google fallback
export default defineModel({
  name: 'google-fallback',
  provider: google,
  model: 'gemini-3.1-pro-preview',
});

Ordered Fallbacks

import { defineModel } from '@standardagents/spec';
import { openai } from '@standardagents/openai';

// Start with Luna. Try each fallback in order.
export default defineModel({
  name: 'cost-optimized',
  provider: openai,
  model: 'gpt-6-luna',
  fallbacks: ['claude-haiku', 'gemini-flash', 'gpt-6.1-sol'],
  // Prices change. Check https://developers.openai.com/api/docs/pricing
  // Standard rates apply to prompts up to 272K tokens.
  inputPrice: 0.1,
  outputPrice: 0.5,
});

Complete Examples

Production Configuration

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

export default defineModel({
  name: 'production',
  provider: openai,
  model: 'gpt-6.1-sol',
  fallbacks: [
    'claude-sonnet',      // Try Anthropic
    'gemini-pro',         // Try Google
    'openrouter-gpt',     // Try OpenRouter
  ],
  // Prices change. Check https://developers.openai.com/api/docs/pricing
  // Standard rates apply to prompts up to 272K tokens.
  inputPrice: 2,
  outputPrice: 10,
  cachedPrice: 0.1,
});

Budget Configuration

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

export default defineModel({
  name: 'budget',
  provider: openai,
  model: 'gpt-6-luna',
  fallbacks: ['claude-haiku', 'gemini-flash'],
  // Prices change. Check https://developers.openai.com/api/docs/pricing
  // Standard rates apply to prompts up to 272K tokens.
  inputPrice: 0.1,
  outputPrice: 0.5,
});

High-Performance Configuration

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

export default defineModel({
  name: 'high-performance',
  provider: anthropic,
  model: 'claude-opus-5-5',
  fallbacks: ['gpt-6.1-sol'],
  // Prices change. Check https://platform.claude.com/docs/en/about-claude/pricing
  inputPrice: 4,
  outputPrice: 20,
});

Type Definitions

ModelDefinition

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

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

// Auto-generated
declare global {
  namespace StandardAgentSpec {
    interface ModelRegistry {
      'gpt-6.1-sol': true;
      'claude-sonnet': true;
      'gemini-pro': true;
    }
  }
}
export {};

Best Practices

Use Descriptive Names
// Good - clear and descriptive
defineModel({ name: 'gpt-6.1-sol', ... });
defineModel({ name: 'claude-sonnet-fast', ... });
defineModel({ name: 'budget-model', ... });

// Avoid - unclear
defineModel({ name: 'model1', ... });
defineModel({ name: 'm', ... });
Configure Fallbacks for Production

Always configure fallbacks for production deployments:

defineModel({
  name: 'production-model',
  provider: openai,
  model: 'gpt-6.1-sol',
  fallbacks: ['claude-sonnet', 'gemini-pro'],  // Multiple fallbacks
});
Set Pricing for Cost Tracking

Configure pricing to monitor costs:

defineModel({
  name: 'tracked-model',
  provider: openai,
  model: 'gpt-6.1-sol',
  // Prices change. Check https://developers.openai.com/api/docs/pricing
  // Standard rates apply to prompts up to 272K tokens.
  inputPrice: 2,
  outputPrice: 10,
});
Match Provider Format

Match the model ID format to the provider:

// OpenAI - simple model name
defineModel({ provider: openai, model: 'gpt-6.1-sol' });

// OpenRouter - provider/model format
defineModel({ provider: openrouter, model: 'openai/gpt-6.1-sol' });

// Anthropic uses its catalog model ID.
defineModel({ provider: anthropic, model: 'claude-sonnet-5-5' });
Organize by Purpose

Structure your models directory by use case:

agents/models/
├── gpt_6_1_sol.ts      # Primary OpenAI model
├── claude_sonnet.ts    # Primary Anthropic model
├── budget_model.ts     # Cost-effective option
├── fast_model.ts       # Low-latency option
└── fallback_model.ts   # Reliable fallback

Environment Configuration

Development

.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/
    ├── gpt_6_1_sol.ts      # export default defineModel({...})
    ├── claude_sonnet.ts    # export default defineModel({...})
    ├── gemini_pro.ts       # export default defineModel({...})
    └── budget.ts           # export default defineModel({...})

Requirements:

  • Use snake_case for file names: gpt_6_1_sol.ts, claude_sonnet.ts
  • One model per file
  • Default export required
  • File placed in agents/models/ directory