开发文档

商户通过服务端签名调用绘城智算 API

签名鉴权

统一鉴权规则

绘城智算所有 OpenAPI 请求统一使用 API Key + HMAC-SHA256 签名。图视觉大脑与绘城智绘共用同一套 账户、应用、AccessKey 与签名体系。

必填请求头

X-HC-Access-Key: your_access_key
X-HC-Timestamp: unix_timestamp
X-HC-Nonce: unique_random_nonce
X-HC-Request-Id: unique_request_id
X-HC-Signature: hmac_sha256_signature

请求时间戳默认允许服务器时间前后 300 秒。 每次请求必须生成新的 Nonce，Nonce 不允许重复使用。

Canonical String

METHOD
PATH
TIMESTAMP
NONCE
PAYLOAD_HASH

五部分之间使用换行符 \n 连接， 不增加空格或额外空行。 

signature =
HMAC_SHA256(
  canonical_string,
  SecretKey
)

普通 JSON 请求

PAYLOAD_HASH = SHA256(raw_http_body)

GET 等无请求体请求使用空字符串的 SHA256。

请求安全

  • Timestamp 默认有效窗口：300 秒
  • Nonce：每次请求唯一，用于防重放
  • Request-ID：每次业务请求必须提供
  • AccessKey 与应用均必须处于启用状态
  • 启用 IP 白名单后，只允许白名单来源调用
  • 每个 API Key 均受每分钟频率限制

SecretAccessKey 只能放在商户服务端，禁止放入浏览器、小程序或 APP 前端代码。 

X-HC-Access-Key: hc_live_xxx
X-HC-Timestamp: 1782871200
X-HC-Nonce: unique_nonce
X-HC-Request-Id: merchant_request_id
X-HC-Signature: hmac_sha256

查询余额

GET /openapi/v1/account/balance

创建材料

POST /openapi/v1/materials
{
  "sku":"HC-YW-12024",
  "name":"云雾灰岩板",
  "category":"stone_slab",
  "width_mm":1200,
  "height_mm":2400,
  "texture_url":"https://merchant.example.com/material.jpg"
}

空间分析

POST /openapi/v1/scenes/analyze
{ "image_url":"https://merchant.example.com/room.jpg" }

材料渲染

POST /openapi/v1/material-renders
{
  "scene_id":"SCENE_xxx",
  "material_id":"MAT_xxx",
  "surface_ids":["floor_01"],
  "output":{"resolution":"2k"}
}

任务查询

GET /openapi/v1/jobs/{job_id}

绘城智绘 OpenAPI

绘城智绘是绘城智算中的 CAD 空间智能能力， 面向工程图纸理解、空间推理、智能布局、质量审核与设计结果输出。

当前版本：V1 Technical Preview

当前技术预览阶段暂不计费。 正式商业计费规则以后续平台公告与控制台价格为准。

应用能力

调用绘城智绘接口前，需要在“应用管理”中为对应应用开通 cad 能力。 

required_capability = cad

未开通时将返回： 

{
  "code": "APP_CAPABILITY_DENIED",
  "message": "当前应用未开通该能力"
}

支持文件

OpenAPI V1 当前支持：

PDF、图片等格式不属于当前 CAD OpenAPI V1 文件输入范围。

创建 CAD 任务

POST /openapi/v1/cad/jobs

请求类型： multipart/form-data

表单字段： 

file = DXF/DWG 文件

CAD multipart 签名

CAD 上传不能使用整个 multipart HTTP body 计算签名。 PAYLOAD_HASH 必须使用实际上传 CAD 文件的 SHA256。 

FILE_SHA256 =
SHA256(actual_cad_file_bytes)

PAYLOAD_HASH =
FILE_SHA256

同时必须额外发送：

X-HC-Content-SHA256: FILE_SHA256

服务端会重新计算实际上传文件摘要。 Header 摘要与实际文件摘要不一致时，请求会被拒绝。

签名原文示例

POST
/openapi/v1/cad/jobs
1782871200
cad_nonce_xxxxxxxxx
a349bd47f91936dc45f2509f1242bfdd6a89c853880cac82292e6dd657b1fc5d

然后：

X-HC-Signature =
HMAC_SHA256(
  canonical_string,
  SecretKey
)

请求 Header

