> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aihubmix.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 模型管理API

> 本API文档提供了对模型管理接口的详细说明，包括新版本和旧版本接口的功能、请求示例、参数说明及响应格式。

## 新版本接口

### 获取模型信息平台

**接口地址**：`GET https://aihubmix.com/api/v1/models`

**功能描述**：获取所有可用模型的详细信息。

### 模型对象字段说明

<ResponseField name="data" type="array">
  模型信息列表数组
</ResponseField>

<ResponseField name="model_id" type="string">
  模型唯一标识符
</ResponseField>

<ResponseField name="desc" type="string">
  模型功能描述（英文）
</ResponseField>

<ResponseField name="types" type="string">
  模型类型，支持值：`llm`（大语言模型）、`image_generation`（图片生成模型）、`video`（视频生成模型）、`tts`（语音合成模型）、`stt`(语音转文本模型)、`embedding`（嵌入模型）、`rerank`（排序模型）
</ResponseField>

<ResponseField name="features" type="string">
  支持的功能特性，支持值：`thinking`（支持思考推理）、`tools`（支持工具调用）、`function_calling`（支持函数调用）、`web`（支持搜索）、`deepsearch`（支持深度搜索）、`long_context`（长上下文模型）、`structured_outputs`（结构化输出）
</ResponseField>

<ResponseField name="input_modalities" type="string">
  支持的输入模态，支持值：`text`（文本）、`image`（图像）、`audio`（音频） 、`video`（视频）、`pdf`
</ResponseField>

<ResponseField name="max_output" type="string">
  最大输出Token数量
</ResponseField>

<ResponseField name="context_length" type="string">
  上下文窗口大小（最大输入Token数量）
</ResponseField>

<ResponseField name="pricing" type="object">
  价格信息对象
</ResponseField>

<ResponseField name="pricing.input" type="number">
  输入Token价格（每1K Token，美元）
</ResponseField>

<ResponseField name="pricing.output" type="number">
  输出Token价格（每1K Token，美元）
</ResponseField>

<ResponseField name="pricing.cache_read" type="number">
  缓存读取价格（每1K Token，美元，可选字段）
</ResponseField>

<ResponseField name="pricing.cache_write" type="number">
  缓存写入价格（每1K Token，美元，可选字段）
</ResponseField>

### 请求示例

