跳转到内容
Zelnum API

OpenAPI

本文档里的每个接口同时也以机器可读的 OpenAPI 3.1 形式发布，你可以直接让工具链读契约，而不用手抄表格。

版本地址说明
文档站https://docs.zelnum.com/openapi.yaml稳定地址，位于本站域名下。阅读本站时以它为准。
平台https://app.zelnum.com/docs/openapi.yaml上游源。文档站的副本与它逐字节一致。

两个文件是同一份文档。之所以做镜像，是为了让规范落在你正在阅读的域名下，并且是一个工具能猜到的路径。

文档里有什么

Section titled “文档里有什么”
部分数量内容
Servers1https://api.zelnum.com/api/v1
Paths10九个正式接口，外加一个实时兼容接口
Tags3Common、Realtime、Bulk —— 与导航的分组一致
Schemas9请求体、响应体，以及错误信封
安全方案2X-API-Key 与 Authorization: Bearer

接口级的细节都在文档自身：必需的请求头、数组上的 minItems/maxItems、series、mode、status、billing_status 的枚举，以及 POST /v1/realtime/detect 上的 deprecated: true 标记。

导入到接口工具

Section titled “导入到接口工具”

Postman —— Import → File → openapi.yaml。Postman 会生成一个集合，并把基础地址放进环境变量；把你的 key 设为集合级的 X-API-Key 请求头，后续每个请求都会继承。

Insomnia —— Create → Import From → File，然后把 X-API-Key 加为集合请求头。

Bruno / HTTPie / curl 生成器 —— 都直接支持 OpenAPI 3.1：

Terminal window
curl -fsSL https://docs.zelnum.com/openapi.yaml -o zelnum.yaml

生成类型化客户端

Section titled “生成类型化客户端”

我们不做官方 SDK —— 接口就是 HTTPS 上的普通 JSON，而且多数情况下生成出来的客户端比手写的更合适，因为它遵循你所用语言的惯例。

Terminal window
# 选你的生成器：python、typescript-fetch、php、go、java、csharp、ruby ……
npx @openapitools/openapi-generator-cli generate \
  -i https://docs.zelnum.com/openapi.yaml \
  -g python \
  -o ./zelnum-client

生成的客户端会从文档里读取基础地址与安全方案，所以运行时你只需要提供 API key。

让镜像保持诚实

Section titled “让镜像保持诚实”

镜像跟随上游，绝不在这里改。契约与文档之间发生漂移，正是这个页面存在的意义，所以副本是与上游比对过的，而不是靠信任：

Terminal window
npm run openapi:check   # 拉取上游，字节不一致即失败
npm run openapi:sync    # 重新同步，并打印哪些接口发生了变化

openapi:check 需要网络，因此刻意不放进站点构建 —— 部署不该因为平台主机抽风而失败。构建实际强制的是这条不变量的离线一半：本文档描述的每个接口都必须存在于随包发布的规范中，页面无法记录一个契约里没有的接口。

下一步

Section titled “下一步”