免费黄金价格 API：XAU、JSON 与 Python 接入

需要 XAU/USD 金价，可从黄金价格聚合工具开始。2026 年 10 月 21 日的端到端实测返回 HTTP 200、success=true，包含以美元／金衡盎司计价的价格、bid 和 ask。下文示例使用同一个具体工具。

• 免费指试用额度。QVeris 当前列出注册验证后的 1,000 一次性试用积分。本次两个工具分别记录 1 credit，响应时结算仍为 pending。
• 不同区域，分别接入。国际区实测使用黄金聚合工具，中国区使用另一项 MetalpriceAPI 工具和不同 API 入口。
• 最新不等于实时。两次返回的数据时间相差 8 小时 45 分 05 秒；单次查询不能证明持续更新频率。

本文实测时间均为北京时间（UTC+08:00），价格为带日期的测试记录，不是当前实时行情。目录验证状态仍为 unverified。参见当前试用与计费条款。

Gold Price Aggregation（黄金价格聚合）是国际区的接入起点。先在工具详情查看输入参数和当前计费规则，再获取对应区域的 Token，发起 API 请求。

建议路径：本文 → 对应工具详情 → 获取所属区域 Token → 单次调用。需要其他能力时再使用通用工具搜索；执行契约见Call API 调用文档。

在本地终端或服务器中，将国际区 Token 配置为环境变量 QVERIS_API_KEY。示例不包含访问凭据。cURL 与 Python 是两种可选方式，每执行一种都会发送一次按规则计费的请求。

cURL：查询一次 XAU/USD

: "${QVERIS_API_KEY:?Set the matching region Token in QVERIS_API_KEY first}"
curl --fail-with-body --silent --show-error --max-time 30 \
  --request POST "https://qveris.ai/api/v1/tools/execute" \
  --header "Authorization: Bearer $QVERIS_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
  "tool_id": "qveris_finance.gold_price_aggregation_v1",
  "parameters": {
    "symbol": "XAU",
    "quote": "USD",
    "limit": 1
  }
}'

Python 3：发起请求并打印返回 JSON

仅使用 Python 标准库。保存为 gold_price.py，配置环境变量后运行 python3 gold_price.py。

import json
import os
import urllib.error
import urllib.request

token = os.environ.get("QVERIS_API_KEY")
if not token:
    raise SystemExit("Set QVERIS_API_KEY to your international-region Token.")

payload = {
    "tool_id": "qveris_finance.gold_price_aggregation_v1",
    "parameters": {"symbol": "XAU", "quote": "USD", "limit": 1},
}
request = urllib.request.Request(
    "https://qveris.ai/api/v1/tools/execute",
    data=json.dumps(payload).encode("utf-8"),
    headers={
        "Authorization": f"Bearer {token}",
        "Content-Type": "application/json",
    },
    method="POST",
)
try:
    with urllib.request.urlopen(request, timeout=30) as response:
        result = json.load(response)
except urllib.error.HTTPError as exc:
    raise SystemExit(f"HTTP {exc.code}: check the region, credits and parameters.") from exc
except (urllib.error.URLError, TimeoutError) as exc:
    raise SystemExit("Network failure or timeout. Check Usage before retrying.") from exc

if not isinstance(result, dict) or result.get("success") is not True:
    raise SystemExit("Tool execution did not succeed; inspect the response before retrying.")
print(json.dumps(result, ensure_ascii=False, indent=2))

Python 示例检查 HTTP 错误和 API 的 success 标志，再打印真实响应，不假定价格字段的嵌套路径。两份示例都不自动重试；请求超时可能留下不确定的执行结果，应先检查 Usage，再决定是否重发。应用重试需遵循 429 响应和调用契约。

国际区实测返回 price = ask = 4,122.22、bid = 4,121.72，单位为美元／金衡盎司。数据时间为北京时间 2026 年 10 月 21 日 16:45:04，来源为 commodity_price_api。

{
  "tool_id": "qveris_finance.gold_price_aggregation_v1",
  "observed_fields": {
    "price": 4122.22,
    "ask": 4122.22,
    "bid": 4121.72
  },
  "currency": "USD",
  "unit": "troy_ounce",
  "source": "commodity_price_api",
  "data_time_beijing": "2026-10-21T16:45:04+08:00"
}

接入时同时保留原始响应和规范化数据，保存来源、币种、单位与时区；展示为当前行情前，检查时间缺失或数据陈旧的情况。

