List models — GET /v1/ai/mcp/models

Searches the model catalog — the one GET /v1/models lists, every OpenRouter model among it as last synced — by text, class, family, capability or free, and answers each match with its class, family, whether it is free, its list price (per token and per million; variable for a router billed at the answering model's price; a resold model's every vendor rate and conditional rate as billed), context window, output bound, expiry and capabilities.

GET /v1/ai/mcp/models

Addresshttps://api.hanzo.ai/v1/ai/mcp/models
MethodGET
OperationaiModels
AuthAuthorization: Bearer $HANZO_API_KEY

Searches the model catalog — the one GET /v1/models lists, every OpenRouter model among it as last synced — by text, class, family, capability or free, and answers each match with its class, family, whether it is free, its list price (per token and per million; variable for a router billed at the answering model's price; a resold model's every vendor rate and conditional rate as billed), context window, output bound, expiry and capabilities.

Request

7 fields.

FieldInTypeRequiredDescription
qquerystring—Q matches the model's id, name, description or owner, ignoring case.
classquerystring—Class keeps one class: premium (third-party frontier models), ours (Hanzo's priced models) or free.
familyquerystring—Family keeps one Hanzo family: enso, zen, kai or zoo.
capabilityquerystring—Capability keeps the models that have it: tools, vision or reasoning, or a modality they take or give (text, image, audio, file, video, decision).
freequeryboolean—Free keeps the models a call to which bills nothing (bounded by the free allowances instead of a balance).
zdrqueryboolean—ZDR keeps only models eligible for Zero Data Retention (excludes free and data-shared routes).
limitqueryinteger—Limit is the most models to answer, 1 to 500; 0 answers 50.

Response

StatusBodyMeaning
200aiModelsok
defaultproblem-detailsrefused

200 body — 24 fields.

FieldInTypeAlwaysDescription
modelsbodyaiModel[]—Models are the matches, in the catalog's order.
models[].capabilitiesbodystring[]—Capabilities are tools, vision and reasoning, those the model supports.
models[].classbodystring—Class is premium, ours or free.
models[].context_windowbodyinteger (int64)—ContextWindow is the most tokens the model reads at once, absent when the catalog does not say.
models[].expiresbodystring—Expires is the day the model's vendor stops serving it (2006-01-02), absent when it states none.
models[].familybodystring—Family is the Hanzo family (enso, zen, kai, zoo), absent for a third-party model.
models[].freebodyboolean—Free is whether a call bills nothing.
models[].idbodystring—ID is the model's id, the one a completion or a decision names.
models[].inputsbodystring[]—Inputs are the modalities the model reads.
models[].max_output_tokensbodyinteger (int64)—MaxOutputTokens is the most one answer may hold, absent when the catalog does not say.
models[].namebodystring—Name is the model's display name.
models[].outputsbodystring[]—Outputs are the modalities the model writes.
models[].pricingbodyaiPrice—
models[].pricing.completionbodystring—Completion is the price of one output token, a decimal string.
models[].pricing.input_per_millionbodynumber (double)—InputPerMillion is the price of a million input tokens.
models[].pricing.output_per_millionbodynumber (double)—OutputPerMillion is the price of a million output tokens.
models[].pricing.overridesbodyobject[]—Overrides are the vendor's conditional rates as billed, each with its condition: min_prompt_tokens, or utc_start, utc_end and utc_days.
models[].pricing.overrides[].*bodyany—
models[].pricing.promptbodystring—Prompt is the price of one input token, a decimal string.
models[].pricing.ratesbodyobject—Rates is every rate a resold model's vendor states, in the vendor's names and units (USD per token for prompt, completion, input_cache_read, input_cache_write, internal_reasoning; per request; per search for web_search), as billed: the vendor's rate times our margin, exact.
models[].pricing.rates.*bodystring—
models[].pricing.variablebodyboolean—Variable is true for a router that bills each answer at the price of the model that gave it; the figures above are then that router's ceiling.
models[].zdrbodyboolean—ZDR is whether the model is eligible for Zero Data Retention (non-free, non-data-shared commercial route).
totalbodyinteger (int64)—Total is how many models matched, before Limit.

Failure carries the platform error shape — see Errors.

Examples

hanzo ai mcp models
import { Configuration, AiApi } from 'hanzoai';

const api = new AiApi(new Configuration({ accessToken: process.env.HANZO_API_KEY }));
const { data } = await api.aiModels();
from hanzoai.cloud import ApiClient, Configuration
from hanzoai.cloud.api import AiApi

client = ApiClient(Configuration(access_token=os.environ["HANZO_API_KEY"]))
result = AiApi(client).ai_models()
cfg := hanzoai.NewConfiguration()
cfg.AddDefaultHeader("Authorization", "Bearer "+os.Getenv("HANZO_API_KEY"))
client := hanzoai.NewAPIClient(cfg)

resp, _, err := client.AiAPI.AiModels(context.Background()).Execute()
if err != nil {
	return err
}
use hanzo_client::apis::{configuration::Configuration, ai_api};

let mut cfg = Configuration::new();
cfg.bearer_access_token = std::env::var("HANZO_API_KEY").ok();

let result = ai_api::ai_models(&cfg, Default::default()).await?;
import ai.hanzo.cloud.ApiClient;
import ai.hanzo.cloud.api.AiApi;

ApiClient client = new ApiClient();
client.setBearerToken(System.getenv("HANZO_API_KEY"));

var result = new AiApi(client).aiModels();
curl https://api.hanzo.ai/v1/ai/mcp/models \
  -H "Authorization: Bearer $HANZO_API_KEY"

Tool ai, op aiModels — POST the JSON-RPC envelope to https://api.hanzo.ai/v1/mcp.

curl -X POST https://api.hanzo.ai/v1/mcp \
  -H "Authorization: Bearer $HANZO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
       "jsonrpc": "2.0",
       "id": 1,
       "method": "tools/call",
       "params": {
         "name": "ai",
         "arguments": {
           "op": "aiModels",
           "input": {}
         }
       }
     }'

AI API · All Hanzo APIs · Interactive reference

Was this page useful?
Broken link or missing step? Drop it in #docs on Discord or open a PR.