Models

模型列表接口回答一个问题：当前这个 Token 能调用哪些模型。返回的是按 Token 权限、分组和上架状态过滤后的结果，不是平台全量模型目录。请求中的 model 必须来自这个列表。

列出可用模型

GET /v1/models

curl https://api.routeapi.ai/v1/models \
  -H "Authorization: Bearer $ROUTEAPI_KEY"

响应：

{
  "success": true,
  "object": "list",
  "data": [
    {
      "id": "gpt-5.5",
      "object": "model",
      "created": 1626777600,
      "owned_by": "openai",
      "supported_endpoint_types": ["openai", "openai-response"]
    },
    {
      "id": "claude-sonnet-4-5",
      "object": "model",
      "created": 1626777600,
      "owned_by": "anthropic",
      "supported_endpoint_types": ["openai", "anthropic"]
    },
    {
      "id": "text-embedding-3-large",
      "object": "model",
      "created": 1626777600,
      "owned_by": "openai",
      "supported_endpoint_types": ["embeddings"]
    }
  ]
}

字段	说明
id	调用时填进 model 的值，唯一可靠的模型标识
object	固定为 "model"
created	固定占位值 1626777600，不是真实上架时间，不要用它排序或判断新旧
owned_by	模型所属渠道类型（如 openai、anthropic）；平台自定义模型为 custom
supported_endpoint_types	该模型可用的端点类型列表，见下方端点类型

响应顶层同时有 success 和 OpenAI 风格的 object/data。OpenAI SDK 只读 data，多出的 success 不影响解析。

data 的顺序不保证稳定，两次请求可能不同。需要固定顺序请在客户端自行排序。

端点类型

supported_endpoint_types 是 RouteAPI 的扩展字段，也是模型列表里唯一的能力信号。它表示这个模型能从哪些协议入口调用：

值	对应端点
openai	POST /v1/chat/completions
openai-response	POST /v1/responses
anthropic	POST /v1/messages
gemini	POST /v1beta/models/{model}:generateContent
embeddings	POST /v1/embeddings
image-generation	POST /v1/images/generations
jina-rerank	POST /v1/rerank
openai-video	OpenAI 视频生成端点
suno-*	Suno 系列端点，见 Suno API

如果一个模型的 supported_endpoint_types 里没有 embeddings，就不要把它传给 /v1/embeddings——这类不匹配会在转发阶段失败。

列表里没有细粒度能力字段。 是否支持工具调用、图像输入、结构化输出，模型列表接口不返回，也没有 supports_tools / supports_vision 这类字段。这些能力由上游模型自身决定，确认方式是查阅模型供应商文档，或直接用目标模型发一次真实请求验证。上下文长度、模态和价格等元数据同样不在这个接口里，它们展示在控制台的模型广场页面。

查询单个模型

GET /v1/models/{model}

curl https://api.routeapi.ai/v1/models/gpt-5.5 \
  -H "Authorization: Bearer $ROUTEAPI_KEY"

存在时直接返回模型对象（不包裹 data）：

{
  "id": "gpt-5.5",
  "object": "model",
  "created": 1626777600,
  "owned_by": "openai"
}

不存在或对当前账户不可见时返回：

{
  "error": {
    "message": "The model 'foo' does not exist",
    "type": "invalid_request_error",
    "param": "model",
    "code": "model_not_found"
  }
}

注意 HTTP 状态码仍是 200。 这个接口把错误放在响应体的 error 字段里，不用状态码表达”模型不存在”。客户端必须检查响应体里有没有 error，只看 HTTP 状态码会把失败当成功。

对当前账户不可见的模型与真正不存在的模型返回完全相同的错误，无法通过这个接口区分两者。

其他协议的模型列表

同一份可用模型集合可以用三种协议格式取回，按你的 SDK 选择即可。

Claude Messages 格式

在 GET /v1/models 上同时带 x-api-key 和 anthropic-version 请求头，返回 Anthropic 风格：

curl https://api.routeapi.ai/v1/models \
  -H "x-api-key: $ROUTEAPI_KEY" \
  -H "anthropic-version: 2023-06-01"

