REST API · v1

井身结构图渲染 API

提交 YAML 或 JSON 井数据，异步生成 PNG / SVG 结构图与配套数据文件。所有示例以当前站点为基地址。

JSON / YAMLBearer Token异步任务 + SSE

身份认证

程序调用使用 API Key。在 API Key 页面生成后，通过 Bearer 头发送。网页账户操作使用安全会话 Cookie。

Authorization: Bearer YOUR_API_KEY

API Key 明文只在创建时显示一次。不要放入 URL、日志或版本库。

渲染流程

提交返回 202 Accepted 与 job 快照。随后轮询状态，或订阅 SSE，直到 success / failed。

GET/api/health

实例存活探针；无需认证。返回 { status, renderRoot }。

POST/api/jobs?image_format=png

提交井数据。Content-Type 为 application/yaml 或 application/json；image_format 为 png 或 svg。

curl -X POST "$BASE/api/jobs?image_format=png" \
  -H "Authorization: Bearer $WELLBORE_API_KEY" \
  -H "Content-Type: application/yaml" \
  --data-binary @well.yaml

GET/api/jobs/{job_id}

查询当前状态。响应字段：id、archive_id、status、warnings、files、error。

GET/api/jobs/{job_id}/events

SSE 状态流，事件名为 status。连接先返回当前快照，每次状态迁移再发送一帧，终态后关闭。

成功响应

{
  "id": "7a45…",
  "status": "success",
  "warnings": [],
  "files": [{"name": "well_structure_plot.png", "bytes": 248310}],
  "error": null
}

status 依次为 queued、running，最终进入 success 或 failed。失败时 HTTP 查询仍返回 200，具体问题位于 error。

井数据契约

顶层字段如下。除 wellInfo 外，其余数据块可按需省略或设为 null；深度单位均为米，直径为毫米，密度为 g/cm³。

字段	类型	说明
`wellInfo`	object	井名、井型、总井深、最大垂深、井斜角
`keyPoints`	object \| null	造斜点、侧钻点、靶点 A/B 及隐藏清单
`stratigraphy`	array \| null	地层名、顶深与底深
`drillingFluidAndPressure`	array \| null	钻井液分段、孔隙/破裂压力与安全窗口
`holeSections`	array \| null	井眼开次、套管、水泥区间与标注方式
`pilotHoleGuideLine`	object \| "auto" \| null	导眼辅助线自动推导或手工参数
`fluidDensityAxis`	[min, max] \| null	压力密度轴范围，元素可为数字或 `auto`
`drillingFluidLabelHide`	array \| null	要隐藏的压力标签字段名

最小 YAML

wellInfo:
  wellName: 示例井
  wellType: straight well
  totalDepth_m: 2500
  deviationAngle_deg: 0
  maxVerticalDepth_m: 2500

井身结构示例

holeSections:
  - topDepth_m: 0
    bottomDepth_m: 1500
    diameter_mm: 311.2
    drawingDiameter_mm: auto
    note: 二开
    labelLayout: slide
    casings:
      - topDepth_m: 0
        bottomDepth_m: 1495
        od_mm: 244.5
        drawingOd_mm: null
        note: 技术套管
        hanger: false
        casingHead: true
        cement:
          mode: full

服务端执行完整的交叉字段校验。校验失败时，errors 会给出字段路径和原因；不要依赖页面表单作为唯一校验。

账户与 API Key

新账户默认为 Free，仅管理员能升级。网页、API 与 MCP 共用渲染额度，按北京时间重置，每周从周一开始。

Free每月 36 次历史保留 6 条

Go每周 36 次历史保留 12 条

Plus每天 36 次历史保留 36 条

Pro每天 360 次历史保留 60 条

POST/api/register

{ code, username, password }；创建账户并建立网页登录会话。

POST/api/login

{ username, password }；建立网页登录会话。

POST/api/password-reset

{ username, temporary_password, new_password }；无需登录，临时密码一天有效且只能使用一次。成功返回 204 并撤销旧会话和 API Key。

POST/api/admin/accounts/{user_id}/temporary-password

