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）。