API Reference · v1

接口文档

REST 风格，JSON 输入输出，请求头携带密钥。所有响应带 ETag 与 Cache-Control。

[01]

鉴权

开放接口通过请求头 X-API-Key 鉴权。一个账号一把密钥，注册后在控制台查看。密钥等同密码，不要提交进代码仓库或放在前端。

请求头

X-API-Key: pk_你的密钥

[02]

端点

https://priceapi.ai

GET /api/v1/prices 需要密钥

返回全量价格数据。响应可缓存一小时，带 ETag。

字段	类型	说明
updated_at	string	数据更新时间，ISO 8601
currency	string	计价货币
unit	string	计价单位
items	array	价格条目列表
items[].id	string	唯一标识
items[].name	string	名称
items[].vendor	string	厂商
items[].input	number	输入价格
items[].output	number	输出价格

示例

$ curl https://priceapi.ai/api/v1/prices \
    -H "X-API-Key: pk_你的密钥"

GET /api/health 公开

服务健康检查。用于监控探活，不计入配额。

响应 · 200

{ "status": "ok" }

[03]

缓存与轮询

省流量的正确姿势

响应带 ETag。把上次拿到的值放进 If-None-Match 再请求，数据没变时服务端返回 304 且响应体为空——轮询几乎不产生流量。

条件请求

$ curl -i https://priceapi.ai/api/v1/prices \
    -H "X-API-Key: pk_你的密钥" \
    -H 'If-None-Match: "52902e927d3bda2e80554bd9c2e5269a"'

HTTP/2 304
cache-control: public, max-age=3600
etag: "52902e927d3bda2e80554bd9c2e5269a"

[04]

状态码

状态码	含义	处理建议
200	成功	正常解析响应体
304	数据未变更	沿用本地缓存，响应体为空
401	密钥无效或缺失	检查 X-API-Key 请求头
429	超出频率限制	按 Retry-After 退避重试
5xx	服务端异常	指数退避重试

交互式接口浏览器：/api/docs · OpenAPI 描述：/api/openapi.json