<CodeGroup>
  ```python Python theme={null}
  import requests

  # 接口地址
  url = "https://aihubmix.com/api/v1/models"

  response = requests.get(url)
  print(response.json())

  params = {
      "type": "llm",                   
  	"modalities": "text",
  	"model": "gpt-5",
  	"features": "thinking",
      "sort_by": "context_length",
      "sort_order": "desc"    
  }
  response = requests.get(url, params=params)
  print(response.json())
  ```

  ```javascript JavaScript theme={null}
  fetch('https://aihubmix.com/api/v1/models')
    .then(response => response.json())
    .then(data => console.log(data));

  const params = new URLSearchParams({
    type: 'llm',
    modalities: 'text',
    model: 'gpt-5',
    features: 'thinking',
    sort_by: 'context_length',
    sort_order: 'desc' 
  });

  fetch(`https://aihubmix.com/api/v1/models?${params}`)
    .then(response => response.json())
    .then(data => console.log(data));
  ```

  ```bash cURL theme={null}
  curl -X GET "https://aihubmix.com/api/v1/models"

  curl -X GET "https://aihubmix.com/api/v1/models?type=llm&modalities=text&model=gpt-5&features=thinking&sort_by=context_length&sort_order=desc"
  ```
</CodeGroup>

### 请求参数说明（可用于筛选）

<ParamField query="type" path="string" type="string">
  模型类型。支持值：`llm`（大语言模型）、`image_generation`（图片生成模型）、`video`（视频生成模型）、`tts`（语音合成模型）、`stt`(语音转文本模型)、`embedding`（嵌入模型）、`rerank`（排序模型）
</ParamField>

<ParamField query="modalities" path="param" type="string">
  输入模态。支持值：`text`(文本)、`image`（图像）、`audio` （音频）、`video`（视频）、`pdf`，支持多模态查询（逗号分隔）
</ParamField>

<ParamField query="model" path="param" type="string">
  模型名称模糊搜索（支持部分匹配）
</ParamField>

<ParamField query="features" path="param" type="string">
  模型功能特性。支持值：`thinking`（支持思考推理）、`tools`（支持工具调用）、`function_calling`（支持函数调用）、`web`（支持搜索）、`deepsearch`（支持深度搜索）、`long_context`（长上下文模型）、`structured_outputs`（结构化输出），支持多功能查询（逗号分隔）
</ParamField>

<ParamField query="sort_by" path="string" type="string">
  排序字段。支持值：\
  • `model_ratio`：按性价比排序\
  • `context_length`：按上下文长度排序\
  • `coding`：编程模型优先排序\
  • `order`：按默认顺序排序
</ParamField>

<ParamField query="sort_order" path="string" type="string">
  排序方向。支持值：\
  • `asc`（升序） \
  • `desc`（降序）
</ParamField>

### 响应成功示例

```json theme={null}
{
    "data": [
        {
            "model_id": "gpt-5",
            "desc": "GPT-5 is OpenAI flagship model for coding, reasoning, and agentic tasks across domains.",
            "pricing": {
                "cache_read": 0.125,
                "input": 1.25,
                "output": 10
            },
            "types": "llm",
            "features": "thinking,tools,function_calling,structured_outputs",
            "input_modalities": "text,image",
            "max_output": 128000,
            "context_length": 400000
        },
        {
            "model_id": "gpt-5-codex",
            "desc": "GPT-5-Codex is a version of GPT-5 optimized for autonomous coding tasks in Codex or similar environments. It is only available in the Responses API, and the underlying model snapshots will be updated regularly. https://docs.aihubmix.com/en/api/Responses-API You can also use it in codex-cll; see https://docs.aihubmix.com/en/api/Codex-CLI for using codex-cll through Aihubmix.",
            "pricing": {
                "cache_read": 0.125,
                "input": 1.25,
                "output": 10
            },
            "types": "llm",
            "features": "thinking,tools,function_calling,structured_outputs",
            "input_modalities": "text,image",
            "max_output": 128000,
            "context_length": 400000
        },
        {
            "model_id": "gpt-5-mini",
            "desc": "GPT-5 mini is a faster, more cost-efficient version of GPT-5. It's great for well-defined tasks and precise prompts.",
            "pricing": {
                "cache_read": 0.025,
                "input": 0.25,
                "output": 2
            },
            "types": "llm",
            "features": "thinking,tools,function_calling,structured_outputs",
            "input_modalities": "text,image",
            "max_output": 128000,
            "context_length": 400000
        },
        {
            "model_id": "gpt-5-nano",
            "desc": "GPT-5 Nano is our fastest, cheapest version of GPT-5. It's great for summarization and classification tasks.",
            "pricing": {
                "cache_read": 0.005,
                "input": 0.05,
                "output": 0.4
            },
            "types": "llm",
            "features": "thinking,tools,function_calling,structured_outputs",
            "input_modalities": "text,image",
            "max_output": 128000,
            "context_length": 400000
        },
        {
            "model_id": "gpt-5-pro",
            "desc": "GPT-5 pro uses more compute to think harder and provide consistently better answers.\n\nGPT-5 pro is available in the Responses API only to enable support for multi-turn model interactions before responding to API requests, and other advanced API features in the future. Since GPT-5 pro is designed to tackle tough problems, some requests may take several minutes to finish. To avoid timeouts, try using background mode. As our most advanced reasoning model, GPT-5 pro defaults to (and only supports) reasoning.effort: high. GPT-5 pro does not support code interpreter.",
            "pricing": {
                "input": 15,
                "output": 120
            },
            "types": "llm",
            "features": "thinking,tools,function_calling,structured_outputs",
            "input_modalities": "text,image",
            "max_output": 128000,
            "context_length": 400000
        }
    ],
    "message": "",
    "success": true
}
```

### 使用场景示例

<CodeGroup>
  ```bash 获取所有大语言模型 theme={null}
  GET https://aihubmix.com/api/v1/models?type=llm
  ```

  ```bash 获取适合编程的模型，按上下文长度排序 theme={null}
  GET https://aihubmix.com/api/v1/models?tag=coding&sort_by=context_length&sort_order=desc
  ```

  ```bash 搜索特定模型 theme={null}
  GET https://aihubmix.com/api/v1/models?model=gpt-5
  ```

  ```bash 复合条件查询 theme={null}
  GET https://aihubmix.com/api/v1/models?type=llm&modalities=text,image&features=function_calling&sort_by=model_ratio&sort_order=asc
  ```

  ```bash 编程模型智能排序 theme={null}
  GET https://aihubmix.com/api/v1/models?sort_by=coding
  ```
</CodeGroup>

> **说明**：在使用编程模型智能排序时，系统会优先展示包含 `coding` 标签的模型，其他模型按默认顺序排列。

### 性能优化

#### 缓存机制

* **缓存策略**：HTTP缓存，缓存时长300秒（5分钟）
* **缓存控制**：`Cache-Control: public, max-age=300, stale-while-revalidate=300`
* **内容验证**：支持ETag内容哈希验证

#### 缓存使用示例

```bash theme={null}
# 使用ETag进行条件请求
curl -H "If-None-Match: \"abc123...\"" \
     https://aihubmix.com/api/v1/models
