Models and providers
Find Hull Gateway model IDs, list available models, and see how the hull-auto tiers route requests.
Hull Gateway gives you models from many providers through one API. To switch models, change the model ID; nothing else in your code changes.
Model IDs
Model IDs use the format vendor/model-name. Pass the ID as model in your request:
{
"model": "anthropic/claude-sonnet-5",
"messages": [{ "role": "user", "content": "Hello!" }]
}With the Vercel AI SDK:
const result = streamText({
model: hull.chat("anthropic/claude-sonnet-5"),
prompt: "Hello!",
})List available models
GET https://api.withhull.com/api/gateway/modelsThe response lists every model with its name, context length, pricing and supported features. The API key is optional here; when you send one with an organization header, the list reflects that organization's model policy. The model picker in Hull shows the same catalog.
The catalog changes as providers release and retire models, so read IDs from this endpoint rather than hard-coding a long list.
Free models
Some models are free to use, subject to rate limits. They're marked in the model list, and many have IDs ending in :free. Free models still need a Hull API key.
Data handling
Some free models are served by providers that log prompts and outputs and use them to improve their services. Don't send personal or confidential data to free models.
Auto models
Auto models (hull-auto/*) pick an underlying model for each request. See Auto model for how to choose a tier.
Routing can change
The models behind each tier are updated on the server as better options appear or as provider pricing and availability change. The tier IDs stay the same.
hull-auto/frontier
The most capable models for any task. Requests use medium reasoning effort. The model depends on the mode, sent in the X-HullCode-Mode header:
| Mode | Routes to |
|---|---|
plan, general, architect, ask, debug | The current Claude Opus model |
build, explore, code | The current Claude Sonnet model |
| No mode or unknown mode | The current Claude Sonnet model |
hull-auto/balanced and hull-auto/efficient
Both use Hull's routing service, which picks a model for each request based on continuously run benchmarks of accuracy and cost. Efficient aims for the cheapest model that is accurate enough for the task. When no routing decision is available, both fall back to a fixed, capable default model.
hull-auto/free
Routes to an available free model, keeping a session on the same model where it can. The candidate list changes as free model availability shifts.
hull-auto/small
Routes lightweight background work (such as session titles and commit messages) to a small, fast model. Accounts with a paid balance get a paid small model; others get a free one.
Example
curl -X POST "https://api.withhull.com/api/gateway/chat/completions" \
-H "Authorization: Bearer $HULL_API_KEY" \
-H "X-HullCode-Mode: plan" \
-H "Content-Type: application/json" \
-d '{"model": "hull-auto/frontier", "messages": [{"role": "user", "content": "Design a database schema for a todo app"}]}'Your own provider keys
If you've added a BYOK key for a model's provider, Hull Gateway sends that model's requests with your key. See Authentication.