仅管理员会话；返回一次性临时密码和 expires_at，重新生成使上一份失效。

PATCH/api/admin/accounts/{user_id}/restriction

{ disabled: true | false }；仅管理员会话可冻结/解冻，冻结阻止网页登录、API 和 MCP 访问；解冻须重新登录。

POST/api/logout

结束当前网页登录会话，返回 204。

GET/api/account

当前用户身份；会话或 API Key 均可读取。

GET/api/account/profile

当前账户的完整资料；仅网页会话可用。

GET/api/account/quota

等级、剩余额度、重置时间与历史上限；会话或 API Key 均可读取。

GET/api/admin/accounts

管理员会话可列出账户。

PATCH/api/admin/accounts/{user_id}/tier

{ tier: "free" | "go" | "plus" | "pro" }；仅管理员会话可更新等级。降级会永久清理超过上限的最旧历史。

PATCH/api/account

更新显示名称、简介和头像；仅网页会话可用。

POST/api/account/password

{ current_password, new_password }；仅网页会话可用。

POST/api/keys

{ label }；创建 API Key，返回 201，明文只出现一次。

GET/api/keys

列出当前账户的 Key 元数据，不返回明文。

DELETE/api/keys/{key_id}

撤销指定 Key，返回 204。

历史与产物

POST/api/account/projects

创建空项目，返回独立 ID；不消耗绘图额度，占普通历史条数，仅网页会话可用。

PATCH/api/account/artifacts/{id}

设置 { name, favorite }（可只传其中一项）。名称最多 100 字，留空使用井名，无井名为「未命名项目」。每账户最多收藏 6 个，不占普通历史额度，不被自动清理；取消收藏后按普通历史规则清理。仅网页会话可用。

POST/api/input/normalize

公开只读：提交 YAML 或 JSON，返回通过现有输入校验的完整 JSON，供编辑器同步表单；不创建任务，不消耗调用额度。

POST/api/account/artifacts/{id}/copy

复制自己的历史，返回独立副本 ID；占历史条数，不消耗渲染额度。使用 POST /api/jobs?edit={id} 在生成成功后更新所选会话。任务状态中的 archive_id 是更新后的产物下载 ID。

GET/api/account/artifacts

列出当前账户仍在磁盘上的历史记录：id、created_at、files、name、custom_name、favorite、draft；空项目也出现在列表中。

DELETE/api/account/artifacts/{job_id}

永久清理自己的输入与全部产物，返回 204；仅网页会话可用。活跃任务返回 409。

POST/api/account/artifacts/delete

{ ids: ["uuid"] }；勾选批量永久清理，返回 204。删除不会返还已用次数。

GET/api/renders/{id}/{name}

下载一份产物。MCP 返回的 PNG/SVG 主图签名链接有效期为 20 分钟，可直接下载；其它产物使用 API Key 或会话。特殊名称 well_data.yaml 返回规范化 YAML。

GET/api/renders/{id}/well_data.yaml

取这次渲染的规范化输入（YAML）。与取产物同一条路，仅创建者可访问。

GET/api/renders/{id}.zip

下载该次渲染的全量 ZIP，需要创建者的 API Key 或会话。有效签名主图链接可分享，冻结账户或撤销签发 Key 会阻断链接。

错误格式

所有非 2xx 响应使用 application/problem+json。保留 traceId 便于排查。

{
  "type": "about:blank",
  "title": "输入未通过校验",
  "status": 422,
  "detail": "共 2 处问题",
  "instance": "/api/jobs",
  "traceId": "…",
  "errors": []
}

状态码	含义	处理建议
401	凭据缺失或无效	登录或更换 API Key
403	当前凭据无权执行	账户管理请使用网页会话
404	资源不存在或不属于当前用户	检查 ID 与账户
409	会话仍在生成	等待渲染结束后清理
429	调用额度用尽	等待周期重置或联系管理员升级
413	请求体过大	缩减输入
415	内容类型不支持	使用 JSON 或 YAML
422	字段或井数据校验失败	按 errors 修正输入
503	任务队列已满	稍后重试
504	渲染超时	简化输入或联系运维