认证与调用

状态: 生效中
更新: 2026-08-11
适用范围: API Platform 调用面

你需要什么

一个 ZaunEkko Account；
一个 API key——在 Account 的「API key」页面创建；
足够的积分余额。

关于 API key

形如 zek_live_...，长期有效，可随时吊销。

明文只在创建时显示一次，系统只保存它的摘要，关闭页面后无法找回——请立刻存进你的密钥管理工具或环境变量，不要提交进代码仓库。

key 只能用于调用服务。审核、上架、管理服务主体这类操作它做不到，需要你本人在浏览器里完成。这是有意的：长效凭证的暴露窗口比浏览器会话长得多，能做的事就该更窄。

一旦泄露，回到 Account 吊销即可。吊销不可恢复，需要继续使用请新建一条。

发起调用

curl -X POST "https://api.zaunekko.com/v1/services/{serviceCode}/versions/{version}:invoke" \
  -H "Authorization: Bearer zek_live_..." \
  -H "Idempotency-Key: your-stable-unique-key" \
  -H "Content-Type: application/json" \
  -d '{ ...符合该版本请求 schema 的内容 }'

浏览器会话的访问令牌同样可用，但只活很短时间且刷新令牌一次性轮换，不适合无人值守的定时任务——任何一次令牌保存失败都会让集成静默中断。服务端集成请用 API key。

Idempotency-Key 是必填的

这个请求头不能为空，最长 191 字符。它的作用是防止重复计费。

网络超时、连接中断、客户端重试——这些情况下你无法确定请求是否已经到达。此时用同一个 key 重发，平台会认出这是同一次调用，返回原来那次的结果，而不是产生第二笔消耗。

因此这个 key 必须：

对同一次业务意图稳定（重试时不变）；
对不同业务意图唯一（换一次调用就换 key）。

一个可用的做法：把业务标识和时间窗拼进去，例如 daily-ranking-2026-08-08。

同一个 key 配上不同的请求内容会被拒绝，因为那意味着 key 的语义已经被破坏。

查看当前调用额度

每个 Account 都有当前调用窗口额度。你可以在发起新调用前查询：

GET /v1/rate-limit
Authorization: Bearer zek_live_...

响应包含当前 policy、窗口内最多接受的 limit、窗口长度 windowSeconds、已接受次数 accepted、剩余次数 remaining 和重置时间 resetAt。

额度只在平台接受一条新的调用意图时消耗。使用同一个 Idempotency-Key 重放已有调用不会重复计数；换用新的 key 会被视为新调用。

窗口额度用完时，调用返回 HTTP 429 和稳定错误码 RATE_LIMIT_EXCEEDED。响应头 Retry-After 给出建议等待的秒数，响应体同时提供当前 policy、limit、窗口和重试时间：

{
  "code": "RATE_LIMIT_EXCEEDED",
  "message": "当前调用窗口的额度已用完，请稍后重试",
  "policy": "api-human-level-v1",
  "limit": 5,
  "windowSeconds": 60,
  "retryAfter": 37
}

请等待 Retry-After 指定的时间再提交新的调用。若只是在确认一次网络结果未知的调用，请保留原来的 Idempotency-Key 重试。

调用方看不到什么

请求里不接受、回执里也不返回：服务提供方的地址、请求头、凭据、分账明细、参与方标识。

这些不是被隐藏，而是不属于调用方的信息边界。你需要知道的只有：这次调用成功与否、消耗了多少积分、拿到了什么结果。

查看回执

GET /v1/invocations
GET /v1/invocations/{invocationId}

回执包含调用状态与实际消耗。结算状态未落定时，回执不会声称「未扣费」——它会明确告诉你结果待确认，而不是给一个可能错误的零。获批并完成全额积分退款后，结算状态显示为 REFUNDED，实际消耗为 0，同时保留原调用标价和退款时间。

争议、退款与内容报告

你可以在 Marketplace 的调用回执详情里，对自己发起的 HUMAN 调用提交争议；也可以在当前公开的 exact Publication 详情里提交内容报告。提交时平台会使用独立的 Idempotency-Key，网络重试不会重复创建案件。

调用争议获批后，只支持全额退回站内积分。不支持部分退款或现金退款；若退款暂时受阻，案件会保留状态与决定证据，等待后续处理，不会假装已经到账。

内容报告获支持后，平台会暂停该 Listing 的公开展示与新调用。该措施不会删除历史 Publication、Invocation、回执或积分记录；只有平台处理人明确解除后才会恢复。如果同一 Listing 还有其他有效下架决定，解除其中一个案件不会提前恢复。

案件进度可在 Marketplace 的「争议与报告」中查看。你只能看到自己提交的案件，不会看到处理人的账号信息或其他用户的身份。

带产物的服务

部分服务除了返回 JSON，还会产出媒体等二进制内容。这类调用的返回体里不含文件本身，只有产物清单——每项带一个标识与内容摘要。

拿到清单后逐个下载：

GET /v1/invocations/{invocationId}/artifacts/{artifactId}
Authorization: Bearer zek_live_...

只有发起该次调用的账号能下载它的产物，且调用必须已完成结算。

平台会完整读取并按摘要复核后才输出，因此不支持分段下载（Range 请求头会被拒绝）——产物是不可变对象，部分读取无法复核完整性。

失败与重试

定义明确的失败（参数不合法、服务方返回业务错误）：预留的积分会被释放，不产生消耗。
结果未知（超时、连接中断、响应格式异常）：平台不会盲目重发，而是用你的 Idempotency-Key 去核对那次调用的真实结局。你可以安全地用同一个 key 重试。

任何情况下，重复使用同一个 Idempotency-Key 都不会造成第二次扣费。