参数名	类型	必填	说明	示例
key	string	是	接口调用密钥
action	string	是	操作方法	realtime
metal	string	是	类型	gold

金价实时查询

接口说明

该接口支持获取黄金、白银及铂金的实时动态价格数据。适用于金融从业者、投资者及开发者查询即时贵金属市场行情。

调用地址

https://api.vsaa.cn/api/goldpriceapi/index.php

该接口用于获取黄金、白银及铂金的实时动态价格数据。

请求方式

本接口同时支持 GET 与 POST 两种请求方法。无论采用哪种方式，参数传递逻辑保持一致，均需通过 URL 查询参数或请求体携带必要的业务参数。

鉴权说明

调用本接口必须提供密钥。采用 Query 参数方式进行鉴权，需在请求 URL 中附加 key 参数，其值为分配的接口调用密钥。例如：https://api.vsaa.cn/api/goldpriceapi/index.php?key=YOUR_API_KEY&action=realtime&metal=gold。未携带有效密钥或密钥错误的请求将被拒绝。

请求参数

参数名	类型	必填	说明
key	string	是	接口调用密钥，用于身份鉴权
action	string	是	操作方法，固定传 `realtime` 以获取实时动态价格
metal	string	是	金属类型，可选值包括 `gold`（黄金）、`silver`（白银）、`platinum`（铂金）

成功响应示例

{
  "code": 0,
  "message": "ok",
  "data": {
    "metal": "黄金",
    "symbol": "JZJ_au",
    "result": {
      "code": 0,
      "data": [
        {
          "time": "00:00",
          "dateTime": "2026-09-25 00:00:23",
          "price": 921.3,
          "sp": 921.3,
          "bp": 918.3,
          "changeRate": "-0.69%",
          "high": null,
          "low": null,
          "changeAmount": null
        },
        {
          "time": "00:05",
          "dateTime": "2026-09-25 00:05:02",
          "price": 921.59,
          "sp": 921.59,
          "bp": 918.59,
          "changeRate": "-0.66%",
          "high": null,
          "low": null,
          "changeAmount": null
        }
      ]
    }
  },
  "timestamp": "2026-09-25T19:33:01+08:00"
}

响应字段说明

字段路径	类型	说明
code	int	状态码，`0` 表示请求成功。
message	string	状态描述，成功时为 `ok`。
data.metal	string	查询的金属中文名称（如“黄金”）。
data.symbol	string	金属内部标识符号（如 `JZJ_au`）。
data.result.code	int	结果子状态码，`0` 表示数据获取正常。
data.result.data	array	实时价格数据列表，按时间顺序排列。
data.result.data[].time	string	时间点短格式（`HH:mm`）。
data.result.data[].dateTime	string	完整时间戳（`yyyy-MM-dd HH:mm:ss`）。
data.result.data[].price	number	当前实时成交价。
data.result.data[].sp	number	卖出价（Sell Price）。
data.result.data[].bp	number	买入价（Buy Price）。
data.result.data[].changeRate	string	涨跌幅百分比，带正负号（如 `+0.50%`、`-0.30%`）。
data.result.data[].high	number/null	阶段最高价，未填充时为 `null`。
data.result.data[].low	number/null	阶段最低价，未填充时为 `null`。
data.result.data[].changeAmount	number/null	涨跌金额，未填充时为 `null`。
timestamp	string	响应生成的 ISO 8601 时间戳（含时区）。

错误响应示例

接口在校验失败、配额不足或系统异常时返回统一的 JSON 错误结构，code 为 0，msg 描述具体原因，errcode 标识业务错误类型。示例（未提供调用密钥）：

{
  "code": 0,
  "msg": "未提供调用密钥",
  "errcode": 11001
}

业务错误码说明

下列 errcode 对应平台层校验结果，调用方应根据返回的 errcode 判断具体异常场景并采取相应处理策略。

errcode	含义
11001	未提供调用密钥
11002	密钥错误
11003	密钥已禁用
11004	积分余额不足
11005	请求过于频繁（QPM 限制）
11006	接口维护中
11007	接口已禁用
11008	接口不可用
11009	密钥校验暂不可用
11010	积分系统暂不可用
11011	收费接口须提供有效密钥
11012	鉴权方式错误
11013	接口不存在
11014	数据源地址无效
11015	数据源地址不允许
11016	数据源请求失败
11017	服务暂不可用
11018	请求方式不允许
11019	当前IP不在白名单内
11020	启用出口代理须提供有效密钥
11021	未配置可用出口代理
11022	出口代理不可用
11023	密钥已过期
11024	令牌分配积分不足

调用示例

终端 curl（bash）

curl -s "https://api.vsaa.cn/api/goldpriceapi/index.php?key=YOUR_KEY&action=realtime&metal=gold"

