认证
Beta 期使用 Personal Access Token:Authorization: Bearer zyp_…。服务端只保存 token 的哈希与前缀;可随时在 Dashboard 撤销。长期将提供 OAuth 2.1 / MCP Authorization(见 MCP 参考),scope 命名保持不变。
Scopes:project:read project:write render:create render:read share:create usage:read。公开端点(capabilities / themes)无需认证。
幂等
所有 create 类请求支持 Idempotency-Key 头(8–128 位字母数字)。同 key 同内容返回首次响应(带 Idempotent-Replay: true);同 key 不同内容返回 409。Agent 重试永不重复计费。
配额
Free 计划(Beta):渲染 50 次/天、渲染页数 500 页/天、导出 100 次/天、MCP 调用 2000 次/天、API 调用 5000 次/天。用量经 GET /v1/usage 查询;超出返回 402 quota_exceeded。
错误格式
{ "error": { "code": "forbidden_scope", "message": "…", "request_id": "req_…", "details": { "required_scope": "render:create" } } }
错误码:unauthorized forbidden_scope not_found invalid_request payload_too_large rate_limited quota_exceeded idempotency_conflict render_failed config_missing internal。响应头含 X-Zhangyu-Api-Version 与 X-Request-Id。日志与错误信息绝不含正文、token 或私密资产 URL。
限流
认证请求 240 次/分钟,匿名公开端点 60 次/分钟;超限返回 429 + Retry-After。
隐私
正文只在处理该请求时被使用;日志、监控与分析事件均不记录正文。私密渲染资产使用带过期时间的签名 URL。删除 token 即撤销其全部访问。