# 模型列表与名称映射

> 获取当前虚拟密钥可用的 APIMart 模型，了解返回字段及公共名称、平台模型和旧别名的对应关系。

Base URL：`https://platform.sgt.site/apimart/v1`

| 方法 | 完整请求地址 | 用途 |
| --- | --- | --- |
| GET | `https://platform.sgt.site/apimart/v1/models` | 查询当前密钥可以使用的 APIMart 模型公共名称与类型 |

此接口用于获取客户端可选模型列表，或在提交前取得合法的 `model`。它返回当前主体和虚拟密钥权限范围内、具备可用渠道的模型；媒体型号还必须已有 APIMart 适配，且当前主体属于企业。它不是所有厂商型号的公开清单，也不返回任务列表、价格或模型参数详情。读取目录不调用模型服务，不产生模型生成费用。

<a id="apimart-models-h-af214442"></a>

## 请求参数与鉴权

| 位置 | 名称 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- | --- |
| Header | `Authorization` | string | 是 | `Bearer YOUR_VIRTUAL_KEY`，使用完整的平台虚拟密钥；配置方式见[地址与接口](apimart-access.md) |
| Query | `category` | string | 否 | `image`：图片；`video`：视频；`chat`：文本对话。省略或空值返回所有可用类别；其他非空值返回 400 |
| Query | `expand` | string | 否 | 当前未实现扩展元数据；不要传入非空值，`expand=parameters` 等请求返回 400 |

请求无正文。接口不支持分页，一次返回当前筛选条件下的完整数组，没有 `page`、`limit` 或游标约定。若所需字段未列出，不要猜测请求参数；图片、视频支持的参数分别见[图片生成](apimart-images.md)和[视频生成](apimart-videos.md)。

<a id="apimart-models-h-5f6c9c30"></a>

## 请求示例

获取所有可用 APIMart 模型：

```bash
curl --request GET "https://platform.sgt.site/apimart/v1/models" \
  --header "Authorization: Bearer YOUR_VIRTUAL_KEY"
```

只获取图片模型：

```bash
curl --request GET "https://platform.sgt.site/apimart/v1/models?category=image" \
  --header "Authorization: Bearer YOUR_VIRTUAL_KEY"
```

查询视频时将 `category=image` 改为 `category=video`，查询文本对话时改为 `category=chat`。示例中的地址为当前网关地址，`YOUR_VIRTUAL_KEY` 是需自行替换的占位值。

<a id="apimart-models-h-be8d2d64"></a>

## 成功响应

HTTP 200。以下是图片目录示例，保留了选模型的主要字段；实际返回数量取决于授权、有效价格和渠道情况，不保证出现示例型号。

```json
{
  "success": true,
  "object": "list",
  "data": [
    {
      "id": "seedream-5-0-lite",
      "object": "model",
      "created": 1626777600,
      "owned_by": "platform",
      "category": "image"
    }
  ]
}
```

| 字段 | 类型 | 含义与使用方式 |
| --- | --- | --- |
| `success` | boolean | 目录读取成功时为 `true` |
| `object` | string | 固定为 `list` |
| `data` | object[] | 当前筛选条件下的模型数组；无匹配项时为 `[]` |
| `data[].id` | string | APIMart 公共模型名称，直接用于后续生成或对话请求的 `model`；区分大小写 |
| `data[].category` | string | `image`、`video` 或 `chat`，决定应使用哪一类调用接口 |
| `data[].object` | string | 固定为 `model` |
| `data[].created` | integer | 模型元数据中的兼容时间戳（秒）；不是该型号的实际上架时间或发布时间 |
| `data[].owned_by` | string | 模型来源展示标识；企业管理模式下为 `platform`，不能据此推断底层渠道或价格 |
| `data[].supported_endpoint_types` | string[] 或 null | 平台补充的模型协议能力标识，不是 APIMart 参数列表 |
| `data[].native_endpoint_types` | string[] 或 null | 平台补充的原生协议能力；媒体条目可能为 null |
| `data[].public_endpoints` | object，可省略 | 平台补充的公开端点元数据，各项含 `path` 与 `method`；APIMart 客户端仍按本栏目的分类路由调用，不把公共别名直接套到其他协议路径 |

基础接入只需读取 `data[].id` 和 `data[].category`。响应可能增加字段，不要把数组下标当作固定模型编号。内部名称和别名会合并为一个公共条目，不会作为不同产品重复返回。

<a id="apimart-models-h-71fed230"></a>

## 空列表与错误处理

没有匹配模型仍返回 HTTP 200：

```json
{
  "success": true,
  "object": "list",
  "data": []
}
```