X-HC-Access-Key: your_access_key
X-HC-Timestamp: 1782871200
X-HC-Nonce: cad_nonce_xxxxxxxxx
X-HC-Request-Id: cad-request-xxxxxxxxx
X-HC-Content-SHA256: file_sha256
X-HC-Signature: calculated_signature

创建成功

HTTP 201
{
  "job_id": "JOB_xxxxxxxxxxxxxxxxxxxx",
  "status": "queued",
  "estimated_cost": 0,
  "cad_task_id": "CAD_xxxxxxxxxxxxxxxxx",
  "billing_mode": "technical_preview_no_charge"
}

查询任务状态

GET /openapi/v1/cad/jobs/{job_id}

此接口只返回公开任务状态，不返回 CAD 内部推理结构。 

{
  "job_id": "JOB_xxx",
  "status": "processing",
  "progress": 50,
  "charged_amount": 0,
  "error": null,
  "created_at": "2026-09-29 16:00:00",
  "started_at": "2026-09-29 16:00:01",
  "finished_at": null
}

获取 CAD 设计结果

GET /openapi/v1/cad/jobs/{job_id}/result

仅当任务状态为 succeeded 时， 返回公开设计结果。

成功结果

{
  "job_id": "JOB_xxx",
  "status": "succeeded",
  "progress": 100,
  "charged_amount": 0,
  "error": null,
  "cad_task_id": "CAD_xxx",
  "design": {
    "ready": true,
    "room_count": 1,
    "layout_count": 1,
    "furniture_count": 2,
    "opening_count": 0
  },
  "quality": {
    "passed": true,
    "geometry_passed": true,
    "layout_ready": true,
    "score": 100,
    "grade": "A"
  },
  "output": {
    "plan": {
      "status": "ok",
      "svg_url": "https://api.zhihuijia-ai.com/runtime/render/..."
    },
    "presentation": {
      "status": "ok",
      "png_url": "https://api.zhihuijia-ai.com/runtime/presentation/...",
      "svg_url": "https://api.zhihuijia-ai.com/runtime/presentation/..."
    }
  }
}

任务状态

状态 说明 结果
queued 已进入任务队列 design / quality / output 为 null
processing 正在处理 design / quality / output 为 null
succeeded 处理完成 返回公开设计结果
failed 任务失败 返回公开错误信息

任务失败

{
  "job_id": "JOB_xxx",
  "status": "failed",
  "progress": 100,
  "charged_amount": 0,
  "error": {
    "code": "CAD_EXECUTION_FAILED",
    "message": "CAD任务处理失败"
  },
  "cad_task_id": null,
  "design": null,
  "quality": null,
  "output": null
}

CAD 内部 Worker、模型、推理、恢复策略和工程诊断信息 不属于公开 API 契约。

常见错误码

错误码 HTTP 说明
AUTH_HEADERS_MISSING 401 缺少 OpenAPI 鉴权请求头
SIGNATURE_EXPIRED 401 请求时间戳已过期
INVALID_ACCESS_KEY 401 AccessKey 不存在或已停用
INVALID_SIGNATURE 401 签名验证失败
IP_NOT_ALLOWED 403 来源 IP 不在白名单
APP_CAPABILITY_DENIED 403 应用未开通 CAD 能力
REPLAY_DETECTED 409 Nonce 已使用
RATE_LIMITED 429 请求频率超过限制
CAD_FILE_REQUIRED 400 未上传 DXF/DWG 文件
CAD_FILE_INVALID 400 上传临时文件无效
CONTENT_SHA256_REQUIRED 401 缺少有效的 X-HC-Content-SHA256
CONTENT_SHA256_MISMATCH 401 上传文件摘要校验失败
CAD_EXECUTION_FAILED - 异步 CAD 任务执行失败

浏览器跨域

绘城智算 OpenAPI 当前允许以下请求头： 

Authorization
Content-Type
X-HC-Access-Key
X-HC-Timestamp
X-HC-Nonce
X-HC-Signature
X-HC-Request-Id
X-HC-Content-SHA256

防重放

每次请求必须生成新的 Nonce。 已认证的 Nonce 会被服务器记录，再次使用将返回： 

HTTP 409
REPLAY_DETECTED

技术预览计费

api_code = cad_design_preview
billing_mode = technical_preview_no_charge
charged_amount = 0

当前仅代表技术预览阶段， 不构成后续正式商业价格承诺。