# 查询模型价格

> 全部文档的索引见 [llms.txt](https://ark.volcengine.com/llms.txt)；在任一文档页面地址后追加 `.md` 可获取该页的 Markdown 版本。

`POST https://ark.cn-beijing.volcengineapi.com/?Action=ListModelPrices&Version=2024-01-01`

查询当前账号可见基础模型的价格信息，可按服务类型、窗口、区域、时段、分辨率和输出尺寸筛选价格分组。

## 鉴权

本接口支持鉴权方式如下，详情请参见 [Base URL 及鉴权](/docs/base-url-and-authentication)。

* Access Key 鉴权，请在 [Access Key 管理](https://console.volcengine.com/iam/keymanage) 页面，获取 Access Key。本接口仅支持 Access Key 鉴权。

---

<span id="request-parameters"></span>
## 请求参数

### Body 参数

**FoundationModelNames** `string[]` `必选` | 基础模型列表

待查询价格的基础模型名称列表。重复名称仅查询一次，并按去重后的请求顺序返回结果。

> **注意**
>
> 传入空列表时返回空的 `ModelPrices`。

**Dimensions** `object[]` | 价格维度筛选

按服务类型、窗口、区域、时段、分辨率和输出尺寸筛选价格分组。未指定 `service_type` 时，返回空的模型价格列表。

> **说明**
>
> 同一维度的多个取值按“或”匹配，不同维度按“且”匹配。未匹配到价格时返回空结果。

**Name** `string` `必选` | 维度名称

`Dimensions.Name`

价格筛选维度名称。可选值：`service_type`（服务类型）、`window`（窗口）、`region`（区域）、`time_period_type`（时段类型）、`resolution`（分辨率）、`output_size_level`（输出尺寸级别）。

**Values** `string[]` `必选` | 维度取值

`Dimensions.Values`

与 `Dimensions.Name` 对应的筛选值，具体对应关系见下表。

| 维度名称 | 取值 | 查询规则 |
| --- | --- | --- |
| `service_type` | * `infer`：通用推理。 \ | 必须指定。仅返回指定服务类型对应的价格分组。 \
|  | * `infer-storage`：存储计费。 \ |  \
|  | * `fast-infer`：在线推理（低延迟）。 \ |  \
|  | * `flex-infer`：在线推理（低优）。 \ |  \
|  | * `batch-infer`：批量推理。 \ |  \
|  | * `finetuned-infer`：精调后模型推理。 \ |  \
|  | * `finetuned`：模型精调。 |  |
| `window` | 模型实际返回的完整窗口档位字符串，包括以下形式： \ 
|  | * 仅输入上限：`输入<=32k`。 \
|  | * 输入区间：`32k<输入<=128K`。 \
|  | * 输入和输出联合条件：`输入<=32k，输出<=200`。 \
|  | 字符串中的中文逗号、大小写以及 `≤`、`<=` 等符号均按实际返回值保留。 | 请求时传入与响应中 `window.Value` 完全一致的档位字符串，不得转换或改写取值格式。`Values` 支持传入一个或多个完整档位值，多个取值按“或”匹配。未指定 `window` 时，返回符合其他筛选条件的全部窗口档位；指定 `window` 时，仅返回与传入值匹配的窗口档位。 |
| `region` | * `regional`：区域档位。 \ | 未指定时仅返回默认全局档位；指定区域值时仅返回对应区域档位；同时指定 `""` 和区域值时，返回默认全局档位及指定区域档位。 \
|  | * `""`：默认全局档位。 |  |
| `time_period_type` | * `offpeak`：闲时档。 \ | 未指定时返回常规/忙时档；指定 `offpeak` 时仅返回闲时档；同时指定 `""` 和 `offpeak` 时，返回常规/忙时档及闲时档。 \
|  | * `""`：常规/忙时档。 |  |
| `resolution` | * `1080p`：1080p 分辨率档位。 \ | 未指定时返回默认分辨率档位；指定分辨率值时仅返回对应档位；同时指定 `""` 和分辨率值时，返回默认分辨率档位及指定分辨率档位。 \
|  | * `4k`：4K 分辨率档位。 \ |  \
|  | * `""`：默认分辨率档位。 |  |
| `output_size_level` | * `large`：大尺寸档位。 \ | 未指定时返回默认尺寸档位；指定尺寸值时仅返回对应档位；同时指定 `""` 和尺寸值时，返回默认尺寸档位及指定尺寸档位。 \
|  | * `""`：默认尺寸档位。 |  |

## 响应参数

**ModelPrices** `object[]` | 模型价格列表

当前账号可见模型的价格列表。

> **说明**
>
> 无匹配结果、模型不可见或请求的模型列表为空时返回空数组。

**FoundationModelName** `string` | 基础模型名称

`ModelPrices.FoundationModelName`

**PriceGroups** `object[]` | 价格分组

`ModelPrices.PriceGroups`

基础模型在不同计费条件下对应的价格分组。

**Dimensions** `object[]` | 价格维度

`ModelPrices.PriceGroups.Dimensions`

价格分组中显式配置的维度组合。默认档位对应的维度不包含在此数组中。

**Name** `string` | 维度名称

`ModelPrices.PriceGroups.Dimensions.Name`

价格分组中显式配置的维度名称。可选值：`service_type`、`window`、`region`、`time_period_type`、`resolution`、`output_size_level`。

**Value** `string` | 维度取值

`ModelPrices.PriceGroups.Dimensions.Value`

价格分组中该维度的实际取值。

**PriceItems** `object[]` | 计费项价格

`ModelPrices.PriceGroups.PriceItems`

价格分组中的计费项价格信息。

**Label** `string` | 计费项名称

`ModelPrices.PriceGroups.PriceItems.Label`

计费项名称。仅返回当前模型适用的计费项。

以下为常见计费项，非完整枚举，具体以模型实际返回的计费项为准。

* `Prompt`：输入 Token。
* `Completion`：输出 Token。
* `CacheHit`：缓存命中 Token。
* `Storage`：缓存存储。
* `ToICompletion`：图像生成输出。
* `T2VCompletion`：视频生成输出。

**PriceUnitCode** `string` | 价格单位编码

`ModelPrices.PriceGroups.PriceItems.PriceUnitCode`

价格计量单位的编码。

**DiscountPriceEndTime** `string` | 促销结束时间

`ModelPrices.PriceGroups.PriceItems.DiscountPriceEndTime`

促销价格的失效时间，格式为 RFC3339。

**DiscountPriceStartTime** `string` | 促销开始时间

`ModelPrices.PriceGroups.PriceItems.DiscountPriceStartTime`

促销价格的生效时间，格式为 RFC3339。

**OriginalPrice** `number` | 原价

`ModelPrices.PriceGroups.PriceItems.OriginalPrice`

折扣前价格。

> **说明**
>
> 缺少该字段表示未提供原始价格，不得按 `0` 处理。

**Price** `number` | 当前价格

`ModelPrices.PriceGroups.PriceItems.Price`

当前账号对应的价格。

> **说明**
>
> 缺少该字段不表示免费，缺失时不得按 `0` 处理。

**UsageUnit** `string` | 用量单位

`ModelPrices.PriceGroups.UsageUnit`

价格分组使用的用量单位。

**DimensionAttributes** `object[]` | 匹配的维度附属信息

`ModelPrices.DimensionAttributes`

与当前模型价格匹配的维度附属信息。

**Name** `string` | 维度名称

`ModelPrices.DimensionAttributes.Name`

维度附属信息的名称。可选值：`service_type`、`window`、`region`、`time_period_type`、`resolution`、`output_size_level`。

**Value** `string` | 维度取值

`ModelPrices.DimensionAttributes.Value`

维度附属信息的取值。

**Ranges** `string[]` | 维度范围

`ModelPrices.DimensionAttributes.Ranges`

与维度取值关联的范围信息。闲时时段的取值可能为包含星期、起始时间、结束时间和时区等信息的 JSON 字符串，具体内容以实际返回值为准。


## 代码示例

## 默认

### cURL

#### Request

```bash
curl 'https://ark.cn-beijing.volcengineapi.com/?Action=ListModelPrices&Version=2024-01-01' \
  -H 'Content-Type: application/json' \
  -H 'X-Date: <X-Date>' \
  -H 'X-Content-Sha256: <X-Content-Sha256>' \
  -H 'Authorization: HMAC-SHA256 Credential=<AK>/<X-Date>/cn-beijing/ark/request, SignedHeaders=content-type;host;x-content-sha256;x-date, Signature=<Signature>' \
  -d '{
    "FoundationModelNames": [
        "doubao-seed-2-0-pro"
    ],
    "Dimensions": [
        {
            "Name": "service_type",
            "Values": [
                "infer"
            ]
        }
    ]
}
'
```

#### Response

```
{
    "ResponseMetadata": {
        "RequestId": "20261028123456E5F607182E04DEF708",
        "Action": "ListModelPrices",
        "Version": "2024-01-01",
        "Service": "ark",
        "Region": "cn-beijing"
    },
    "Result": {
        "ModelPrices": [
            {
                "FoundationModelName": "doubao-seed-2-0-pro",
                "PriceGroups": [
                    {
                        "UsageUnit": "token",
                        "Dimensions": [
                            {
                                "Name": "service_type",
                                "Value": "infer"
                            }
                        ],
                        "PriceItems": [
                            {
                                "Label": "Prompt",
                                "Price": 0.0008,
                                "PriceUnitCode": "CNY_PER_MILLION_TOKEN"
                            },
                            {
                                "Label": "Completion",
                                "Price": 0.002,
                                "PriceUnitCode": "CNY_PER_MILLION_TOKEN"
                            }
                        ]
                    }
                ]
            }
        ]
    }
}
```
