模型列表

模型可用性会随账号分组、通道状态和服务配置变化。GET /v1/models 是当前账号可见模型的权威来源。

查询接口

GET https://api.topapis.cn/v1/models
Authorization: Bearer YOUR_API_KEY

curl "https://api.topapis.cn/v1/models" \
  -H "Authorization: Bearer $TOPAPIS_API_KEY"

OpenAI 兼容响应通常使用以下结构：

{
  "object": "list",
  "data": [
    {
      "id": "YOUR_MODEL",
      "object": "model",
      "owned_by": "provider"
    }
  ]
}

调用模型时，将 data[].id 原样写入请求体的 model 字段。

选择接口族

模型名称本身不能完全说明请求协议。应根据模型用途选择对应接口族：

用途	常用接口
文本与对话	POST /v1/chat/completions
OpenAI 兼容图片	POST /v1/images/generations
Gemini 原生图像	POST /v1beta/models/{model}:generateContent
SD2.0 异步视频	POST /v1/video/generations
Grok 异步视频	POST /v1/videos/generations

具体模型页会说明请求体、任务轮询和返回格式。

可用性原则

• 控制台展示或其他账号返回的模型，不代表当前密钥一定可用。
• 模型标识区分大小写时，应完全保留接口返回值。
• 收到 403 或模型不可用错误时，先重新查询 /v1/models，再检查账号分组和令牌权限。
• 长期运行的应用可以缓存模型列表，但应设置过期时间，并允许配置覆盖。
• 不应把文档中的示例模型名称当作永久服务承诺。

启动时检查

生产应用可以在启动或健康检查阶段验证目标模型是否存在：

const response = await fetch('https://api.topapis.cn/v1/models', {
  headers: {
    Authorization: `Bearer ${process.env.TOPAPIS_API_KEY}`,
  },
})

if (!response.ok) {
  throw new Error(`Model discovery failed with HTTP ${response.status}`)
}

const payload = await response.json()
const modelIds = new Set(payload.data.map((model) => model.id))

if (!modelIds.has(process.env.TOPAPIS_MODEL)) {
  throw new Error('Configured model is not visible to this API key')
}

此检查只验证模型可见性，不替代实际请求的错误处理。