本地服务 API

API 鉴权与返回

对外 HTTP 接口，面向外部程序接入、调试和联调。

鉴权规则

  • GET /health 不鉴权。
  • /actions、/actions/info、/actions/run、/action-flows、/action-flows/info、/action-flows/run 在配置了 API Key 时才要求带请求头。
  • 默认请求头名是 X-API-Key。
  • 如果服务启动时没有传入 API Key，本地开发阶段可直接访问受保护端点。

成功返回

所有成功响应都会包成统一外壳：

{
  "success": true,
  "error_code": null,
  "error": null,
  "data": {
    "result": {},
    "variables": {},
    "step_results": {}
  }
}
  • data.result 是主结果。
  • data.variables 是执行结束时的变量快照。
  • data.step_results 是逐步骤结果。

失败返回

失败也有统一外壳：

{
  "success": false,
  "error_code": "VALIDATION_ERROR",
  "error": "错误说明",
  "data": null
}

常见错误码包括：BAD_REQUEST、UNAUTHORIZED、ACTION_NOT_FOUND、VALIDATION_ERROR、SERVICE_BUSY、ACTION_EXECUTION_FAILED。

并发与资源锁

  • 某些动作会走全局串行，服务忙时会返回 SERVICE_BUSY。
  • 剪映草稿相关请求会按最终草稿目录加资源锁。
  • 如果请求里带了剪映草稿动作，但没有显式给 draft_name，会直接校验失败。