§ API REFERENCE

创建执行

POST/executionsscope: executions:write

为某外部用户在某能力上创建一次执行（去 PII 解析主体 + 幂等 + 额度冻结）。

鉴权：Authorization: Bearer <access_token>。

§ 1

请求信息

REQUEST

POST https://api.lingxiguangnian.com/api/open/v1/executions

请求头

参数	类型	必填	说明
`Authorization`	string	是	Bearer <access_token>。由 POST /token 换取，有效期 2 小时；api_secret 不得直连业务端点（→ 401）。
`Idempotency-Key`	string	是	幂等键（16-256 字符）。同键返回同一 execution_id，不重复冻结。

请求体参数

参数	类型	必填	说明
`external_user_id`	string	是	调用方自有用户标识（业务键，非 PII）。
`resource_type`	enum	是	来自 capabilities.resource_type。
`resource_id`	uuid	是	来自 capabilities.resource_id。
`kind`	string	否	兼容字段；建议不传，由服务端按资源真源推导。
`session_type`	enum	否	计费会话类型 assessment / game / consultation / none（默认 none）。
`metadata_safe`	object	否	非 PII 辅助上下文（服务端二次校验）。

§ 2

调用示例

EXAMPLES

POST /executions

curl -X POST "https://api.lingxiguangnian.com/api/open/v1/executions" \
  -H "Authorization: Bearer oat_xxxxxxxxxxxxxxxx" \
  -H "Idempotency-Key: order-2026-0001" \
  -H "Content-Type: application/json" \
  -d '{ "external_user_id": "ext-u-912", "resource_type": "CAPABILITY_UNIT", "resource_id": "22222222-2222-4222-8222-222222222222" }'

§ 3

返回结果

RESPONSE

返回字段

参数	类型	必填	说明
`execution_id`	uuid	是	执行 ID。
`replayed`	boolean	是	true=幂等命中(200)；false=新建(201)。

RESPONSE · JSON

{ "success": true, "data": { "execution_id": "9b8e0c2a-3d4f-4a5b-8c6d-7e8f9a0b1c2d", "replayed": false } }

§ 4

端点错误码

ERRORS

通用鉴权、scope 与限流错误见「使用概述」；下表为本端点专属错误。

HTTP	error_code	触发条件
422	`open_api.validation_error`	请求体字段缺失 / 类型错。
422	`open_api.pii_in_metadata`	metadata_safe 含明文个人信息。
400	`open_api.idempotency_key_required`	缺 Idempotency-Key 头。
410	`open_api.standalone_assessment_deprecated`	尝试创建独立认知评估执行。
402	`open_api.credit_freeze_failed`	额度不足 / 冻结失败。

使用说明

创建成功后执行进入 RUNNING；冻结金额取目录当前有效价格。同一 Idempotency-Key 重放不重复冻结。

契约真源：apps/m-master/src/app/api/open/v1/executions/route.ts