# 模型列表

> 查询当前虚拟密钥可用的模型：图片、视频和 3D 用 GET /media/v1/models；GET /v1/models 是含全部类型的通用目录，文本模型从中筛选；含返回示例、字段说明、名称映射和各媒体模型的输入方式；参数取值见各生成页。

调用模型前，先查这把密钥能用哪些模型，再把返回的模型 ID **原样**填进请求的 `model`；如果 `id` 是 `Nano Banana 2 Lite`，就保留空格使用这个名称，不自行换成内部型号。仅用于说明的系列简称不能代替目录 ID。按要调用的能力选择查询接口：

| 查询接口 | 用于 | 返回内容 |
| --- | --- | --- |
| `GET /media/v1/models` | [图片、视频、3D 生成](models.md#models-media) | 只含媒体模型：模型 ID、生成类型、每个参数的取值范围和可传的参考素材 |
| `GET /v1/models` | [通用模型目录；文本对话从这里取 ID](models.md#models-text) | 全部可用模型（文本、图片、视频、3D 等）的 ID、调用协议和请求地址；只要文本模型时按[只列出文本模型](models.md#models-text-filter)筛选 |

两个查询都只读取平台目录，不提交生成，也不产生费用。本页各表列出的模型不代表你的密钥已获授权：实际能用哪些模型以查询返回为准，没有授权的模型请联系管理员开通。


能力描述中的默认值用于构造请求，不保证每个产物的文件格式。特别是 3D 的模型 ID、`output_format` 和 `kind=model3d` 不能唯一确定返回文件类型；五款型号的默认与模式差异见[3D 默认输出](media-3d.md)，多图和视频结果见[任务产物](media-tasks.md#media-tasks-h-faa3e87e)。未知或未声明的格式不能按 GLB/PNG/MP4 命名。

<a id="models-media"></a>

## 媒体模型

图片、视频和 3D 模型用 `GET /media/v1/models` 查询。返回结果说明这把密钥能用哪些模型、每个模型提交到哪个地址、每个参数能填什么、能传哪些参考素材。结果中只有模型 ID，展示名称对应哪个 ID 见[媒体模型名称映射](models.md#models-media-names)。

<a id="models-media-list"></a>

### 查询媒体模型列表

先按[地址与鉴权](access.md)设置 `GATEWAY_ORIGIN` 和 `KEY`。查询只读取平台目录，不触发生成，也不产生费用。

```bash
# 全部媒体模型
curl -s "$GATEWAY_ORIGIN/media/v1/models" \
  -H "Authorization: Bearer $KEY"

# 只看某一类：category 可选 image、video、3d
curl -s "$GATEWAY_ORIGIN/media/v1/models?category=video" \
  -H "Authorization: Bearer $KEY"

# 只看一个模型：路径里放模型 ID
curl -s "$GATEWAY_ORIGIN/media/v1/models/kling-3.0" \
  -H "Authorization: Bearer $KEY"

# 含空格的公开名称按 URL 路径编码；JSON model 仍使用原名
curl -s "$GATEWAY_ORIGIN/media/v1/models/Nano%20Banana%202%20Lite" \
  -H "Authorization: Bearer $KEY"
```

| 查询参数 | 说明 |
| --- | --- |
| `category` | 可选。取 `image`、`video` 或 `3d`，区分大小写；省略时返回全部。`audio` 也能通过校验，但目前没有音频模型，固定返回空列表；其他值返回 400 `invalid_request` |
| 路径中的模型 ID | 只查一个模型时使用，必须与列表中的 `id` 完全一致；含 URL 特殊字符时先做 URL 编码 |

列表没有分页，一次返回当前条件下的全部可用模型。

装有 `jq` 时，可以只列出类型和模型 ID：

```bash
curl -s "$GATEWAY_ORIGIN/media/v1/models" \
  -H "Authorization: Bearer $KEY" | jq -r '.data[] | [.type, .id] | @tsv'
```

```text
image   doubao-seedream-5-0-lite-260128
video   kling-3.0
3d      hy-3d-express
```

查询结果在一段时间内基本不变，建议在应用里缓存，不要每次提交前都重新查询；读取过于频繁会返回 429 `rate_limited`。

<a id="models-h-2fada320"></a>

### 媒体模型返回示例

假设你的密钥能用 Seedream 5 Lite、可灵 3.0 和混元 3D Express 三个模型，`GET /media/v1/models` 返回 HTTP 200，正文如下。内容与平台实际返回一致，只调整了换行和缩进：

**完整返回 JSON（Seedream 5 Lite、可灵 3.0、混元 3D Express）**

```json
{
  "object": "list",
  "data": [
    {
      "id": "doubao-seedream-5-0-lite-260128",
      "object": "media.model",
      "type": "image",
      "provider": "volcengine",
      "sync": true,
      "supports_cancel": false,
      "capability_version": 1,
      "parameters": {
        "aspect_ratio": {"type": "string", "enum": ["1:1", "4:3", "3:4", "16:9", "9:16", "3:2", "2:3", "21:9"]},
        "n": {"type": "integer", "minimum": 1, "maximum": 15, "default": 1},
        "output_format": {"type": "string", "enum": ["jpeg", "png"]},
        "prompt": {"type": "string", "required": true},
        "resolution": {"type": "string", "enum": ["2K", "3K", "4K"], "default": "2K"},
        "size": {"type": "string"}
      },
      "references": [
        {"role": "reference", "types": ["image"], "max_count": 14, "max_bytes": 10485760, "supports_asset": true, "requires_asset": false}
      ],
      "provider_options_schema": {
        "additionalProperties": false,
        "properties": {
          "volcengine": {
            "additionalProperties": false,
            "properties": {
              "watermark": {"type": "boolean", "default": false}
            },
            "type": "object"
          }
        },
        "type": "object"
      }
    },
    {
      "id": "kling-3.0",
      "object": "media.model",
      "type": "video",
      "provider": "kling",
      "sync": false,
      "supports_cancel": false,
      "capability_version": 1,
      "parameters": {
        "aspect_ratio": {"type": "string", "enum": ["16:9", "9:16", "1:1"], "default": "16:9"},
        "duration": {"type": "integer", "minimum": 3, "maximum": 15, "default": 5},
        "generate_audio": {"type": "boolean", "default": false},
        "prompt": {"type": "string", "required": true, "minLength": 1, "maxLength": 3072},
        "resolution": {"type": "string", "enum": ["720p", "1080p", "4k"], "default": "720p"}
      },
      "references": [
        {"role": "first_frame", "types": ["image"], "max_count": 1, "max_bytes": 10485760, "supports_asset": false, "requires_asset": false},
        {"role": "last_frame", "types": ["image"], "max_count": 1, "max_bytes": 10485760, "supports_asset": false, "requires_asset": false}
      ],
      "provider_options_schema": {
        "additionalProperties": false,
        "properties": {
          "kling": {
            "additionalProperties": false,
            "properties": {
              "multi_shot": {"type": "boolean"},
              "watermark": {"type": "boolean"}
            },
            "type": "object"
          }
        },
        "type": "object"
      }
    },
    {
      "id": "hy-3d-express",
      "object": "media.model",
      "type": "3d",
      "provider": "tencent",
      "sync": false,
      "supports_cancel": false,
      "capability_version": 1,
      "parameters": {
        "output_format": {"type": "string", "enum": ["obj", "glb", "stl", "usdz", "fbx", "mp4"]},
        "prompt": {"type": "string"}
      },
      "references": [
        {"role": "reference", "types": ["image"], "max_count": 1, "max_bytes": 10485760, "supports_asset": false, "requires_asset": false}
      ],
      "provider_options_schema": {
        "additionalProperties": false,
        "properties": {
          "tencent": {
            "additionalProperties": false,
            "properties": {
              "enable_geometry": {"type": "boolean", "default": false},
              "enable_pbr": {"type": "boolean", "default": false}
            },
            "type": "object"
          }
        },
        "type": "object"
      }
    }
  ]
}
```

读结果时注意：

- 返回中只有模型 ID，没有展示名称；两者的对应关系见下方[媒体模型名称映射](models.md#models-media-names)。
- `data` 的顺序不代表推荐，请按 `id` 查找模型，不要按数组下标取用。
- 单模型查询返回的就是 `data` 中的一个元素，外面没有 `object: "list"` 和 `data`。
- 没有可用模型时返回 `{"object":"list","data":[]}`，这不是报错。排查方法见下方[媒体模型空列表与报错](models.md#models-media-errors)。

<a id="models-media-fields"></a>

### 媒体模型返回字段

外层只有两个字段：`object` 固定为 `"list"`，`data` 是当前密钥可用的模型数组。数组里每个模型对象的字段如下：

| 字段 | 示例值 | 含义与用法 |
| --- | --- | --- |
| `id` | "kling-3.0" | 模型 ID，原样填入生成请求的 `model` |
| `object` | "media.model" | 固定值，表示这是一个模型能力对象 |
| `type` | "video" | 生成类型，取值 `image`、`video`、`3d`，决定提交地址：图片 `/media/v1/images/generations`，视频 `/media/v1/videos/generations`，3D `/media/v1/3d/generations`。提交到不匹配的地址返回 400 |
| `provider` | "kling" | 厂商选项的命名空间，当前包括 `volcengine`、`gemini`、`openai`、`kling`、`minimax`、`tencent`；GPT Image 使用 `openai`。客户端应兼容响应中后续新增的值，实际可用选项以 `provider_options_schema` 为准。厂商选项要写在 `provider_options` 下以它命名的对象里，例如 `"provider_options": {"kling": {...}}` |
| `sync` | false | 上游是否同步生成。为 `true`（目前只有图片模型）时，提交时带 `"wait": 50` 通常一次就能拿到结果；为 `false` 时，提交后按任务 ID 轮询。两种情况平台返回的都是任务对象 |
| `supports_cancel` | false | 能否取消已提交的任务。为 `false` 时不要调用取消接口；目前只有 Seedance 为 `true` |
| `capability_version` | 1 | 能力描述的格式版本，目前都是 `1`，不影响请求写法 |
| `parameters` | 对象 | 该模型接受的生成参数。键名就是请求里的字段名，键值描述类型和取值，见下表 |
| `references` | 数组 | 该模型接受的参考素材，每项是一种角色加类型，见下文 |
| `provider_options_schema` | 对象 | `provider_options` 里允许出现的厂商选项，见下文 |

`parameters` 中每个参数可能带以下子字段：

| 子字段 | 示例 | 含义 |
| --- | --- | --- |
| `type` | "integer" | 值的类型：`string` 是带引号的字符串，`integer` 是不带引号的整数，`boolean` 是 `true` 或 `false` |
| `required` | true | 必须填写。没有这个子字段表示可以单独省略，但仍要满足下文“返回结果没有写出的规则” |
| `minimum`、`maximum` | 3、15 | 数字的取值范围，包含两端 |
| `minLength`、`maxLength` | 1、3072 | 字符串的长度范围，按字符计 |
| `enum` | ["720p", "1080p", "4k"] | 只能从这些值中选择，区分大小写 |
| `default` | 5 | 省略该参数时使用的值。没有 `default` 时，省略后的效果由模型或输入方式决定，见各生成页 |

例如可灵 3.0 的 `"duration": {"type": "integer", "minimum": 3, "maximum": 15, "default": 5}` 表示：请求里可以写 `"duration": 8`，不能写成 `"duration": "8"`；不写时生成 5 秒。

`parameters` 只列出该模型特有的生成参数。`model`、`references`、`provider_options`、`metadata`、`wait` 是所有模型共用的请求字段，不在其中重复，见[媒体请求约定](media-access.md)。除这些公共字段外，`parameters` 里没有的字段该模型都不接受，传入会返回 400。

`references` 的每一项描述一种可以传的参考素材：

| 子字段 | 示例 | 含义 |
| --- | --- | --- |
| `role` | "first_frame" | 素材角色，填入请求中 `references[].role` |
| `types` | ["image"] | 该角色接受的素材类型，请求中 `references[].type` 从中选择 |
| `max_count` | 1 | 该角色、该类型最多传几份 |
| `max_bytes` | 10485760 | 单个文件的大小上限，单位为字节。10485760 即 10 MiB，209715200 即 200 MiB，15728640 即 15 MiB |
| `supports_asset` | false | 能否用素材库的 `asset_id` 引用素材。为 `false` 时只能用 `url` 或 `file_id` |
| `requires_asset` | false | 为 `true` 时只能用 `asset_id`。目前所有模型都为 `false` |

同一角色可能出现多项。例如 Seedance 2.0 的 `reference` 角色分别列出图片（`max_count: 9`）和视频（`max_count: 3`），两种类型各自计数。

`provider_options_schema` 是一段 JSON Schema，按两层 `properties` 往下读：第一层的键（如 `kling`）是命名空间，第二层列出可用选项及其类型；`additionalProperties: false` 表示没有列出的选项一律不接受。以上面可灵 3.0 的返回为例，请求里这样写：

```json
{"provider_options": {"kling": {"watermark": false}}}
```

Nano Banana / Gemini 的 `gemini` 命名空间下没有任何选项，不需要传 `provider_options`。GPT Image 使用 `openai` 命名空间；可选值只在[图片生成](media-images.md)维护。

<a id="models-h-975b0902"></a>

### 从返回结果写出请求

以上面返回的 `kling-3.0` 为例，逐项对照：

| 返回内容 | 请求怎么写 |
| --- | --- |
| `"id": "kling-3.0"`，`"type": "video"` | `"model": "kling-3.0"`，提交到 `POST /media/v1/videos/generations` |
| `prompt` 为 `required`，长度 1–3072 | 必须写 `prompt`，不超过 3072 个字符 |
| `duration` 为整数 3–15，默认 5 | `"duration": 5`，可省略 |
| `resolution` 只能是 `720p`、`1080p`、`4k` | `"resolution": "1080p"`，注意是小写 `p` |
| `generate_audio` 默认 `false` | 需要声音时写 `"generate_audio": true` |
| `references` 有 `first_frame`，最多 1 张图片，不支持素材库 | `{"role": "first_frame", "type": "image", "url": "..."}`，也可以用 `file_id` |
| `provider_options_schema` 的命名空间是 `kling` | 选项写在 `"provider_options": {"kling": {...}}` 里 |
| `sync: false`，`supports_cancel: false` | 提交后按任务 ID 轮询，不能取消 |

得到的请求体：

```json
{
  "model": "kling-3.0",
  "prompt": "画面中的纸船顺着水流缓缓漂远，镜头保持固定",
  "duration": 5,
  "resolution": "1080p",
  "generate_audio": true,
  "references": [
    {"role": "first_frame", "type": "image", "url": "https://files.example.com/boat.png"}
  ],
  "provider_options": {"kling": {"watermark": false}},
  "wait": 0
}
```

提交、轮询和结果读取的完整流程见[视频生成](media-videos.md)。

<a id="models-h-a2d5b37d"></a>

### 返回结果没有写出的规则

能力描述只说明每个字段单独能填什么，不描述字段之间的组合规则。提交前还要对照各生成页，常见的有：

- Seedream 的 `size` 与 `aspect_ratio` 只能二选一。
- 可灵 3.0 的厂商选项里列有 `multi_shot`，但只有 Omni 带参考视频时它才能为 `true`；其他情况传了必须为 `false`，一般直接省略。
- MiniMax H3 的 `aspect_ratio` 没有返回 `default`：纯文生默认 `16:9`，带首帧或首尾帧时只能用 `adaptive`。
- 混元 3D 的 `prompt` 没有标为必填，因为文生和单图二选一：只写 `prompt` 是文生，只传参考图是图生，两者都写会报错（Sketch 模式除外）。
- Seedream 4.5 和 4.0 返回的 `resolution` 列有 `3K`，但目前提交 `3K` 会返回 400，报错 “<模型 ID> resolution must be one of …”。请按[图片生成：Seedream 参数怎么填](media-images.md#media-images-h-b80d0153)选择档位。

<a id="models-media-errors"></a>

### 媒体模型空列表与报错

一个模型同时满足以下条件，才会出现在你的列表里：

- 管理员已为你的企业、部门或账号授权该模型，这把密钥也没有限制它。
- 该模型已上架、配置了有效价格，并且有可用渠道。
- 该模型已接入平台媒体接口。四款 Nano Banana 与三款 GPT Image 已有统一任务适配；仍只提供[厂商原生兼容](official.md)入口的其他模型不会出现在这里。

没有任何模型满足全部条件时，返回 HTTP 200 和 `{"object":"list","data":[]}`。先去掉 `category` 再查一次；仍为空时，请管理员核对授权、上架、价格和渠道。列表里有某个模型，也不保证下一次生成一定成功：提交时平台还会检查最新的权限、预算和渠道状态。

查询失败时，错误格式与生成接口相同，例如查询一个你无权使用的模型：

```json
{
  "error": {
    "code": "model_not_found",
    "message": "Model is not available to the current key",
    "stage": "validation",
    "retryable": false
  },
  "request_id": "req_example"
}
```

| HTTP 状态与错误码 | 原因 | 处理 |
| --- | --- | --- |
| 400 `invalid_request` | `category` 不是允许的值，报错 Unknown model category | 改为 image、video、3d，或去掉该参数 |
| 401 `model_not_authorized` | 没带密钥、密钥填错或已失效 | 按[地址与鉴权](access.md)检查请求头 |
| 403 `model_not_authorized` | 身份、组织状态或 IP 限制不允许读取 | 请管理员核对 |
| 404 `model_not_found` | 单模型查询时 ID 拼错、不在你的可用范围，或没有接入媒体接口 | 从列表返回的 id 原样复制 |
| 429 `rate_limited` | 查询太频繁 | 缓存查询结果，稍等再查 |
| 500 `internal_error` | 平台暂时读不到模型目录 | 稍后重试；持续失败时提供 request_id |

其他错误码见[媒体错误处理](media-errors.md)。

<a id="models-media-names"></a>

### 媒体模型名称映射

查询结果中只有模型 ID。下表给出展示名称与返回字段的对应关系；`provider` 同时是 `provider_options` 中的键名。

Nano Banana 的公开名称本身就是可调用 ID。平台内部复用 Gemini 的能力模板来校验和转换参数，不要求管理员另行上架模板型号，也不要求调用方换名。授权、选渠道、价格、任务及账单保持公开名称；只有所选渠道的模型映射改变发往上游的名称，未配置映射时保留原名。已有 Gemini ID 仍按原来的上架与授权独立可见，不因 Nano Banana 授权自动开放。

| 模型 ID（`id`） | 展示名称 | `type` | `provider` | 能否取消 |
| --- | --- | --- | --- | --- |
| `doubao-seedream-5-0-lite-260128` | Seedream 5 Lite | image | volcengine | 否 |
| `doubao-seedream-5-0-260128` | Seedream 5.0 | image | volcengine | 否 |
| `doubao-seedream-5-0-pro-260628` | Seedream 5 Pro | image | volcengine | 否 |
| `doubao-seedream-4-5-251128` | Seedream 4.5 | image | volcengine | 否 |
| `doubao-seedream-4-0-250828` | Seedream 4.0 | image | volcengine | 否 |
| `gemini-3.1-flash-image` | Gemini 3.1 Flash Image | image | gemini | 否 |
| `gemini-3-pro-image` | Gemini 3 Pro Image | image | gemini | 否 |
| `gemini-3.1-flash-lite-image` | Gemini 3.1 Flash Lite Image | image | gemini | 否 |
| `gemini-2.5-flash-image` | Gemini 2.5 Flash Image | image | gemini | 否 |
| `Nano Banana` | Nano Banana | image | gemini | 否 |
| `Nano Banana 2` | Nano Banana 2 | image | gemini | 否 |
| `Nano Banana Pro` | Nano Banana Pro | image | gemini | 否 |
| `Nano Banana 2 Lite` | Nano Banana 2 Lite | image | gemini | 否 |
| `gpt-image-2` | GPT Image 2 | image | openai | 否 |
| `gpt-image-2.5-sunburst` | GPT Image 2.5 Sunburst | image | openai | 否 |
| `gpt-image-2.5-flare` | GPT Image 2.5 Flare | image | openai | 否 |
| `doubao-seedance-2-0-260128` | Seedance 2.0 | video | volcengine | 是 |
| `doubao-seedance-2-0-fast-260128` | Seedance 2.0 Fast | video | volcengine | 是 |
| `doubao-seedance-2-0-mini-260615` | Seedance 2.0 Mini | video | volcengine | 是 |
| `doubao-seedance-2-5-260628` | Seedance 2.5 | video | volcengine | 是 |
| `kling-3.0` | 可灵 Kling 3.0 | video | kling | 否 |
| `kling-3.0-turbo` | 可灵 Kling 3.0 Turbo | video | kling | 否 |
| `kling-3.0-omni` | 可灵 Kling 3.0 Omni | video | kling | 否 |
| `MiniMax-H3` | MiniMax H3 | video | minimax | 否 |
| `hy-3d-3.0` | 混元 3D 专业版 3.0 | 3d | tencent | 否 |
| `hy-3d-3.1` | 混元 3D 专业版 3.1 | 3d | tencent | 否 |
| `hy-3d-express` | 混元 3D Express | 3d | tencent | 否 |
| `tripo-3d-3.1` | Tripo 3D 3.1 | 3d | tencent | 否 |
| `tripo-3d-p1` | Tripo 3D P1 | 3d | tencent | 否 |

模型 ID 区分大小写，例如 `MiniMax-H3` 不能写成 `minimax-h3`。Tripo 的 `provider` 也是 `tencent`，厂商选项写在 `provider_options.tencent` 下。

<a id="models-media-images"></a>

### 图片模型与输入方式

提交地址：`POST /media/v1/images/generations`。图片模型都在上游同步出图，提交时设置 `"wait": 50`，通常一次请求就能拿到结果。图片任务不支持取消。

| 展示名称 | 模型 ID | 输入方式 | 单次张数 `n` |
| --- | --- | --- | --- |
| Seedream 5 Lite | `doubao-seedream-5-0-lite-260128` | 文生图；图生图（最多 14 张参考图） | 1–15，默认 1 |
| Seedream 5.0 | `doubao-seedream-5-0-260128` | 文生图；图生图（最多 14 张参考图） | 1–15，默认 1 |
| Seedream 5 Pro | `doubao-seedream-5-0-pro-260628` | 文生图；图生图（最多 10 张参考图） | 只能为 1 |
| Seedream 4.5 | `doubao-seedream-4-5-251128` | 文生图；图生图（最多 14 张参考图） | 1–15，默认 1 |
| Seedream 4.0 | `doubao-seedream-4-0-250828` | 文生图；图生图（最多 14 张参考图） | 1–15，默认 1 |
| Gemini 3.1 Flash Image | `gemini-3.1-flash-image` | 文生图；图生图（最多 14 张参考图） | 只能为 1 |
| Gemini 3 Pro Image | `gemini-3-pro-image` | 文生图；图生图（最多 14 张参考图） | 只能为 1 |
| Gemini 3.1 Flash Lite Image | `gemini-3.1-flash-lite-image` | 文生图；图生图（最多 14 张参考图） | 只能为 1 |
| Gemini 2.5 Flash Image | `gemini-2.5-flash-image` | 文生图；图生图（最多 14 张参考图） | 只能为 1 |
| Nano Banana | `Nano Banana` | 文生图；图生图（最多 14 张参考图） | 只能为 1 |
| Nano Banana 2 | `Nano Banana 2` | 文生图；图生图（最多 14 张参考图） | 只能为 1 |
| Nano Banana Pro | `Nano Banana Pro` | 文生图；图生图（最多 14 张参考图） | 只能为 1 |
| Nano Banana 2 Lite | `Nano Banana 2 Lite` | 文生图；图生图（最多 14 张参考图） | 只能为 1 |
| GPT Image 2 | `gpt-image-2` | 文生图；编辑（最多 2 张参考图） | 只能为 1 |
| GPT Image 2.5 Sunburst | `gpt-image-2.5-sunburst` | 文生图；编辑（最多 2 张参考图） | 只能为 1 |
| GPT Image 2.5 Flare | `gpt-image-2.5-flare` | 文生图；编辑（最多 2 张参考图） | 只能为 1 |

清晰度、宽高比、像素尺寸、输出格式、水印、质量、背景、组图和参考图的取值与默认值只在[图片生成](media-images.md)维护：Seedream 见其 [Seedream 参数怎么填](media-images.md#media-images-h-b80d0153)，Nano Banana / Gemini 见 [Gemini 参数怎么填](media-images.md#media-images-h-184d7ee6)，GPT Image 见 [统一任务生成与编辑](media-images.md#media-images-h-eeced450)。GPT 直接 Images API 的独立请求与 Base64 响应见[GPT Image 生成与编辑](gpt-images.md)。

<a id="models-media-videos"></a>

### 视频模型与输入方式

提交地址：`POST /media/v1/videos/generations`。视频生成通常需要几十秒到数分钟，提交后按任务 ID 轮询。

| 展示名称 | 模型 ID | 输入方式 | 能否取消 |
| --- | --- | --- | --- |
| Seedance 2.0 | `doubao-seedance-2-0-260128` | 文生；首帧；首尾帧；多模态参考（图 9、视频 3、音频 3） | 支持 |
| Seedance 2.0 Fast | `doubao-seedance-2-0-fast-260128` | 同 Seedance 2.0 | 支持 |
| Seedance 2.0 Mini | `doubao-seedance-2-0-mini-260615` | 同 Seedance 2.0 | 支持 |
| Seedance 2.5 | `doubao-seedance-2-5-260628` | 文生；首帧；首尾帧；多模态参考（图 30、视频 10、音频 10）；480p 样片与基于样片的 1080p 正式视频 | 支持 |
| 可灵 Kling 3.0 | `kling-3.0` | 文生；首帧；首尾帧 | 不支持 |
| 可灵 Kling 3.0 Turbo | `kling-3.0-turbo` | 文生；首帧 | 不支持 |
| 可灵 Kling 3.0 Omni | `kling-3.0-omni` | 文生；首帧；首尾帧；参考图（最多 7 张）；参考视频（1 段） | 不支持 |
| MiniMax H3 | `MiniMax-H3` | 文生；首帧；首尾帧；多模态参考（图 9、视频 3、音频 3） | 不支持 |

清晰度、时长、宽高比、声音、厂商选项及参考素材组合规则只在[视频生成](media-videos.md)维护，按型号分别见 Seedance、可灵和 MiniMax H3 的参数表。分辨率大小写因型号而异，以该页为准。

<a id="models-media-3d"></a>

### 3D 模型与输入方式

提交地址：`POST /media/v1/3d/generations`。3D 生成通常需要数分钟，提交后按任务 ID 轮询；当前五款都不支持取消。产物一律是平台签发的限时下载链接。

| 展示名称 | 模型 ID | 输入方式 | 输出格式 |
| --- | --- | --- | --- |
| 混元 3D 专业版 3.0 | `hy-3d-3.0` | 文生；单图；多视图（主图 + 最多 7 个视角）；草图（Sketch 模式，图文同时提供） | 默认输出模型文件；`output_format` 可选 `stl`、`usdz`、`fbx` 之一，不保证在默认文件之外追加，见[默认输出与格式选择](media-3d.md#media-3d-h-978e5ef6) |
| 混元 3D 专业版 3.1 | `hy-3d-3.1` | 同 3.0 | 同 3.0 |
| 混元 3D Express | `hy-3d-express` | 文生；单图 | `output_format`：`obj`、`glb`、`stl`、`usdz`、`fbx`、`mp4` |
| Tripo 3D 3.1 | `tripo-3d-3.1` | 文生；单图；多视图（前、后、左、右）；文字可与图片同时提供 | 模型文件，格式不可选 |
| Tripo 3D P1 | `tripo-3d-p1` | 同 Tripo 3.1 | 模型文件，格式不可选 |

厂商选项（`provider_options.tencent`）、顶层 `output_format`、Tripo 的 `seed` 与 `negative_prompt` 的取值和组合限制只在[3D 生成](media-3d.md)维护，见其[混元 3D 参数怎么填](media-3d.md#media-3d-h-befb787d)和 [Tripo 参数怎么填](media-3d.md#media-3d-h-c62437ab)。

<a id="models-text"></a>

## 通用模型目录与文本模型

`GET /v1/models` 是平台的**通用模型目录**：返回这把密钥当前可用的**全部**模型，文本、图片、视频、3D 都在里面，不按类型区分，也没有分类参数。它回答“**这把密钥现在可以使用哪些模型 ID，文本模型通过什么协议调用？**”。

| 你要做的事 | 怎么用这个目录 |
| --- | --- |
| 调用文本模型 | 按[只列出文本模型](models.md#models-text-filter)筛出文本模型，再取 ID 和请求地址 |
| 用平台 API 生成图片、视频或 3D | 不用这个目录，改用上文[媒体模型](models.md#models-media)的 `GET /media/v1/models`；那里才有参数取值和平台提交地址 |
| 厂商原生兼容入口 | 用这个目录确认型号是否对密钥开放，请求格式见对应的厂商页面 |

返回的不是所有厂商模型或价格表；文本模型的上下文窗口等规格见[文本模型规格](llm-catalog.md)。

<a id="models-text-list"></a>

### 查询通用模型目录

| 项目 | 约定 |
| --- | --- |
| 方法 | `GET` |
| 路径 | `/v1/models` |
| 鉴权 | `Authorization: Bearer` 加完整虚拟密钥，见[地址与鉴权](access.md) |
| 请求参数 | 无；不提供分类筛选或分页参数 |
| 请求体 | 无 |
| 成功结果 | HTTP 200，`data` 为当前密钥可见的全部模型对象数组，含非文本模型 |

先按[地址与鉴权](access.md)设置 `GATEWAY_ORIGIN` 和 `KEY`。此命令只查询模型，不会发起生成。

```bash
curl -s "$GATEWAY_ORIGIN/v1/models" \
  -H "Authorization: Bearer $KEY"
```

装有 `jq` 时，可以只列出全部模型 ID：

```bash
curl -s "$GATEWAY_ORIGIN/v1/models" \
  -H "Authorization: Bearer $KEY" | jq -r '.data[].id'
```

<a id="models-text-filter"></a>

### 只列出文本模型

每个条目的 `native_endpoint_types` 可以区分模型类型：文本对话模型一定是数组（可能是 `[]`）；图片、视频、3D 以及向量、语音等其他模型固定为 `null`。按这一字段筛选，就只剩文本模型：

```bash
curl -s "$GATEWAY_ORIGIN/v1/models" \
  -H "Authorization: Bearer $KEY" \
  | jq -r '.data[] | select(.native_endpoint_types != null) | .id'
```

在程序中筛选时使用相同条件：保留 `native_endpoint_types` 不为 `null` 的条目。

不要按 `supported_endpoint_types` 是否包含 `openai`、`gemini` 来判断是不是文本模型：Seedream、Gemini 图片等模型的这个字段同样带有 `openai` 或 `gemini`，按它筛选会把图片模型混进来。

<a id="models-h-c090c358"></a>

### 通用目录返回示例

下面演示一个文本模型和一个 3D 模型同时出现在目录中的样子。`example-text` 是示意 ID，不代表已上架；`hy-3d-express` 的字段与平台返回一致。实际调用时使用你查询到的 `data[].id`。

```json
{
  "success": true,
  "object": "list",
  "data": [
    {
      "id": "example-text",
      "object": "model",
      "created": 1626777600,
      "owned_by": "platform",
      "supported_endpoint_types": ["openai", "openai-response", "anthropic", "gemini"],
      "native_endpoint_types": ["openai"],
      "public_endpoints": {
        "openai": {"method": "POST", "path": "/v1/chat/completions"},
        "openai-response": {"method": "POST", "path": "/v1/responses"},
        "anthropic": {"method": "POST", "path": "/v1/messages"},
        "gemini": {"method": "POST", "path": "/v1beta/models/{model}:generateContent"}
      }
    },
    {
      "id": "hy-3d-express",
      "object": "model",
      "created": 1626777600,
      "owned_by": "platform",
      "supported_endpoint_types": ["tencent-3d"],
      "native_endpoint_types": null,
      "public_endpoints": {
        "tencent-3d": {"method": "POST", "path": "/tencent/v1/api/3d/submit"}
      }
    }
  ]
}
```

第一项 `native_endpoint_types` 是数组，是文本模型；第二项为 `null`，是 3D 模型。3D 模型在这里给出的 `/tencent/...` 是厂商原生兼容入口；用平台 API 生成 3D 时，按 `GET /media/v1/models` 的结果和[3D 生成](media-3d.md)提交。

<a id="models-text-fields"></a>

### 通用目录返回字段

| 字段 | 类型 | 含义与用法 |
| --- | --- | --- |
| `success` | boolean | 正常列表响应为 `true`；仍需检查是否有错误正文 |
| `object` | string | 列表固定为 `list` |
| `data` | array | 当前可见的全部模型，含文本、图片、视频、3D 等；没有符合条件的模型时为 `[]` |
| `data[].id` | string | 调用所用的模型 ID，区分大小写；原样填入生成请求的 `model` 或模型路径参数 |
| `data[].object` | string | 模型对象固定为 `model` |
| `data[].created` | integer | 为协议兼容保留的时间戳；当前不能用来判断模型发布时间、上架时间或排序 |
| `data[].owned_by` | string | 模型归属标识；企业模式通常为 `platform`，不能用来推断实际渠道或鉴权方式 |
| `data[].supported_endpoint_types` | array 或 null | 模型可使用的端点类型。文本模型包含原生及可转换协议，见下表；其他模型是对应入口的类型，例如 `tencent-3d`、`ark-video`。不能用来判断是否为文本模型 |
| `data[].native_endpoint_types` | array 或 null | 文本模型为数组，表示当前可达渠道共同原生支持的协议，可能为 `[]`；图片、视频、3D 等非文本模型固定为 `null`。用它区分文本模型 |
| `data[].public_endpoints` | object，可省略 | 端点类型到公开请求地址的映射；每项只有 `method` 和 `path` |

`public_endpoints` 中的路径**相对于网关根地址**，已经包含所需版本与厂商前缀，不要再添加一次。路径含 `{model}` 时，替换为当前模型 ID，并对路径参数进行 URL 编码。参数和响应仍需阅读该接口文档；仅有地址不代表可以用相同请求体调用所有协议。

文本模型的端点类型对应如下：

| 端点类型 | 你要使用的 API | 请求与响应说明 |
| --- | --- | --- |
| `openai` | Chat Completions，以 `messages` 提交对话 | [文本模型调用](llm-api.md) |
| `openai-response` | Responses，以 `input` 提交输入 | [文本模型调用](llm-api.md) |
| `anthropic` | Messages，使用 Anthropic 请求形状 | [文本模型调用](llm-api.md) |
| `gemini` | GenerateContent，以 `contents` 提交输入 | [文本模型调用](llm-api.md) |

`supported_endpoint_types` 表示可服务协议的并集；`native_endpoint_types` 表示当前可达渠道原生能力的交集。某协议只出现在前者时，平台可能进行协议转换，不能承诺每条可达渠道都原生支持。关键功能无法保留时，请求仍会被拒绝。目录中的图片、视频和 3D 模型，请以上文[媒体模型](models.md#models-media)的查询结果确认参数和提交地址，不要从这里的端点类型推测平台媒体路径。

<a id="models-h-8980ae8b"></a>

### 查询单个模型

已取得模型 ID 时，可用同一密钥读取单个对象：

```bash
MODEL_ID="替换为列表返回的模型ID"

curl -s "$GATEWAY_ORIGIN/v1/models/$MODEL_ID" \
  -H "Authorization: Bearer $KEY"
```

模型 ID 含特殊字符时，先进行 URL 路径编码。成功时 HTTP 200，正文直接是上例 `data[0]` 的模型对象，**没有 `data` 包装，也没有列表级 `success`**；读取 `response.id`，不要读取 `response.data.id`。

单模型查询使用相同的权限过滤。模型不存在或对当前密钥不可见时，当前 Bearer 接口的兼容行为是 **HTTP 200 加错误正文**：

```json
{
  "error": {
    "message": "The model 'example-missing' does not exist",
    "type": "invalid_request_error",
    "param": "model",
    "code": "model_not_found"
  }
}
```

<a id="models-h-5487052b"></a>

### 文本模型名称对应

平台接口使用**目录返回的模型 ID**，不要求调用方换算厂商名称。展示名称、系列简称和请求中的 `model` 是不同用途；不能只凭系列名称猜测可调用 ID。

| 你看到或使用的位置 | 应如何对应 |
| --- | --- |
| 模型列表 `data[].id` | 当前可调用的模型 ID；复制完整值，保留大小写、连字符及版本后缀 |
| 文本生成请求 `model` | 填入所选条目的 `id`，例如目录返回 `example-text` 时就填写同值 |
| 模型查询或生成路径中的 `{model}` | 使用该条目的 `id`，按 URL 路径参数编码 |
| 模型展示名或系列名 | 仅帮助阅读，不作为请求参数；对应型号仍以目录为准 |
| 平台配置的调用别名 | 以目录实际返回值确认支持范围，不从展示名或缩写自动推导；不同 ID 不自行合并或替换 |

若目录实际返回另一个平台配置名称，使用实际返回的 `id`。上游型号转换由平台处理，调用方无需知道或手动填写渠道内部映射。图片、视频和 3D 模型的展示名称与模型 ID 对照见上文[媒体模型名称映射](models.md#models-media-names)。

<a id="models-h-de32e3d5"></a>

### 通用目录空列表与报错

目录综合当前渠道可用性、模型上架与有效价格、企业和部门及主体授权、虚拟密钥的模型限制。授权或渠道状态变化后，结果也可能变化。

若响应为 `{"success":true,"object":"list","data":[]}`，表示当前密钥没有符合条件的可见模型。请管理员核对模型授权、上架、有效价格与渠道状态；这不表示厂商没有模型。列表也不检查下一次生成的实际成本是否在预算内，返回模型不等于生成必定成功。

`data` 不为空、但[只列出文本模型](models.md#models-text-filter)的筛选结果为空时，表示这把密钥只开放了图片、视频或 3D 等模型；需要文本模型时请管理员开通。

客户端同时检查 HTTP 状态、顶层 `error` 以及 `success: false`，不要仅以 HTTP 200 判断成功。目录失败不应通过提交生成请求来“试一下”。

| 结果 | 常见原因 | 处理方式 |
| --- | --- | --- |
| HTTP 401 | 密钥缺失、错误、禁用、过期，或有限密钥额度已用完 | 核对完整 Bearer 值、密钥状态及额度 |
| HTTP 403 | IP 限制、组织或身份状态不允许；平台管理身份不是消费主体 | 阅读错误正文，请管理员核对身份和限制 |
| HTTP 200，`error.code: model_not_found` | 单模型不存在或不可见 | 重新查询列表，使用原样返回的模型 ID |
| HTTP 200，`success: false` | 平台未能读取分组等目录依赖 | 保留错误信息与请求标识，交由平台排查 |
| HTTP 5xx | 平台读取或服务异常 | 退避重试这个只读查询；持续失败时提供请求标识 |

例如无效密钥可返回 HTTP 401，错误形状如下；具体消息可能附带请求标识，不应依赖中文消息进行分支判断：

```json
{
  "error": {
    "message": "无效的令牌",
    "type": "new_api_error",
    "code": ""
  }
}
```

排查时保存响应头 `X-Oneapi-Request-Id`、HTTP 状态和错误正文，不记录或发送密钥。

<a id="models-h-acfc4e74"></a>

## 下一步

1. 生成图片、视频或 3D：按模型的 `type` 阅读[图片生成](media-images.md)、[视频生成](media-videos.md)或[3D 生成](media-3d.md)，复制对应的完整请求；提交后按[任务查询与结算](media-tasks.md)读取结果、下载产物、核对费用。
2. 调用文本模型：按[只列出文本模型](models.md#models-text-filter)选出模型 ID，按其 `public_endpoints` 确认接口地址，再按[文本模型调用](llm-api.md)准备对应协议的请求体；厂商原生请求按[原生地址与 SDK](official.md)进入对应模型页。

模型查询只读取元数据，不产生费用；后续生成请求会消耗额度。价格以企业配置为准，本页不列出报价；媒体任务的实际扣费见任务响应中的 `billing`。