```

> 如果内容未更新，服务器返回 `304 Not Modified` 状态码。

### 错误处理

<CodeGroup>
  ```json 400 请求参数错误 theme={null}
  {
    "success": false,
    "message": "请求参数格式错误"
  }
  ```

  ```json 500 服务器内部错误 theme={null}
  {
    "success": false,
    "message": "服务器内部错误，请稍后重试"
  }
  ```
</CodeGroup>

### 重要说明

1. **数据完整性**：此接口返回所有符合条件的模型，不进行分页处理
2. **类型兼容性**：支持新旧类型标识的自动映射
   * `t2t` ↔ `llm`
   * `t2i` ↔ `image_generation`
   * `t2v` ↔ `video`
   * `reranking` ↔ `rerank`
3. **筛选逻辑**：多个筛选条件之间为逻辑与（AND）关系
4. **排序规则**：未指定排序方式时，默认按系统预设顺序排列

***

## 旧版本接口

> ⚠️ **注意**：以下为旧版本接口，建议优先使用新版本接口以获得更好的性能和功能体验。

### 获取模型列表

端点（Endpoint）： `GET /v1/models`

* 有用户登录获取用户分组下的可用列表，无用户登录获取 default 分组下的可用列表。
* header 中有 Authorization 字段则查询 key 对应的 token 下配置的模型列表。

**返回示例：**

```json theme={null}
{
  "data": [
    {
      "id": "gpt-4o-mini",
      "object": "model",
      "created": 1626777600,
      "owned_by": "OpenAI",
      "permission": [
        {
          "id": "modelperm-LwHkVFn8AcMItP432fKKDIKJ",
          "object": "model_permission",
          "created": 1626777600,
          "allow_create_engine": true,
          "allow_sampling": true,
          "allow_logprobs": true,
          "allow_search_indices": false,
          "allow_view": true,
          "allow_fine_tuning": false,
          "organization": "*",
          "group": null,
          "is_blocking": false
        }
      ],
      "root": "gpt-4o-mini",
      "parent": null
    }
  ]
}
```

### 返回结果

| 状态码 | 状态码含义 | 说明   | 数据模型   |
| --- | ----- | ---- | ------ |
| 200 | OK    | none | Inline |

### 返回数据结构

状态码 **200**

| 名称                         | 类型             | 必选   | 约束   | 中文名   | 说明   |
| -------------------------- | -------------- | ---- | ---- | ----- | ---- |
| » data                     | \[object]      | true | none |       | none |
| »» id                      | string         | true | none | 模型 ID | none |
| »» object                  | string         | true | none | model | none |
| »» created                 | integer        | true | none | 创建时间  | none |
| »» owned\_by               | string         | true | none | 开发者   | none |
| »» permission              | \[object]¦null | true | none |       | none |
| »»» id                     | string         | true | none |       | none |
| »»» object                 | string         | true | none |       | none |
| »»» created                | integer        | true | none |       | none |
| »»» allow\_create\_engine  | boolean        | true | none |       | none |
| »»» allow\_sampling        | boolean        | true | none |       | none |
| »»» allow\_logprobs        | boolean        | true | none |       | none |
| »»» allow\_search\_indices | boolean        | true | none |       | none |
| »»» allow\_view            | boolean        | true | none |       | none |
| »»» allow\_fine\_tuning    | boolean        | true | none |       | none |
| »»» organization           | string         | true | none |       | none |
| »»» group                  | null           | true | none |       | none |
| »»» is\_blocking           | boolean        | true | none |       | none |
| »» root                    | string         | true | none | 模型名称  | none |
| »» parent                  | null           | true | none | 父节点   | none |

### 获取模型信息

端点（Endpoint）：`GET /v1/models/:model`

### 请求参数

| 名称    | 位置   | 类型     | 必选 | 说明    |
| ----- | ---- | ------ | -- | ----- |
| model | path | string | 是  | 模型 ID |

**返回示例：**

```json theme={null}
200 Response
```

```json theme={null}
{
  "id": "string",
  "object": "string",
  "created": 0,
  "owned_by": "string",
  "permission": [
    {
      "id": "string",
      "object": "string",
      "created": 0,
      "allow_create_engine": true,
      "allow_sampling": true,
      "allow_logprobs": true,
      "allow_search_indices": true,
      "allow_view": true,
      "allow_fine_tuning": true,
      "organization": "string",
      "group": null,
      "is_blocking": true
    }
  ],
  "root": "string",
  "parent": null
}
```

### 返回结果

| 状态码 | 状态码含义 | 说明   | 数据模型   |
| --- | ----- | ---- | ------ |
| 200 | OK    | none | Inline |

### 返回数据结构

状态码 **200**

| 名称                       | 类型        | 必选    | 约束   | 中文名   | 说明   |
| ------------------------ | --------- | ----- | ---- | ----- | ---- |
| id                       | string    | true  | none | 模型 ID | none |
| object                   | string    | true  | none | model | none |
| created                  | integer   | true  | none | 创建时间  | none |
| owned\_by                | string    | true  | none | 开发者   | none |
| permission               | \[object] | true  | none |       | none |
| » id                     | string    | false | none |       | none |
| » object                 | string    | false | none |       | none |
| » created                | integer   | false | none |       | none |
| » allow\_create\_engine  | boolean   | false | none |       | none |
| » allow\_sampling        | boolean   | false | none |       | none |
| » allow\_logprobs        | boolean   | false | none |       | none |
| » allow\_search\_indices | boolean   | false | none |       | none |
| » allow\_view            | boolean   | false | none |       | none |
| » allow\_fine\_tuning    | boolean   | false | none |       | none |
| » organization           | string    | false | none |       | none |
| » group                  | null      | false | none |       | none |
| » is\_blocking           | boolean   | false | none |       | none |
| root                     | string    | true  | none | 模型名称  | none |
| parent                   | null      | true  | none | 父节点   | none |

***

更新时间：2026-06-01