ContextQMD
Back to Eliza

Models API

packages/docs/rest/models.md

2.0.14.4 KB
Original Source

The models endpoint lists available AI models from configured providers. Results are cached on disk; use ?refresh=true to bust the cache and fetch fresh model lists from each provider's API.

Model Categories

Models are automatically classified into categories based on their ID:

CategoryMatching keywords in model ID
chatDefault for any model not matching other categories
embeddingembed, text-embedding
imagedall-e, dalle, imagen, stable-diffusion, midjourney, flux
ttstts, text-to-speech, eleven_
sttwhisper, stt, transcrib
othermoderation, guard, safety

Cache Behavior

Model lists are cached per-provider on disk:

ParameterValue
Cache location~/.eliza/models-cache/<provider>.json
Cache TTL24 hours
Cache formatJSON with version, providerId, fetchedAt, models[]

Each cached file stores:

json
{
  "version": 1,
  "providerId": "openai",
  "fetchedAt": "2026-02-19T10:00:00.000Z",
  "models": [
    { "id": "gpt-4o", "name": "GPT-4o", "category": "chat" }
  ]
}

Cache is invalidated when the fetchedAt timestamp is older than 24 hours. Use ?refresh=true to force a cache bust.

Supported Providers

The models endpoint fetches from providers that have API keys configured:

ProviderEnv KeyAPI EndpointAuth Method
openaiOPENAI_API_KEYhttps://api.openai.com/v1/modelsAuthorization: Bearer
anthropicANTHROPIC_API_KEYhttps://api.anthropic.com/v1/models?limit=100x-api-key + anthropic-version: 2023-06-01
google-genaiGOOGLE_GENERATIVE_AI_API_KEY or GOOGLE_API_KEYGenerative Language API /v1beta/modelsAPI key in query parameter
groqGROQ_API_KEYhttps://api.groq.com/openai/v1/modelsAuthorization: Bearer
xaiXAI_API_KEYhttps://api.x.ai/v1/modelsAuthorization: Bearer
openrouterOPENROUTER_API_KEYhttps://openrouter.ai/api/v1/models + /embeddings/modelsAuthorization: Bearer
ollamaOLLAMA_BASE_URL<base>/api/tagsNo auth
vercel-ai-gatewayAI_GATEWAY_API_KEY or AIGATEWAY_API_KEYGateway /modelsNo auth required

Provider-Specific Notes

  • Anthropic: Uses x-api-key header (not Authorization: Bearer) and requires the anthropic-version header
  • Google: Passes the API key as a query parameter (?key=<apiKey>), not a header
  • Ollama: Local-only, no authentication. Reads model names from the /api/tags response
  • OpenRouter: Fetches two endpoints in parallel — /api/v1/models for chat/image/audio models and /api/v1/embeddings/models for embedding models. Uses architecture.output_modalities for classification

Endpoints

GET /api/models

List available AI models. Optionally filter by a specific provider or refresh the cache.

Query Parameters

ParameterTypeRequiredDescription
providerstringNoFilter to a specific provider (e.g., openai, anthropic, ollama). Returns all providers if omitted
refreshstringNoSet to "true" to bust the cache and fetch fresh model lists from provider APIs

Response (all providers)

json
{
  "providers": {
    "openai": [
      { "id": "gpt-4o", "name": "GPT-4o", "category": "chat" },
      { "id": "gpt-5-mini", "name": "GPT-4o Mini", "category": "chat" },
      { "id": "text-embedding-3-large", "name": "text-embedding-3-large", "category": "embedding" }
    ],
    "anthropic": [
      { "id": "claude-opus-4-7", "name": "Claude Opus 4.7", "category": "chat" }
    ]
  }
}

Response (single provider)

json
{
  "provider": "openai",
  "models": [
    { "id": "gpt-4o", "name": "GPT-4o", "category": "chat" }
  ]
}

Model Object

FieldTypeDescription
idstringModel identifier (e.g., gpt-4o, claude-opus-4-7)
namestringHuman-readable display name
categorystringOne of: chat, embedding, image, tts, stt, other