{
  "data": [
    {
      "id": "claude-sonnet-4-5",
      "created_at": "2021-07-20T12:00:00Z",
      "display_name": "claude-sonnet-4-5",
      "type": "model"
    }
  ],
  "first_id": "claude-sonnet-4-5",
  "has_more": false,
  "last_id": "claude-sonnet-4-5"
}

两个请求头必须同时存在才会切换到这个格式，只带 x-api-key 仍返回 OpenAI 格式。display_name 等于 id，不是控制台里的展示名。has_more 恒为 false——列表一次返回完，没有分页。列表为空时 first_id 和 last_id 是空字符串。

Gemini 格式

curl "https://api.routeapi.ai/v1beta/models" \
  -H "x-goog-api-key: $ROUTEAPI_KEY"

{
  "models": [
    { "name": "gemini-2.5-pro", "displayName": "gemini-2.5-pro" }
  ],
  "nextPageToken": null
}

Gemini 格式的模型对象还包含 inputTokenLimit、supportedGenerationMethods 等字段，但 RouteAPI 只填充 name 和 displayName，其余字段返回 null。不要依赖这些空字段判断模型能力。

Gemini 协议的模型列表请用 /v1beta/models 路径，不要在 /v1/models 上带 Gemini 请求头。

不带 /v1 前缀

客户端把 Base URL 配成不带 /v1（例如 https://api.routeapi.ai）时，GET /models 同样可用，内部会改写回 /v1/models。

决定列表内容的四道过滤

模型出现在你的列表里，需要同时通过四道过滤。排查”模型不在列表中”时按这个顺序看：

1. Token 模型白名单 — 如果这个 Token 启用了模型限制，列表就是白名单与其余条件的交集。未启用则进入下一条。
2. 分组已启用模型 — 取你所属用户分组（及 Token 指定分组）下已启用的模型并集。模型没有任何可用渠道就不会出现。
3. 目录上架状态 — 平台开启严格元数据模式时，未上架的模型对外等同不存在。
4. 是否已配价 — 未配置价格的模型默认被过滤掉，除非平台开了自用模式，或你的账户设置里开启了「接受未设价模型」。

四道过滤后返回空列表是正常结果，不是错误。分组内模型全部未上架时就会这样。

同一个平台下，不同 Token 的模型列表可以完全不同。用 A Token 查列表、用 B Token 发请求是常见的踩坑方式——排查时务必用同一个 Token 做这两件事。

模型不可用排查

请求报模型相关错误时，先对照错误文案定位到具体环节：

错误文案	HTTP	含义	处理
Model name not specified...	400	请求里 model 为空	补上 model 字段
This token has no access to model {model}	403	模型不在该 Token 的白名单里	在控制台给 Token 加上该模型，或换一个不限模型的 Token
This token has no access to any models	403	Token 启用了模型限制但白名单为空	补全白名单
No valid upstream service	503	模型无可用渠道（未配置、全部禁用或熔断中）	确认模型 ID 拼写；换用列表里的其他模型；联系平台管理员
The model '{model}' does not exist	200（体内 error）	GET /v1/models/{model} 查不到或不可见	用 GET /v1/models 确认准确 ID

排查顺序：

1. 用同一个 Token 调 GET /v1/models，确认模型确实在列表里。
2. 逐字符核对 model 拼写，包括大小写和连字符。模型 ID 严格匹配。
3. 确认调用的端点在该模型的 supported_endpoint_types 里。
4. 以上都对但仍失败，说明问题在渠道侧（无可用上游或上游报错），到控制台日志按 request ID 查具体上游响应。详见错误与调试。

最佳实践

• 固定模型 ID，不要用控制台展示名或临时别名。请求只认 id。
• 启动时拉一次列表并缓存，不要每次业务请求都查。可用模型集合变化频率很低。
• 不要用 created 排序，它是所有模型共享的固定占位值。
• 关键链路准备备用模型，在主模型返回 503 时切换。
• 上线前用生产 Token 实测一次，模型列表和一次真实调用都要跑，覆盖工具调用、图像输入等你实际用到的能力——这些能力列表接口不保证。

接下来

• 认证方式 — Token 权限、模型白名单和额度配置。
• Chat Completions — 用列表里的模型发起对话。
• 错误与调试 — 完整状态码与排查顺序。
• 计费与额度 — 模型价格与用量口径。