# 使用 API

cs2.sh 所有端点共享的内容：认证、饰品命名与变体、响应封装、部分成功、OHLC 分桶，以及共享的错误和限制模型。

本页介绍 cs2.sh API 各端点共享的约定，包括认证、请求类型、响应对象、变体、时间戳、缺失数据、部分成功、错误和限制。

- 想在指引下发起第一个请求，请从[快速开始](/zh-cn/docs/quickstart)开始。
- 关于市场字段、刷新频率和历史覆盖范围，见[数据覆盖范围](/zh-cn/docs/data-coverage)。
- 各端点页面记录了各自精确的参数和响应字段。

## 认证

公开 API 基础 URL 为 `https://api.cs2.sh`。

所有 `/v1` 端点都需要 Bearer API 密钥。每个 `/v1` 请求还必须接受 gzip 压缩，POST 请求还应包含 `Content-Type: application/json`：

| 请求头 | 值 | 适用于 |
| --- | --- | --- |
| `Authorization` | `Bearer YOUR_API_KEY` | 所有 `/v1` 端点 |
| `Accept-Encoding` | `gzip` | 所有 `/v1` 端点 |
| `Content-Type` | `application/json` | POST 端点 |

成功的 `/v1` 响应是 gzip 编码的。大多数 HTTP 客户端会自动解压。错误响应以纯 JSON 返回。

在仪表盘中轮换 API 密钥会生成一个新密钥，并立即使旧密钥失效。

## GET 与 POST 请求

cs2.sh 使用两种主要的请求模式：

- GET 快照：获取某个端点完整的当前数据集。
- POST 查询：请求最多 100 件指定饰品的数据，并附带日期、来源或间隔等端点特定参数。

例如，下面的请求获取完整的当前价格快照：

```http
GET /v1/prices/latest
```

下面的请求获取两件指定饰品的当前价格：

```http
POST /v1/prices/latest
Content-Type: application/json

{
  "items": [
    "USP-S | Printstream (Factory New)",
    "AK-47 | Redline (Field-Tested)"
  ]
}
```

GET 快照可能很大，但很有用，因为你可以保存一次响应，之后在本地进行查询。当你需要针对一组已知饰品获得有界响应时，POST 请求更合适。历史端点也使用 POST 请求来限制响应大小。

## 饰品

POST 端点使用 `market_hash_name` 标识饰品：

```json
{
  "items": [
    "USP-S | Printstream (Factory New)"
  ]
}
```

[GET /v1/schema](/zh-cn/docs/schema) 按所有端点所接受的同一 `market_hash_name` 返回每一件受支持的饰品。它还包含饰品元数据、市场 id、图片、外观、磨损区间和变体。

POST 端点在一次请求中最多接受 100 件饰品。

## 响应

大多数饰品端点返回一个以 `market_hash_name` 为键的 `items` 对象。

```json
{
  "response_time": "2026-07-26T18:54:04.041Z",
  "currency": "USD",
  "items": {
    "USP-S | Printstream (Factory New)": {
      "market_hash_name": "USP-S | Printstream (Factory New)",
      "buff": {
        "updated_at": "2026-07-26T18:50:53Z",
        "collected_at": "2026-07-26T18:53:10.67Z",
        "ask": 109.72,
        "ask_volume": 463,
        "bid": 106.17,
        "bid_volume": 41
      }
    }
  }
}
```

常见的顶层字段包括：

| 字段 | 含义 |
| --- | --- |
| `response_time` | API 生成响应的时间。 |
| `currency` | 响应货币，价格数据当前仅为 `USD`。 |
| `items` | 饰品名称到返回数据的映射。 |
| `errors` | POST 端点中与成功饰品一起返回的逐饰品失败。 |

当前价格饰品对每个市场包含一个对象。历史端点使用相同的 `items` 映射，时间序列数据嵌套在每件饰品之内。

完整的响应 schema 见 [API 对象](/zh-cn/docs/objects)。

## 变体

带有受支持的 Doppler、Gamma Doppler 或 Case Hardened 变体的饰品可以包含 `variants` 对象。

```json
{
  "market_hash_name": "★ Karambit | Doppler (Factory New)",
  "buff": {
    "ask": 1336.26,
    "bid": 1281.77
  },
  "variants": {
    "Ruby": {
      "market_hash_name": "★ Karambit | Doppler (Factory New)",
      "name": "★ Karambit | Doppler (Factory New) | Ruby",
      "display_name": "Ruby",
      "version": "ruby",
      "buff": {
        "ask": 7671.41,
        "bid": 7287.47
      },
      "csfloat": {
        "ask": 7590,
        "bid": 7220
      }
    }
  }
}
```

在变体对象上：

| 字段 | 含义 |
| --- | --- |
| `market_hash_name` | 基础饰品的 market hash name。 |
| `name` | 完整的 cs2.sh 变体名称。 |
| `display_name` | 面向人类的变体标签。 |
| `version` | 稳定的变体代码。 |

### 版本代码

变体饰品支持的 `version` 代码：

| version 代码 | 变体系列 | 显示标签 |
| --- | --- | --- |
| `p1` | Doppler / Gamma Doppler | Phase 1 |
| `p2` | Doppler / Gamma Doppler | Phase 2 |
| `p3` | Doppler / Gamma Doppler | Phase 3 |
| `p4` | Doppler / Gamma Doppler | Phase 4 |
| `ruby` | Doppler | Ruby |
| `sapphire` | Doppler | Sapphire |
| `blackpearl` | Doppler | Black Pearl |
| `emerald` | Gamma Doppler | Emerald |
| `t1` | Case Hardened | Tier 1 |
| `t2` | Case Hardened | Tier 2 |
| `t3` | Case Hardened | Tier 3 |
| `t4` | Case Hardened | Tier 4 |
| `singleblue` | Case Hardened | Blue Gem |