PHP

// PHP
$key = "YOUR_KEY";
$action = "realtime";
$metal = "gold";
$url = "https://api.vsaa.cn/api/goldpriceapi/index.php";
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPGET, true);
$ch->setopt_array([
    CURLOPT_HTTPHEADER => array(),
    CURLOPT_POSTFIELDS => http_build_query([
        "key" => $key,
        "action" => $action,
        "metal" => $metal,
    ]),
]);
// 修正：使用 curl_setopt_array 替代误写
curl_setopt_array($ch, [
    CURLOPT_URL => $url,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => http_build_query([
        "key" => $key,
        "action" => $action,
        "metal" => $metal,
    ]),
]);
$response = curl_exec($ch);
curl_close($ch);
echo $response;

注意事项

密钥保管：key 参数通过 URL 查询字符串传递，避免将密钥硬编码到客户端代码或提交至公开仓库；后端服务调用时妥善保管密钥，切勿泄露至前端页面或日志中。
参数取值：action 固定为 realtime；metal 取值需严格对应支持类型（如 gold、silver、platinum），传值错误会导致接口无法识别目标金属。
频率限制：每分钟调用上限约 120 次，高频刷新场景建议设置合理轮询间隔，避免触发限流导致请求被拒绝。
数据时效性：返回数据为实时动态价格，时间戳基于北京时间（+08:00），部分字段（如 high、low、changeAmount）在实时场景下可能为 null，解析时需做判空处理。
传输安全：调用地址使用 HTTPS 协议，确保密钥及请求参数在传输过程中加密，防止中间人窃取。
响应结构：顶层 code 为 0 表示成功，具体价格数据嵌套在 data.result.data 数组中，每条记录包含时间、价格、涨跌等字段，集成时应按此层级解析。

免责声明

欢迎使用 万象数据API（以下简称“本平台”，域名为 api.vsaa.cn）。在使用本平台提供的任何接口、数据及相关服务之前，请您务必仔细阅读并充分理解本免责声明的全部内容。您对本平台任何服务的使用，均视为您已阅读、理解并同意本声明的全部条款。

1. 本平台仅提供**技术接口与数据聚合服务**，不存储、不生产、不拥有任何原始数据内容。 2. 本平台所返回的数据均来源于公开网络或第三方接口，仅作**技术学习、研究与交流**之用。 3. 本平台不保证任何接口的**持续可用性、准确性、完整性或及时性**，接口可能因第三方原因随时变更、中断或停止。 1. 使用者应遵守中华人民共和国相关法律法规，以及其所在地的所有适用法律。 2. **禁止**将本平台接口用于任何违法违规用途，包括但不限于： - 侵犯他人知识产权、隐私权或其他合法权益； - 从事网络攻击、数据爬取滥用、恶意刷量等行为； - 传播违法、有害、虚假或不良信息； - 用于任何商业转售、二次分发而未获授权的情形。 3. 使用者应自行承担因使用本平台服务而产生的一切后果与法律责任。 1. 本平台**不收集、不存储**使用者的个人敏感信息。 2. 使用者通过接口提交的查询参数，仅用于当次请求处理，不做持久化留存。 3. 若接口涉及第三方数据，其版权与解释权归原数据方所有，本平台不承担相关争议责任。 1. 本平台以**“现状”**和**“现有”**为基础提供服务，不对服务作出任何明示或暗示的担保。 2. 因使用或无法使用本平台服务而导致的任何**直接、间接、偶然或必然损失**，本平台及其运营者均不承担任何责任。 3. 因不可抗力、网络故障、第三方服务中断、政策调整等原因导致的服务异常，本平台不承担责任。 1. 本平台的接口设计、文档、代码及相关标识，其知识产权归本平台所有。 2. 未经书面许可，任何单位或个人不得复制、修改、传播或用于商业用途。 1. 本平台有权随时修改本免责声明，修改后的内容将在本页面公布，不再另行通知。 2. 使用者应定期查阅本声明，继续使用即视为接受变更后的条款。 1. 本声明的最终解释权归 **万象数据API** 所有。 2. 如您不同意本声明的任何内容，请立即停止使用本平台服务。 3. 如因本声明产生争议，双方应友好协商解决；协商不成的，可提交本平台运营者所在地有管辖权的人民法院裁决。

最后更新日期：2026年10月6日

金价实时查询

接口信息

请求参数

返回示例

详细文档

金价实时查询

接口说明

调用地址

请求方式

鉴权说明

请求参数

成功响应示例

响应字段说明

错误响应示例

业务错误码说明

调用示例

终端 curl（bash）

PHP

注意事项

快速上手

在线测试

接口反馈

免责声明

免责声明

推荐接口

语言合成_v2