本地 HTTP(S) 接口

SDK Open 通过本地 Asset HTTP/HTTPS 端点提供输入文件上传和任务资产读取能力。

站点	地址	说明
Asset HTTPS	https://sdk-runtime.localhost:18082	对外 SDK 默认端点，用于上传文件和读取任务资产。
Asset HTTP	http://127.0.0.1:17082	明文兼容端点。

对外 SDK 默认开启 TLS，并使用 sdk-runtime.localhost 本机域名。Asset HTTP 端口可通过 SDK_ASSET_HTTP_PORT 覆盖，Asset HTTPS 端口可通过 SDK_ASSET_HTTPS_PORT 覆盖。自定义 TLS 部署时，客户端应使用证书匹配的 <tls-host>，并信任服务端证书或其签发 CA。

资产 URL 默认使用配置的资产基地址；如需通过 HTTPS、反向代理或固定外部地址访问，请将 SDK_ASSET_BASE_URL 设置为客户端实际可访问的 HTTPS 基地址，例如 https://sdk.example.com:18082。

需要鉴权的接口使用：

Authorization: Bearer <token>

上传和资产接口使用 auth.create_session 返回的 session_token。

接口支持 CORS 预检，允许 Authorization、Content-Type 请求头，以及 GET、POST、OPTIONS 方法。

上传接口

POST /api/uploads/images 和 POST /api/uploads/files 接受 multipart/form-data，当前两个路径走同一套上传处理逻辑。

鉴权要求：Authorization: Bearer <session_token>。该 session 需要具备 image.process、image.enhance 或 file.convert 任一 capability。

字段	类型	必填	说明
file	file	是	图片、PDF、OFD 或 TIFF。文件不能为空，最大 50MB。

支持的文件扩展名：jpg、jpeg、png、bmp、tif、tiff、webp、pdf、ofd。当 Content-Type 为空或为 application/octet-stream 时，会根据扩展名补充资产 content_type。

成功响应：

字段	类型	说明
upload_id	string	后续 Command 方法使用的上传 ID。
asset	object	原始资产，asset_id=asset-original，kind=original，包含 path、url、download_url、content_type、width、height、size。上传文件的 width、height 可能为 0。

示例：

curl -X POST "https://sdk-runtime.localhost:18082/api/uploads/files" \
  -H "Authorization: Bearer <session_token>" \
  -F "file=@/path/to/input.pdf"

响应示例：

{
  "upload_id": "img-1780920159-1",
  "asset": {
    "asset_id": "asset-original",
    "kind": "original",
    "path": "/home/user/.czur/sdk/image/img-1780920159-1/assets/original.pdf",
    "url": "https://sdk-runtime.localhost:18082/api/assets/img-1780920159-1/asset-original",
    "download_url": "https://sdk-runtime.localhost:18082/api/assets/img-1780920159-1/asset-original/download",
    "content_type": "application/pdf",
    "width": 0,
    "height": 0,
    "size": 102400
  }
}

资产接口

接口	鉴权	说明
GET /api/assets/{task_id}/{asset_id}	session token	以内联方式读取资产，响应头 Content-Disposition: inline。
GET /api/assets/{task_id}/{asset_id}/download	session token	以附件方式下载资产，响应头 Content-Disposition: attachment; filename="{asset_id}"。

资产访问会校验 session_token 所属连接和任务资产归属。跨连接读取会返回 capability 或 session 错误。当前资产读取规则：

资产来源	读取要求
上传资产、图像处理资产、文件转换资产、SANE 扫描资产	同一连接，且 session 具备 image.process、image.enhance、file.convert 或 sane.scan 任一 capability。
图像增强任务资产	同一连接，且 session 具备 image.enhance。
采集任务资产	同一连接，且 session 具备 capture.get。

如果资产记录存在但本地文件已不存在，HTTP 返回 404。

错误响应

HTTP 接口错误响应使用统一 JSON：

{
  "code": 401,
  "message": "unauthorized",
  "data": {}
}

常见 HTTP 状态：

HTTP 状态	场景
400	缺少 multipart file 字段，或上传文件为空、过大、格式不支持。
401	缺少或无效的 session token。
403	session 存在，但缺少访问上传或资产所需 capability。
404	上传或资产接口未启用，或资产不存在。
500	内部错误。