变体的可用性取决于市场和端点。变体支持情况见[数据覆盖范围](/zh-cn/docs/data-coverage)，每件饰品所附带的变体见 [GET /v1/schema](/zh-cn/docs/schema)。

## 时间戳

当前市场价格对象可以包含三个不同的时间戳：

| 字段 | 含义 |
| --- | --- |
| `response_time` | cs2.sh 生成完整 API 响应的时间。 |
| `updated_at` | 市场最后一次更新价格的时间。 |
| `collected_at` | cs2.sh 采集它的时间。 |

`response_time` 并不表示某个市场价格的采集时间。检查新鲜度时，请使用该市场对象内部的时间戳。

刷新频率是近似值，并因市场而异。各端点和来源的预期刷新频率见[数据覆盖范围](/zh-cn/docs/data-coverage)。

## 历史响应分桶

`prices/history` 和 `market/buff/history` 返回固定的、UTC 对齐的 OHLC 分桶。分桶内的每个市场对象都包含以下观测字段：

| 字段 | 含义 |
| --- | --- |
| `bucket` | UTC 对齐区间的开始时间。 |
| `open_time` | 分桶内第一次观测的时间。 |
| `close_time` | 分桶内最后一次观测的时间。 |
| `sample_count` | 该分桶所代表的底层观测数量。 |

`ask_volume` 和 `bid_volume` 是分桶内最后观测到的值。

并非每个历史端点都返回 OHLC。`market/steam/history` 返回采样的 Steam 订单簿历史，归档端点则返回各自端点页面所记录的数据。关于 OHLC、采样和归档历史之间的区别，见[数据覆盖范围](/zh-cn/docs/data-coverage)。

## 缺失数据

缺失的价格不等于价格为零。

在当前价格的基础饰品上，市场对象可能存在，但不可用字段被设为 `null`：

```json
{
  "skinport": {
    "updated_at": null,
    "collected_at": null,
    "ask": null,
    "ask_volume": null
  }
}
```

变体和历史响应对象可能是稀疏的。当某个市场对该变体或区间没有数据时，该市场对象可能不存在。

某些历史端点在所请求范围内不存在数据时，会省略有效的饰品。相关端点页面记录了其精确的空数据行为。

## 部分成功

POST 端点会独立校验请求的饰品。一次请求可以在同一个 `200` 响应中返回成功的饰品和逐饰品错误。

```json
{
  "items": {
    "USP-S | Printstream (Factory New)": {
      "market_hash_name": "USP-S | Printstream (Factory New)"
    }
  },
  "errors": [
    {
      "item": "Invalid Item Name",
      "code": "unknown_item",
      "message": "item not found"
    }
  ]
}
```

`errors` 中的条目仅适用于所请求的那件饰品。它不会使成功返回的饰品失效。

### 饰品错误码

| 代码 | 含义 |
| --- | --- |
| `unknown_item` | 请求的名称与任何已知饰品都不匹配。 |
| `invalid_format` | 提交的饰品值无效。 |
| `not_in_cache` | 饰品有效，但在相关的当前数据集中不可用。 |
| `not_in_archive` | 饰品有效，但在所请求的归档数据集中没有行。 |
| `unsupported_source` | 该饰品在所请求的市场上没有对应标识。 |
| `unsupported_variant` | 该数据集不支持所请求的变体。 |

相关端点页面记录了它可能返回哪些饰品错误码。完整对象见 [ItemError](/zh-cn/docs/objects#itemerror)。

饰品错误与请求级错误不同。

## 请求错误

请求级错误使用共享的 JSON 对象：

```json
{
  "error": "validation_error",
  "message": "items must contain at most 100 entries",
  "request_id": "550e8400-e29b-41d4-a716-446655440000"
}
```

部分错误还包含 `details` 对象。

`request_id` 标识失败的请求，联系支持时应一并提供。

| 状态码 | 含义 |
| --- | --- |
| `400` | 请求参数缺失或无效、JSON 格式错误，或请求过大。 |
| `401` | API 密钥缺失、格式错误或无效。 |
| `403` | 请求的端点不包含在你的套餐中。 |
| `404` | 未知路径，或所请求的饰品在相关数据集中均无数据。 |
| `405` | 该端点不支持所请求的 HTTP 方法。 |
| `429` | 超出每秒请求限制。 |
| `500` | 内部服务器错误。 |
| `503` | 服务、数据库或所请求的快照暂时不可用。 |
| `504` | 请求或数据库查询超时。 |

请先修正 `400`、`401`、`403`、`404` 和 `405` 错误再重试。对 `429` 和临时性的 `5xx` 错误，请以有界延迟重试。

各端点页面记录了该端点特有的其他错误行为。

## 限制

| 限制 | 值 |
| --- | --- |
| 请求 | 每个用户每秒 10 个请求 |
| 每个 POST 请求的饰品数 | 100 |
| 请求体 | 1 MiB |
| 响应压缩 | `/v1` 必须使用 gzip |

历史端点还有按间隔划分的最大请求范围。这些记录在[数据覆盖范围](/zh-cn/docs/data-coverage)和相关端点页面中。

完整的 GET 快照可能很大。当你需要反复访问同一个当前数据集时，请缓存它们，并对更小的、针对指定饰品的请求使用 POST 端点。

## OpenAPI

完整的 OpenAPI 3.1 规范可在 [cs2.sh/openapi.zh-CN.yaml](https://cs2.sh/openapi.zh-CN.yaml) 获取。

它包含端点参考所使用的请求参数、响应 schema、枚举和示例。