先确认 `category`，再检查当前主体的模型授权和虚拟密钥的模型限制。图片、视频目录还要求企业主体；平台未上架对应型号、有效价格不可用或渠道停用时，也可能没有可用条目。下方映射表列出平台已适配的名称，不承诺当前密钥能使用表内全部型号。

请求参数错误示例，HTTP 400：

```json
{
  "error": {
    "code": 400,
    "message": "unsupported category",
    "type": "invalid_request_error"
  },
  "request_id": "request_example"
}
```

| HTTP | `error.type` | 处理方式 |
| --- | --- | --- |
| 400 | `invalid_request_error` | 检查 `category` 是否为三个合法值之一；移除非空 `expand` |
| 401 | `authentication_error` | 检查完整虚拟密钥、Bearer 格式及密钥是否有效；已停用、过期或额度耗尽的密钥也不能读取此目录 |
| 403 | `permission_error` | 检查消费身份、所属组织、IP 限制等访问条件；具体原因见 `error.message` |
| 429 | `rate_limit_error` | 降低目录读取频率，退避后重试，避免每次界面渲染都请求目录 |
| 500 | `server_error` | 目录读取异常，保存 `request_id` 供排查 |
| 503 | `bad_gateway` | 平台暂时不可用，退避后重试只读目录请求 |

错误正文结构见[HTTP 错误](apimart-errors.md)。重试目录 GET 请求不会提交生成任务；生成提交的重试规则不可据此类推。

<a id="apimart-models-h-9c98c83e"></a>

## 取得模型后如何调用

| `category` | 后续接口 | 下一步 |
| --- | --- | --- |
| `image` | `POST /apimart/v1/images/generations` | 将 `id` 放入 `model`，按[图片生成](apimart-images.md)补充 `prompt` 和尺寸参数 |
| `video` | `POST /apimart/v1/videos/generations` | 将 `id` 放入 `model`，按[视频生成](apimart-videos.md)补充提示词、时长或参考媒体 |
| `chat` | `POST /apimart/v1/chat/completions` | 将 `id` 放入 `model`，使用 Chat Completions 的 `messages` 和可选 `stream` |

图片、视频提交后保存响应中的 `task_id`，按[任务查询与结算](apimart-tasks.md)读取结果。目录只反映读取当时的可用模型，提交时仍会重新校验授权、参数与预算。

以下两表为模型名称对照。新客户端优先使用目录返回的公共名称；已列出的平台内部名称和旧别名仍可提交，但不会扩大授权或绕过模型限制。

<a id="apimart-models-section-1"></a>

## 图片

| APIMart model | 平台原生/内部模型 | 仍接受的其他旧别名 |
| --- | --- | --- |
| `seedream-5-0-lite` | `doubao-seedream-5-0-lite-260128` | — |
| `seedream-5-0-pro` | `doubao-seedream-5-0-pro-260628` | `seedream-5.0-pro` |
| `seedream-4.0` | `doubao-seedream-4-0-250828` | `seedream-4-0` |
| `seedream-4.5` | `doubao-seedream-4-5-251128` | `seedream-4-5` |
| `gemini-3.1-flash-image-preview` | `gemini-3.1-flash-image` | `nano-banana-2`、`nano-banana-2-ext` |
| `gemini-3-pro-image-preview` | `gemini-3-pro-image` | `nano-banana-pro` |
| `gemini-3.1-flash-lite-image` | `gemini-3.1-flash-lite-image` | `nano-banana-2-lite` |
| `gemini-2.5-flash-image-preview` | `gemini-2.5-flash-image` | `nano-banana` |
| `doubao-seedream-5-0-260128` | 同名 | 平台扩展型号，APIMart 官方无对应型号 |

<a id="apimart-models-section-2"></a>

## 视频

| APIMart model | 平台原生/内部模型 | 仍接受的其他旧别名 |
| --- | --- | --- |
| `seedance-2.0` | `doubao-seedance-2-0-260128` | `seedance-2-0` |
| `seedance-2.0-fast` | `doubao-seedance-2-0-fast-260128` | — |
| `seedance-2.0-mini` | `doubao-seedance-2-0-mini-260615` | — |
| `seedance-2.5` | `doubao-seedance-2-5-260628` | — |
| `MiniMax-H3` | `MiniMax-H3` | `minimax-h3` |
| `kling-v3` | `kling-3.0` | — |
| `kling-3.0-turbo` | `kling-3.0-turbo` | — |
| `kling-v3-omni` | `kling-3.0-omni` | — |

型号名称区分大小写，使用表中写法；平台仅对明确列出的别名提供兼容。别名不代表不同价格产品，也不会自动切换不同厂商通道。