图框内截图

重要提示

本接口返回的是位图，适合做局部核对，不建议将整个图框截图交给大模型去识别；
建议先调用各专业的识图接口获取结构化识别结果（建筑、结构、给排水、暖通、电气），再根据识图结果，对存疑、缺失或需要复核的部位用较小的 wcsLoc 局部截图验证；
整张图框截图信息密度高、文字与线条密集，直接交给大模型识别准确率低、耗时长、成本高，且识别结果无法与图框内的结构化数据对应。

接口概述

根据图框 ID 和布局内相对坐标（WCS）下的截图范围，对图框内指定区域截图，响应以附件形式直接返回 PNG 图片。

frameId 来自图框基本信息结果获取接口返回的 data[].frameId，截图范围应参考该接口返回的 frameWcsLoc。

请求地址

http

POST /result/pre/download/captureScreenshotInFrame

请求头

参数	必填	说明
apiKey	是	API 访问凭证，值为 `YOUR_API_KEY`
Content-Type	是	固定为 `application/json`

请求参数

请求体为 JSON 对象：

参数	类型	必填	说明
frameId	String	是	图框唯一标识
wcsLoc	Object	是	截图范围，取布局内相对坐标（WCS）下的矩形区域
wcsLoc.left	Number	是	范围左边界，即最小 X 值
wcsLoc.top	Number	是	范围上边界，即最大 Y 值
wcsLoc.right	Number	是	范围右边界，即最大 X 值
wcsLoc.bottom	Number	是	范围下边界，即最小 Y 值

坐标系说明

布局内相对坐标（WCS，即世界坐标系 World Coordinate System）是指以图框所在布局的原点为参照的坐标：X、Y 轴方向固定在布局上（Y 轴向上），单位与图纸绘图单位一致（通常为毫米），不随视图缩放、图框位置或图框旋转而改变。布局上任意一个点，都能用一对 (x, y) 唯一表示。这里的「相对」是相对布局原点，不是相对上一个点，也不是相对图框左下角。AutoCAD 系列里习惯称这套坐标为「世界坐标系」，但它的作用范围只到图框所在的那个布局（模型空间或图纸空间），并不是整张 DWG 的所有内容共用一套坐标，所以按「布局内相对坐标」理解更准确。图框基本信息接口返回的 layoutName 就表示图框属于哪个布局，不同布局之间的坐标不要直接比较。

使用本接口时可以这样理解：

不需要做任何坐标换算：本接口的 wcsLoc 与图框基本信息结果获取返回的 frameWcsLoc、signFlashWcsLoc、cvSignWcsLoc 是同一套坐标，直接把图框的 frameWcsLoc 当作基准来裁剪即可。
Y 轴向上，与屏幕坐标相反：top 是较大的 Y 值（图框上方），bottom 是较小的 Y 值（图框下方），务必满足 top > bottom。网页、图片等屏幕坐标系是 Y 轴向下，写代码时不要直接把屏幕上的上下关系套用到 wcsLoc 上。
图框旋转不用你处理：即使图框带有旋转角度，wcsLoc 仍按布局内相对坐标填写，服务端会按图框旋转角度自动把截出的图片转正。

示例：图框 frameWcsLoc 为 left=0, top=594, right=841, bottom=0，若要截取图框右下角的图签区域，wcsLoc 传 { "left": 650, "top": 120, "right": 841, "bottom": 0 } 即可。

请求示例

bash

curl -X POST "https://openapi.bangtu-ai.com/openApi/result/pre/download/captureScreenshotInFrame" \
  -H "apiKey:  YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "frameId": "frame-001",
    "wcsLoc": {
      "left": 0.0,
      "top": 594.0,
      "right": 841.0,
      "bottom": 0.0
    }
  }' \
  -o frame-001-screenshot.png

返回结果

调用成功时返回 HTTP 200 与图片流：

响应头	值
Content-Type	`image/png`
Content-Disposition	`attachment;filename*=utf-8''{frameId}-screenshot.png`
Cache-Control	`no-cache`

响应体为 PNG 图片二进制内容。截图时会按图框旋转角度自动还原方向，因此返回的图片方向与图纸中的图框方向一致。

截图范围校验

wcsLoc 必须完全位于图框范围（frameWcsLoc）内，否则请求失败：

条件	要求
left	不小于图框范围的 left
top	不大于图框范围的 top
right	不大于图框范围的 right
bottom	不小于图框范围的 bottom

如需截取整个图框，可直接使用图框基本信息结果中的 frameWcsLoc 原值。

失败响应

接口异常时返回通用 JSON 错误结构：

json

{
  "code": 500,
  "message": "系统繁忙，请稍后再试",
  "data": null,
  "timestamp": 1784533710000
}

常见失败原因包括：frameId 或 wcsLoc 缺失、图框不存在、图框缓存数据未找到、图框范围数据不存在、截图范围超出图框范围、截图服务未返回图片地址。截图为同步调用，失败时请在服务端日志中查看具体原因。

调用流程

调用图纸基本信息识别任务创建接口，获取 taskId。
轮询任务状态查询接口，等待状态变为 SUCCESS。
调用图框基本信息结果获取接口，获取图框列表、frameId 及 frameWcsLoc。
按业务需要计算截图范围并调用本接口获取图框图片。

注意事项

本接口用于局部截图核对，请勿将整个图框截图交给大模型识别，建议先识图再按需局部截图验证，详见文首「重要提示」。
wcsLoc 使用布局内相对坐标（WCS），Y 轴向上、top 大于 bottom，与屏幕坐标系相反，详见上文「坐标系说明」。
截图范围为必填参数，且不能超出图框范围，建议在图框范围内按需裁剪，例如仅截取图签区域。
接口为同步调用，截图耗时与图框大小有关，请设置合理的请求超时时间。
接口不做缓存，同一范围重复调用会重新触发截图。
frameId 应按字符串传递，不要转换为数字。

图框内截图 ​

接口概述 ​

请求地址 ​

请求头 ​

请求参数 ​

坐标系说明 ​

请求示例 ​

返回结果 ​

截图范围校验 ​

失败响应 ​

调用流程 ​

注意事项 ​