适用场景在跨境支付、电商比价、财务系统或任何需要动态汇率转换的应用中实时获取外汇兑换比例是一项基础却又关键的工程。本 API 提供了一种轻量级接入方式支持 26 种主流货币CNY / USD / EUR / GBP / JPY 等之间的实时互转数据约 1 分钟级刷新适合对实时性要求较高的非高频场景。典型用法包括客户端汇率小工具 / 计算器插件电商网站的商品用量说明多币种展示财务对账系统中的汇率源旅行类应用的货币换算功能接口能力边界维度说明请求方法GET端点https://v1.apizero.cn/api/exchange-rate支持货币人民币、美元、欧元、英镑、日元、港币、韩元、澳元、加元、新加坡元、瑞士法郎、新台币、泰铢、马来西亚林吉特、俄罗斯卢布、印度卢比、巴西雷亚尔、南非兰特、新西兰元、瑞典/挪威/丹麦克朗、菲律宾比索、印尼盾、越南盾、阿联酋迪拉姆 (共 26 种)数据更新分钟级非实时推送单 IP QPS5 /s (超出后返回频率限制错误)特性支持同币种快路径fromto 时直接返回不消耗上游资源支持货币列表查询 (actioncurrencies)鉴权可选 Authorization Header匿名调用有每日调用上限请求参数详解所有参数均通过 URL Query 传递均为可选参数但组合使用时需符合业务逻辑。参数名类型必填默认值说明moneynumber否1要转换的金额必须大于 0传入 0 或负数会触发校验错误fromstring否CNY源货币代码三字母 ISO 4217不区分大小写如USD、EURtostring否USD目标货币代码格式同上actionstring否(无)传currencies时直接返回支持的货币列表忽略其他参数且不调用上游汇率服务关键设计细节当from和to相同时例如fromUSDtoUSDAPI 会直接返回rate1、resultmoney不经过上游汇率源。这在批量处理或默认展示时能显著降低响应延迟。actioncurrencies是一个隐形的“元操作”不消耗该接口的 QPS 配额适合前端初始化时获取货币列表。货币代码虽不区分大小写但建议统一为大写以避免歧义。鉴权方式API 支持两种调用模式匿名调用直接发起 GET 请求无需携带任何鉴权头。但匿名调用有每日总次数限制以文档最新说明为准超过限制后会返回鉴权错误。鉴权调用在 HTTP Header 中添加Authorization: Bearer sk_live_你的密钥。密钥通过 API 平台申请格式以sk_live_开头。建议在生产环境中始终携带 API Key避免因每日配额耗尽导致服务中断。curl 请求示例以下提供两种可复制的示例执行前请将YOUR_API_KEY替换为真实密钥或将AuthorizationHeader 移除使用匿名模式。示例 1匿名查询 100 人民币兑美元curl -sS -X GET \ https://v1.apizero.cn/api/exchange-rate?money100fromCNYtoUSD示例 2携带 API Key 查询欧元兑日元E5 模式curl -sS -X GET \ -H Authorization: Bearer sk_live_YOUR_API_KEY \ https://v1.apizero.cn/api/exchange-rate?money500fromEURtoJPY示例 3获取支持的货币列表curl -sS -X GET \ https://v1.apizero.cn/api/exchange-rate?actioncurrencies响应为 JSON 数组包含每个货币的code和name_cn字段。响应数据结构解读成功时 HTTP 状态码为 200响应体为 JSON 对象结构如下{ code: 0, msg: 成功, request_id: abc123def456, data: { from: CNY, from_name: 人民币, money: 100, rate: 0.146405, result: 14.6405, to: USD, to_name: 美元, update_time: 2026-05-06 13:00:02 } }字段类型说明codeint业务状态码0 表示成功非 0 请参考错误码表msgstring状态描述成功时为“成功”失败时给出具体原因request_idstring本次请求的唯一标识可用于日志追踪和排查问题data.fromstring源货币代码data.from_namestring源货币中文名称data.moneynumber请求时传入的金额与输入一致data.ratenumber1 单位源货币可兑换的目标货币数量即汇率data.resultnumber转换结果 money * rate已按业务规则四舍五入data.tostring目标货币代码data.to_namestring目标货币中文名称data.update_timestring该汇率最近的更新时间格式YYYY-MM-DD HH:mm:ss时区为北京时间注意rate字段保留 6 位小数result保留 4 位小数这是上游汇率源的处理规则适用于绝大多数货币对。货币列表查询详情当设置actioncurrencies时响应体结构略有不同{ code: 0, msg: 成功, request_id: xyz789, data: [ { code: CNY, name_cn: 人民币 }, { code: USD, name_cn: 美元 }, ... ] }该操作用于动态获取当前 API 支持的全部货币代码及中文名称适合客户端缓存或表单选择器填充。错误处理与常见问题业务错误码codemsg 说明常见原因及处理1001参数错误money必须为正数或from/to代码不在支持列表内。检查请求参数1002鉴权失败匿名调用次数超限或 API Key 无效。添加正确的 Authorization Header或等待配额重置1003频率限制QPS 超过 5/s。建议客户端实现指数退避重试或本地限流1004上游服务异常汇率源临时不可用。可缓存上一次有效结果并稍后重试2000系统内部错误联系平台技术支持提供request_idHTTP 状态码200— 正常响应业务结果需查看code字段。400— 请求格式错误如 URL 编码问题。401— 鉴权头格式错误或密钥无效。429— QPS 超限。503— 服务暂不可用建议退避重试。工程化注意事项重试策略对于 429 和 503 状态码建议使用指数退避1s、2s、4s最大重试 3 次。对于其他错误则直接告警。本地缓存汇率数据分钟级更新对于非实时场景可在客户端缓存 60 秒减少不必要的请求。使用update_time字段判断是否过期。并发控制QPS 上限为 5若需高并发转换多个币种建议批量请求或在代码中实现令牌桶限流。货币代码校验请求前可先调用actioncurrencies获取合法列表避免因参数错误浪费请求。日志与监控记录每次请求的request_id、响应时间及错误码便于快速定位上游或网络问题。API Key 安全密钥应存储在环境变量或密钥管理服务中勿硬编码在客户端代码或版本控制中。参考文档官方文档页https://apizero.cn/aidocs/exchange-rate原始接口说明Markdownhttps://apizero.cn/aidocs/exchange-rate/raw.md以上文档包含了最新的参数说明、变更日志和 FAQ集成前建议查阅。