BUILT FOR DEVELOPERS

让设备查询，融入你的应用。

一个接口，获取设备类型、型号与可用序列号。

REST API / v1

快速开始

通过 HTTPS 发送设备 UDID，接口以 JSON 返回本次可获取的设备信息。以下示例中的 YOUR_API_KEY 和 YOUR_DEVICE_UDID 需要替换为你的实际值。

POST/v1/devices/lookup

Terminal

curl --request POST 'https://chax.axkj.xyz/v1/devices/lookup' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{"udid":"YOUR_DEVICE_UDID","provider":"auto"}'

示例用于服务端调用。JavaScript 示例适用于支持 fetch 的 Node.js 环境，请勿将 API Key 放入公开网页代码。

身份验证

每次调用都需要在请求头中携带 API Key。密钥由服务运营方提供。

HTTP Header

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

密钥只保存在服务端。建议通过环境变量注入密钥，不要写入前端代码、公开仓库或请求 URL。

请求参数

请求体为 JSON 对象，包含以下字段。

字段	类型	必填	说明
udid	string	是	设备 UDID。支持 8 位十六进制字符 + 连字符 + 16 位十六进制字符，或 40 位十六进制字符。
provider	string	否	`auto`（默认）自动综合查询；`apple` 仅 Apple；`udids` 仅 UDIDS.CN；`hiuc` 仅云趣。

UDID 不是序列号、IMEI 或设备名称。请保留新格式中的连字符。建议提交前移除首尾空格。

自动查询优先保留 Apple 信息，再用设备类别一致的 UDIDS.CN、云趣结果补充空字段。来源故障时仍返回其他可用结果。GET /api/providers 可查看已启用的来源。网页公共接口 POST /api/public/lookup 使用同样的请求和响应格式，无需密钥。

返回结果

成功请求返回 HTTP 200，包含 data 和 meta。以下为结构示例，字段值为说明性占位值，并非真实查询记录。

200 OK · application/json

{
  "data": {
    "udid": "YOUR_DEVICE_UDID",
    "deviceClass": "ipad",
    "devicePlatform": "ios",
    "model": "DEVICE_MODEL",
    "serialNumber": null
  },
  "meta": {
    "source": "apple_developer_portal",
    "resultStatus": "complete",
    "partialReason": null,
    "fieldSources": {
      "deviceClass": "apple_developer_portal",
      "devicePlatform": "apple_developer_portal",
      "model": "apple_developer_portal"
    },
    "sources": ["apple_developer_portal"],
    "providerErrors": {},
    "conflictingSources": [],
    "queriedAt": "2026-01-01T00:00:00Z",
    "cached": false,
    "serialNumberStatus": "not_returned",
    "classificationStatus": "identified"
  }
}

设备信息 · data

字段	类型	说明
udid	string	本次查询的设备唯一标识。
deviceClass	string	设备分类：`iphone`、`ipad`、`ipod`、`mac`、`watch`、`tv`、`vision`。无法识别时为 `unknown`。
devicePlatform	string / null	设备平台，以实际返回值为准。
model	string / null	上游型号原文，也可能是“iPhone 17 系列”等系列名称，并非精确子型号。未返回时为 `null`。
serialNumber	string / null	可用的序列号，未返回时为 `null`。

查询信息 · meta

字段	类型	说明
source	string	`apple_developer_portal` 为 Apple 记录，`apple_validation_message` 为 Apple 分类提示；`udids`、`hiuc` 为对应第三方；`combined` 表示采用多个来源的字段。
resultStatus	string	`complete` 表示得到设备记录或型号等详情，字段仍可为空；`partial` 表示当前信息有限。两者均不是设备真实性证明。
partialReason	string / null	`registration_limit_reached` 表示 Apple 注册名额限制了详情；`limited_upstream_data` 表示来源仅给出有限信息。详情补全后为 `null`。
fieldSources	object	每个非空设备字段的来源，键为 deviceClass、devicePlatform、model 或 serialNumber。
sources	array	本次成功返回信息的来源列表；不表示这些来源的所有字段均被采用。
providerErrors	object	失败来源及其安全错误代码。自动模式下部分来源失败仍可返回 HTTP 200。
conflictingSources	array	与优先来源设备类别或序列号存在冲突的来源；冲突信息不用于补全。
queriedAt	string	查询时间，ISO 8601 格式。
cached	boolean	是否从缓存返回本次结果。
serialNumberStatus	string	序列号存在时为 `available`，未返回时为 `not_returned`。
classificationStatus	string	已识别时为 `identified`，未识别时为 `unknown`。

成功响应不保证所有字段都有值。缺失序列号和未识别类型都是正常的结果状态。不要将 null、空值或 unknown 转换为 iPhone / iPad 等确定分类。

错误处理

非成功响应使用相应的 HTTP 状态码，并在 JSON 中提供错误代码。根据 error.code 处理业务逻辑，不要依赖提示文案。

Error response

{
  "error": {
    "code": "rate_limited",
    "message": "Too many requests",
    "requestId": "REQUEST_ID"
  }
}

错误代码	处理建议
all_providers_failed	所有来源均未提供可用结果；error.providerErrors 列出各来源错误代码。
provider_disabled	所选来源未启用，改用 auto 或其他可用来源。
udids_* hiuc_*	对应来源超时、暂不可用或结果未通过校验，可尝试自动查询。第三方自身限制仍可能影响结果。
unauthorized	检查 Bearer API Key 是否正确、完整。
rate_limited upstream_rate_limited upstream_budget_exhausted	减少请求频率。若响应提供 `Retry-After` 请求头，按指定时间等待后再试。
invalid_request	请求参数不合法（HTTP 422），请核对 UDID 格式及 JSON 请求体。
service_busy	当前查询队列已满，按 Retry-After 提示稍后重试。
unsupported_media_type	请使用 Content-Type: application/json。
device_not_found	核对 UDID。暂未查到不等同于设备不存在。
service_not_configured account_not_configured account_configuration_invalid session_expired	服务暂不可用，由服务运营方恢复后再试。
upstream_timeout lookup_timeout	查询超时，稍后重试。建议使用有限次数的指数退避。
upstream_connection_error upstream_http_error upstream_rejected	查询连接失败或被拒绝，稍后重试。
upstream_invalid_response upstream_device_mismatch	设备结果未通过校验，不要使用该响应生成设备信息。

HTTP 422 表示参数校验失败，使用相同错误结构，错误代码为 invalid_request。对于未列出的状态码或错误代码，请保留响应状态与 requestId，按通用失败处理。

接入建议

本站当前不设置每分钟或每日查询次数配额，网页查询与开放 API 均适用。

为请求设置合理超时，并对网络错误和限流做有限次数重试。
只在用户需要时查询，避免高频重复请求同一设备。
按真实返回值显示信息，兼容新增设备分类和空字段。
日志中避免记录完整 API Key、UDID 与序列号。