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
namestringrequiredUnique identifier for this model configuration. Used to reference the model in prompts. Use snake_case or kebab-case.
name: 'gpt-6.1-sol'providerProviderFactoryrequiredProvider 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 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: openaiUse defineProvider for local sub-providers with custom keys/endpoints, then default-import the provider into the model.
modelstringrequiredThe 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' |
'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:
- Primary model tried up to 2 times
- First fallback tried up to 2 times
- Second fallback tried up to 2 times
- 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.
inputPricenumberCost 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: 2outputPricenumberCost 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: 10cachedPricenumberCost 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.1capabilitiesModelCapabilitiesDeclares model features, reasoning levels, and context or output limits.
providerOptionsprovider-specific objectOptions 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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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 fallbackEnvironment Configuration
Development
# 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