所提供的实测记录中，两区 Token 认证、搜索及各一次数据调用均成功。工具覆盖仍需分别检查：中国区按 ID 查询没有返回国际区的黄金聚合工具。

中国区 cURL 示例

将中国区 Token 配置为 QVERIS_CN_API_KEY。MetalpriceAPI 工具详情网页位于国际站；中国区已实测的 API 入口仍为 https://api.qveris.cn/api/v1/tools/execute。

: "${QVERIS_CN_API_KEY:?Set the matching region Token in QVERIS_CN_API_KEY first}"
curl --fail-with-body --silent --show-error --max-time 30 \
  --request POST "https://api.qveris.cn/api/v1/tools/execute" \
  --header "Authorization: Bearer $QVERIS_CN_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
  "tool_id": "metalpriceapi.latest.retrieve.v1.f8ea59a7",
  "parameters": {
    "base": "USD",
    "currencies": "XAU"
  }
}'

不要把 XAU 字段直接当美元金价

{
  "USDXAU": 4137.5007344064,
  "XAU": 0.0002416918
}

当 base=USD 时，XAU=0.0002416918 表示每美元对应的黄金数量；USDXAU=4137.5007344064 表示其倒数，即每金衡盎司的美元价格。1 / 0.0002416918 ≈ 4137.5007344064，不能将 0.0002416918 标成美元金价。参见MetalpriceAPI 单位与汇率文档（英文原文）。

此次调用没有验证人民币／克、上海金、金店零售价或历史行情。国际区目录中也能查到 commodity_price_api 直连工具和 NBP 今日金价工具，但本次均未执行，因此不列为已实测工具。

截至 2026 年 10 月 21 日，国际站QVeris 定价页列出注册验证后 1,000 一次性试用积分。Discover 与 Inspect 免费，执行按所选工具的计费规则消耗积分。试用不等于无限调用或永久免费金价数据；中国区资格与活动额度应在所属区域账户中另行确认。

本次查阅的两个公开工具详情页都显示每次调用 1 credit。两次成功调用也各记录 1 credit，但响应时结算仍为 pending。这是观察到的待结算记录，不代表已经对账确认最终扣费。

试用积分用完后，继续执行计费调用需要账户具有足够积分，并遵循当前套餐或充值条款。执行前查看工具规则，执行后通过 Usage 或积分账本确认最终结算；重试、其他工具及外部 AI 客户端费用可能增加成本。

免费实时金价 API，真的实时吗？

两次调用都返回了最新价格结果，但并未验证任一工具的更新周期、最大延迟或交易时段行为。应逐次检查来源时间戳。目录中的 Updated 或 Freshness 时间描述目录条目，不一定是金价观测时间。MetalpriceAPI 文档说明延迟随套餐变化，但仅凭这点不能确认本次 QVeris 调用背后的上游套餐。参见供应商文档（英文原文）。

可以获取免费的历史黄金价格吗？

本次没有实测历史金价。本文的最新价格请求不能证明历史行情覆盖。需要历史数据时，应另查适用工具，并单独验证日期范围、日线或日内粒度、缺失区间、修订、价格口径、单位与费用。

XAU/USD 能直接当作人民币／克、上海金或金店价吗？

本次没有验证这些能力。币种或重量换算属于计算，不代表取得上海市场报价或金店零售价。现货、基准、期货和零售金价的含义不同，可参考世界黄金协会金价资料（英文原文）及LBMA 黄金基准说明（英文原文）；这些资料不属于本文额外实测的 QVeris 接口。

初次验收可以从小任务开始：检查工具、执行一次请求、验证 JSON、保留时间戳，再查看最终用量记录。一次调用成功是具体证据，不是持续可用或许可保证。

更新日期：2026 年 10 月 21 日。上述两区执行结果来自所提供的端到端实测记录：先完成认证与搜索，再在两区各执行一次实际查询。本次页面修订重新核对了公开指南、工具详情、定价及调用文档，没有重复执行付费数据调用，也未包含任何 Token。

两个工具详情地址均返回 HTTP 200，标题和工具 ID 匹配；目录状态仍为 unverified。单次查询成功不承诺持续可用、正式认证或商用转授权。所提供的记录不含完整原始响应和最终结算对账。

保留的原文白板配图是英文选型流程，包含实时与历史需求检查，不代表图中所有能力均已实测。