Model Aliasing

Keep app-facing model names stable while swapping providers underneath.

What it does

Model aliasing lets your app call one model name while Stockyard maps it to the real provider and model underneath. Your app sends "model": "fast" and Stockyard resolves it to gpt-4o-mini on OpenAI, or claude-haiku-4-5-20251001 on Anthropic, or whatever you configure. See why model aliasing matters for the full picture.

This means you can swap models, test replacements, or move traffic between providers without changing app code anywhere.

Quick start

The fastest way to set up an alias is through the API:

# Create an alias: "fast" resolves to gpt-4o-mini
curl -X PUT https://your-stockyard/api/proxy/aliases \
  -H "X-Admin-Key: your-key" \
  -H "Content-Type: application/json" \
  -d '{"alias": "fast", "model": "gpt-4o-mini"}'

# Now your app just sends model: "fast"
curl https://your-stockyard/v1/chat/completions \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"model": "fast", "messages": [{"role": "user", "content": "Hello"}]}'

Stockyard resolves fast to gpt-4o-mini before dispatching to OpenAI. Your app never knows the difference.

YAML configuration

You can also define aliases in your stockyard.yaml config file. These load on startup.

modelalias:
  enabled: true
  aliases:
    - alias: "fast"
      model: "gpt-4o-mini"
    - alias: "smart"
      model: "claude-sonnet-4-20250514"
    - alias: "cheap"
      model: "gpt-4o-mini"
    - alias: "flagship"
      model: "claude-opus-4-20250414"
    - alias: "local"
      model: "llama3:8b"

Aliases defined via the API are persisted to the database and survive restarts. YAML aliases and API aliases merge together, with API aliases taking precedence if the same alias name exists in both.

API endpoints

List aliases

curl https://your-stockyard/api/proxy/aliases \
  -H "X-Admin-Key: your-key"

Returns:

{
  "aliases": [
    {"alias": "fast", "model": "gpt-4o-mini"},
    {"alias": "smart", "model": "claude-sonnet-4-20250514"}
  ],
  "count": 2,
  "enabled": true
}

Create or update an alias

curl -X PUT https://your-stockyard/api/proxy/aliases \
  -H "X-Admin-Key: your-key" \
  -H "Content-Type: application/json" \
  -d '{"alias": "fast", "model": "claude-haiku-4-5-20251001"}'

Returns {"alias": "fast", "model": "claude-haiku-4-5-20251001", "action": "updated"}. The change takes effect immediately on the next request.

Delete an alias

curl -X DELETE https://your-stockyard/api/proxy/aliases/fast \
  -H "X-Admin-Key: your-key"

After deletion, requests using that alias name will be sent as-is to the provider. If the provider does not recognize the model name, the request will fail.

Resolution stats

curl https://your-stockyard/api/proxy/aliases/stats \
  -H "X-Admin-Key: your-key"

Returns total resolutions and the last 200 alias resolution events with timestamps, showing which aliases are being used and how often.

Common patterns

Swap providers without touching app code. Your app calls "model": "default". Today it maps to OpenAI. Tomorrow you point it at Anthropic. No deploy needed.

A/B test models. Create "model": "candidate" pointing at a new model. Route a subset of traffic to it using the alias while keeping your production alias stable.

Local plus cloud. Set "model": "local" pointing at your Ollama instance. If you need to fail over to cloud, update the alias to point at a hosted model.

Stable names for downstream consumers. If other teams or services depend on your model names, aliases let you change what runs underneath without breaking their integration.