REST API v1 · Pro

外部 API 参考文档

可从自家系统直接调用 AI 建筑模拟器的建筑方案生成及 PowerPoint・DXF 导出的 REST API（Pro 方案限定）。

概要与基础 URL

所有端点均为 HTTPS 的 JSON API。请以 Content-Type: application/json 发送请求正文，错误会以通用格式（error.code / error.message）返回。

基础 URL

https://realestate-api-297361533323.asia-northeast1.run.app/api/v1

仅导出类端点（/export/*）在成功时返回文件（二进制）。

验证

请将在我的页面「账户设置」标签页 →「外部 API 对接（开发者）」发行的 API 密钥（以 mkr_api_ 开头的字符串），以 Bearer 形式放入 Authorization 请求头发送。

Authorization: Bearer mkr_api_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

API 密钥仅在发行时显示一次。遗失时请重新发行（重新发行后旧密钥立即失效）。
设置「允许的 IP 地址」后，来自其他 IP・CIDR 的请求会返回 403（IP_NOT_ALLOWED）。可通过 GET /me 的 clientIp 确认来源 IP。
请将 API 密钥保存在服务器端，勿嵌入浏览器或应用程序。MCP 用密钥（mkr_live_）无法用于此 API。

速率限制

每位 API 密钥持有者每日最多可使用 200 单位。各端点消耗的单位如下。

端点	消耗单位
GET /me	0
POST /generate-house	20 (+10 includeExterior)
POST /export/pptx, /export/dxf	2
GET /signals/{cityCode}	5
POST /analyze-property-flyer	20

单位于每日 0:00（UTC）重置。超过上限的调用会返回 HTTP 429（DAILY_LIMIT_EXCEEDED）且不会执行。
短时间连续调用限制为每个 API 密钥每分钟 20 次（超过时返回 HTTP 429 RATE_LIMITED・Retry-After: 60）。
此外，为保护整体服务，每个来源 IP 每 15 分钟上限为 100 次请求。
建筑方案生成失败时（GENERATION_FAILED），已消耗的单位会退回。

可通过响应头确认使用情况。

X-RateLimit-Limit: 200
X-RateLimit-Remaining: 180
X-RateLimit-Reset: 1790640000        # Unix time (next 00:00 UTC)
Retry-After: 43200                   # only on 429

确认密钥与使用情况

GET/api/v1/me

返回 API 密钥是否有效、当前的來源 IP、允许的 IP 及当日使用情况，不消耗单位。

Request

curl https://realestate-api-297361533323.asia-northeast1.run.app/api/v1/me \
  -H "Authorization: Bearer $MEKIKI_API_KEY"

Response 200

{
  "plan": "pro",
  "clientIp": "203.0.113.10",
  "allowedIps": ["203.0.113.10", "198.51.100.0/24"],
  "usage": { "used": 20, "limit": 200, "remaining": 180, "resetAt": "2026-09-30T00:00:00.000Z" },
  "costs": { "generateHouse": 20, "exterior": 10, "export": 2 }
}

生成建筑方案

POST/api/v1/generate-house

根据区域与需求，由 AI 生成包含各楼层户型（2D）、设计理念、预估总预算及简易壁量检查的建筑方案（JSON）。

参数	类型	必填	说明
prefecture	string	必填	都道府县（例: 東京都）
municipality	string	必填	市区町村（例: 江戸川区）
district	string	选填	地区・町名（例: 西葛西）
tags	string[]	选填	需求条件（最多 12 项。例: 駐車場1台 / 3階建て / 平屋 / 予算5,000万円以内）
includeExterior	boolean	选填	true 时同时生成外观图（base64 图片）（+10 单位）
termsAccepted	true	必填	同意使用条款（AI 生成物免责与商业使用许可条款）。非 true 时返回 400（TERMS_NOT_ACCEPTED）

Request

curl -X POST https://realestate-api-297361533323.asia-northeast1.run.app/api/v1/generate-house \
  -H "Authorization: Bearer $MEKIKI_API_KEY" \
  -H "Content-Type: application/json" \
  --max-time 600 \
  -d '{
    "prefecture": "東京都",
    "municipality": "江戸川区",
    "tags": ["駐車場1台", "3階建て"],
    "includeExterior": false,
    "termsAccepted": true
  }'

Response 200 (abridged)

{
  "requestId": "3f1c2a9e-7b1d-4c3e-9a51-6f0d2c8e4b77",
  "planSource": "ai",
  "plan": {
    "site": { "area": 80, "streetSide": "south" },
    "building": { "width": 5.46, "depth": 7.28, "floors": 3, "parkingSpaces": 1 },
    "roof": { "type": "flat", "eavesDepth": 0 },
    "floors": [
      {
        "level": 1,
        "rooms": [{ "type": "garage", "x": 0, "y": 0, "width": 2.73, "height": 5.46, "label": "ガレージ" }, "..."],
        "doors": ["..."], "openings": ["..."], "furnitures": ["..."]
      },
      "..."
    ],
    "externalStructures": ["..."]
  },
  "conceptExplanation": "想定総予算：約6,970万円（土地 …）…",
  "budget": { "landCost": 35200000, "buildingCost": 34779000, "total": 69979000, "...": "..." },
  "structuralWarning": ["1階のX方向（間口方向）の壁量が不足しています（存在壁量 14.43m / 必要壁量 18.29m）"],
  "structuralCheck": { "method": "simplified_wall_quantity", "floors": ["..."] }
}

生成约需 1〜3 分钟（含外观再加约 30 秒）。请将客户端超时设置为约 10 分钟。
坐标与尺寸单位为米，对齐 910mm 模数（0.91m 的倍数）。原点为从道路侧看建筑的左前角。
includeExterior: true 时，响应会加入 exterior（imageBase64・mimeType）。
生成的方案也会保存到我的页面的生成记录（requestId 即记录 ID）。

PowerPoint / DXF 导出

POST/api/v1/export/pptx

POST/api/v1/export/dxf

发送 generate-house 返回的 plan，即可获得可编辑的 PowerPoint（.pptx）或 CAD 用 DXF（.dxf）。

Request (generate → DXF)

# 1) Generate a plan and keep only { plan, location }
curl -s -X POST https://realestate-api-297361533323.asia-northeast1.run.app/api/v1/generate-house \
  -H "Authorization: Bearer $MEKIKI_API_KEY" -H "Content-Type: application/json" \
  -d '{"prefecture":"東京都","municipality":"江戸川区","termsAccepted":true}' \
  | jq '{plan: .plan, location: "東京都江戸川区"}' > plan.json

# 2) Export it as DXF (or /export/pptx)
curl -X POST https://realestate-api-297361533323.asia-northeast1.run.app/api/v1/export/dxf \
  -H "Authorization: Bearer $MEKIKI_API_KEY" -H "Content-Type: application/json" \
  --data @plan.json -o floor-plan.dxf

PPTX: 每层一张幻灯片，房间・家具・门窗均为独立图形，页脚含公司名称・联系方式与免责声明。
DXF: R12 格式・单位 mm・日文为 Shift_JIS。墙・轴线・门窗・房间名・尺寸分图层导出，图框含公司名称与免责声明。
公司名称与联系方式取自我的页面的白标设置（未设置时为物件目利研究的标示）。

先行信号与地方政府公开信息

GET/api/v1/signals/{cityCode}

指定 5 位市区町村代码后，返回各町丁的先行信号差距指数（偏差值、等级 S–C）、区域特性（areaRegime），以及地方政府的再开发、补助金与灾害信息，均附来源 URL、确认日与免责声明。

Request

curl "https://realestate-api-297361533323.asia-northeast1.run.app/api/v1/signals/13122?wait=25" \
  -H "Authorization: Bearer $MEKIKI_API_KEY"

Response 200 (excerpt)

{
  "cityCode": "13122",
  "municipalityName": "葛飾区",
  "towns": [
    {
      "townName": "新小岩",
      "momentumDeviation": 21.2, "rank": "C", "gapZScore": -2.88,
      "zPop": -0.94, "zPrice": 1.94, "reliability": "normal",
      "regime": "REDEVELOPMENT_DRIVEN",
      "linkedIntel": [{ "category": "REDEVELOPMENT", "title": "新小岩駅南口地区第一種市街地再開発事業",
        "sourceUrl": "https://www.city.katsushika.lg.jp/...", "verifiedAt": "2026-10-18T05:06:09.013Z", "match": "direct" }],
      "sources": [{ "source_url": "https://www.e-stat.go.jp/dbview?sid=8003006792", "source_title": "...", "verified_at": "..." }]
    }
  ],
  "intel": { "status": "ready", "origin": "registered", "items": [{ "category": "SUBSIDY", "sourceUrl": "https://...", "verifiedAt": "..." }] },
  "disclaimer": "...",
  "cache": { "status": "persistent", "cachedAt": "...", "expiresAt": "..." }
}

町丁排名（差距指数）数秒内返回。地方政府信息（intel）尚未生成时 intel.status 为 "pending"，请加上 ?wait=25（最多等待 25 秒）重新请求，直到变为 "ready"。结果缓存 7 天。
此为町丁间的统计相对比较，不含个别物件价格或未来价格。显示或再分发时请一并标示 disclaimer 与各来源。
地方政府信息：已登记的市区町村使用登记 URL，其他则自动搜索官方网站（*.lg.jp / city.*.jp 等），仅使用返回 200 且正文含市区町村名的页面（intel.origin = discovered）。找不到时 intel.status = "unavailable"（仍返回差距指数）。

错误

发生错误时，会连同 HTTP 状态码返回以下格式的 JSON。

Response 429

{
  "error": {
    "code": "DAILY_LIMIT_EXCEEDED",
    "message": "Daily API limit reached (195/200 units; this call needs 20). Resets at 2026-09-30T00:00:00.000Z"
  }
}

HTTP	code	说明
400	INVALID_PARAMETERS / INVALID_PLAN	参数或 plan 格式不正确
400	TERMS_NOT_ACCEPTED	未指定 termsAccepted: true
401	INVALID_API_KEY	无 API 密钥・格式错误・无效（已停用）
403	PLAN_NOT_ELIGIBLE	密钥持有者非 Pro 方案
403	IP_NOT_ALLOWED	來源 IP 不在允许列表中
429	RATE_LIMITED	超过每分钟 20 次的上限
429	DAILY_LIMIT_EXCEEDED	当日可用单位不足（UTC 0:00 重置）
400	INVALID_CITY_CODE	市区町村代码不是 5 位数字
404	NO_DATA	公开统计不足，无法计算（已退还使用单位）
500	GENERATION_FAILED	建筑方案生成失败（单位已退回）
502	UPSTREAM_ERROR	获取统计或地方政府网站失败（已退还使用单位，请稍后重试）
503	USAGE_UNAVAILABLE	暂时无法确认使用情况（请稍后重试）

生成物为 AI 的概念设计，不保证壁量及尺寸的准确性。Pro 方案的生成物可用于自家客户提案等商业用途。详情请参阅使用条款（第6条之4）。