​
鉴权

所有 /ai/v1/* 接口必须带请求头：
缺失或错误返回 403。令牌值不写在本站，向后端/运维团队索取；它与后端校验 AI 服务回调用的是同一个令牌。 GET /health、GET /docs、GET /openapi.json、GET /llms.txt 不需要鉴权。

​
request_id

每个请求必传的非空字符串，由调用方生成，用于幂等追踪：
  • 同步接口在响应中原样返回。
  • 异步接口（AI-3 / AI-6）的回调 body 里带同一个 request_id，同时回调请求头里有 x-request-id 便于日志串联。
建议生成全局唯一值（如 UUID），不要复用。

​
同步与异步

  • 同步（AI-1&2 / AI-4 / AI-5 / AI-7）：200 响应里直接带结果。
  • 异步（AI-3 / AI-6）：提交成功返回 202 + { "request_id": "...", "accepted": true }，最终结果通过回调 POST 给后端，见回调协议。202 只表示「已受理」，不代表处理成功。

​
字段命名

线上契约一律 snake_case。请求和回调双方都遵守。