适用场景与接口能力边界实时汇率查询API适用于任何需要货币转换的场景跨境电商平台展示商品多币种用量说明、旅行规划工具估算当地费用、财务分析系统多币种报表、个人记账软件等。接口提供26种主流货币CNY、USD、EUR、GBP、JPY、HKD、KRW、AUD、CAD、SGD、CHF、TWD、THB、MYR、RUB、INR、BRL、ZAR、NZD、SEK、NOK、DKK、PHP、IDR、VND、AED之间的实时互转数据1分钟级更新响应时间在毫秒级别。能力边界QPS5次/秒支持同币种快路径当from和to为相同货币时本地直接返回结果不消耗上游资源。货币列表查询通过actioncurrencies子命令无需鉴权即可获取全部支持货币的代码与中文名可用来动态生成下拉选择器。调用限制匿名调用每日有50次调用额度携带有效API Key可提升额度具体以文档为准。请求参数详解接口使用GET方法地址为https://v1.apizero.cn/api/exchange-rate所有参数均为Query String形式。参数名是否必填类型说明默认值示例值money否number要转换的金额必须大于01100from否string源货币代码ISO 4217三字母CNYCNYto否string目标货币代码ISO 4217三字母USDUSDaction否string传currencies返回支持货币列表忽略其他参数无currencies注意货币代码不区分大小写但建议统一使用大写。actioncurrencies是一个独立功能此时不进行汇率换算直接返回所有支持货币的列表包含code和name_cn字段。此操作不消耗调用配额。鉴权方式请求支持两种调用模式匿名调用不携带任何鉴权头每日可调用50次。授权调用在HTTP头部添加Authorization格式为Bearer sk_live_xxxxxxxxxxxxxx具体Key需从服务商获取。携带Key后调用次数更高具体以服务商文档为准。接入示例cURL以下提供两个可复制示例测试时请替换为真实金额或货币代码。匿名调用1 CNY 兑换 USDcurl -sS -X GET \ https://v1.apizero.cn/api/exchange-rate?money1fromCNYtoUSD携带 Authorization 头的调用100 USD 兑换 JPYcurl -sS -X GET \ -H Authorization: Bearer sk_live_YOUR_API_KEY \ https://v1.apizero.cn/api/exchange-rate?money100fromUSDtoJPY获取支持货币列表curl -sS -X GET \ https://v1.apizero.cn/api/exchange-rate?actioncurrencies接入示例Pythonrequests库import requests # 配置参数 url https://v1.apizero.cn/api/exchange-rate params { money: 1, from: CNY, to: USD } # 匿名调用 resp requests.get(url, paramsparams) data resp.json() if data.get(code) 0: print(f{data[data][money]} {data[data][from_name]} {data[data][result]} {data[data][to_name]}) print(f汇率更新时间{data[data][update_time]}) else: print(f错误{data.get(msg)}) # 如需鉴权添加headers # headers {Authorization: Bearer sk_live_xxxxxxxxxxxxxx} # resp requests.get(url, paramsparams, headersheaders)接入示例JavaScriptfetchconst url new URL(https://v1.apizero.cn/api/exchange-rate); url.searchParams.set(money, 1); url.searchParams.set(from, CNY); url.searchParams.set(to, USD); fetch(url) .then(response response.json()) .then(data { if (data.code 0) { console.log(${data.data.money} ${data.data.from_name} ${data.data.result} ${data.data.to_name}); console.log(汇率更新时间${data.data.update_time}); } else { console.error(错误, data.msg); } }) .catch(error console.error(请求失败, error));返回值解读成功换算响应HTTP 200{ code: 0, data: { from: CNY, from_name: 人民币, money: 1, rate: 0.146405, result: 0.1464, to: USD, to_name: 美元, update_time: 2026-05-06 13:00:02 }, msg: 成功, request_id: abc123def456 }字段说明code状态码0 表示成功非0表示失败。msg描述信息成功时为“成功”失败时提供错误原因。request_id请求唯一标识可用于问题排查。data.from/data.to源/目标货币代码。data.from_name/data.to_name对应货币的中文名称。data.money请求的金额。data.rate实时汇率1单位源货币可兑换多少单位目标货币。data.result兑换结果money × rate保留小数点后四位。data.update_time数据更新时间格式YYYY-MM-DD HH:mm:ss。货币列表响应actioncurrencies当请求携带actioncurrencies时返回一个包含所有支持货币对象的数组每个对象包含code货币代码和name_cn中文名称。具体结构请以实际文档为准。常见错误与处理HTTP状态码code值含义处理建议4004001参数错误如money0、无效货币代码、缺少必要参数检查请求参数是否合法货币代码是否为26种之一4014002鉴权失败Authorization头格式错误或Key无效确认Bearer后空格格式检查API Key是否有效4294003频率超限超过QPS 5/s或每日额度增加请求间隔或升级配额5005000服务端内部错误稍后重试若持续失败请联系服务商注意以上错误码和对应处理方案基于常见接口规范具体请以原始文档为准。工程化注意事项缓存策略汇率数据每分钟更新建议在客户端或中间层缓存1分钟避免大量重复请求。缓存过期后只拉取一次可大幅降低QPS压力。降级与容错当API返回非0码或网络异常时应展示上次缓存的汇率或提示用户“汇率获取失败”不要直接阻塞业务流程。前端展示金额保留两位小数即可汇率显示四位小数注意不同货币的精度差异如日元通常无小数。货币列表动态化利用actioncurrencies接口在应用启动时拉取支持货币列表并缓存当上游新增货币时无需发版即可支持。安全实践API Key 仅应在服务端环境变量中配置绝不可暴露在前端代码中。前端应通过后端代理转发请求。参考文档文档页https://apizero.cn/aidocs/exchange-rate原始文档https://apizero.cn/aidocs/exchange-rate/raw.md
)
