積木 → 未來建築 → 3D 模型

1. 一鍵流程 — POST /api/pipeline/blocks-to-3d

curl -X POST "https://techart.tronk.tw/face_lineart/api/pipeline/blocks-to-3d" \
  -F "image=@./blocks.jpg" \
  -F "type=AI_Factory" \
  -F "id=3" \
  -F "userID=user-001" \
  -F "gemini_model=gpt-image-2" \
  -F "skip_3d=1"

立即回應（圖片尚未生成，所以 building_ai_id 為 null）：

{
  "success": true,
  "job_id": "88eb0f2641e642cf9ac11624950f7e38",
  "building_ai_id": null,
  "userID": "user-001",
  "blocks_image": "/uploads/blocks_input_..."
}

2. 輪詢生圖 Job — GET /api/pipeline/blocks-to-3d/job/<job_id>

使用步驟 1 回傳的 job_id，每 2 秒查詢一次。Job 約保留 1 小時。

curl "https://techart.tronk.tw/face_lineart/api/pipeline/blocks-to-3d/job/88eb0f2641e642cf9ac11624950f7e38"

# status=done 回應重點
{
  "success": true,
  "job": {
    "status": "done",
    "stage": "done",
    "building_ai_id": 2242,
    "building_image": "/uploads/blocks_building_....jpg",
    "userID": "user-001",
    "data": {
      "building_ai_id": 2242,
      "building_image": "/uploads/blocks_building_....jpg",
      "userID": "user-001",
      "skip_3d": true
    }
  }
}

3. 獨立審查 — POST /api/moderation/analyze

僅審查與積木分析，不觸發生圖。頁面下方有測試區塊。

curl -X POST "https://techart.tronk.tw/face_lineart/api/moderation/analyze" \
  -F "image=@./blocks.jpg" \
  -F "moderation_provider=openai"

4. 輪詢 3D 任務 — GET /api/tripo3d/task/<tripo_task_id>

同 Tripo3D API，每 3 秒輪詢直到 status 為 success。

5. 服務狀態 — GET /api/pipeline/blocks-to-3d/status

{
  "success": true,
  "online": true,
  "gemini": { "online": true, "default_model": "gemini-3.1-flash-image" },
  "openai": { "online": true, "default_model": "gpt-image-2" },
  "tripo3d": { "online": true, "default_model": "v3.0-20250812" }
}

6. 更新 Prompt 範本 / Description

可在頁面上方直接編輯並儲存；也可呼叫 API。

# 更新共用範本（必須含 {description}）
curl -X PUT "https://techart.tronk.tw/face_lineart/api/buildings/prompt-template" \
  -H "Content-Type: application/json" \
  -d "{\"prompt_template\":\"將第一張圖轉成第二張圖風格...\\n{description}\"}"

# 更新某 type/id 的 description
curl -X PUT "https://techart.tronk.tw/face_lineart/api/buildings/styles/AI_Factory/1" \
  -H "Content-Type: application/json" \
  -d "{\"description\":\"智慧製造與 AI 工廠風格...\"}"

7. 查詢積木轉建築圖片 — GET /api/images/blocks-to-3d

只回傳 source=blocks-to-3d 的圖片，可用 id 或日期篩選。可在上方 測試區塊 直接試用。

積木轉建築的圖片存在專屬資料表，id 是不與 gemini 生圖、上傳圖片共用的獨立連號序號。

# 依 id
curl "https://techart.tronk.tw/face_lineart/api/images/blocks-to-3d?id=120"

# 依日期
curl "https://techart.tronk.tw/face_lineart/api/images/blocks-to-3d?date=2026-07-10"

# 日期區間
curl "https://techart.tronk.tw/face_lineart/api/images/blocks-to-3d?date_from=2026-07-01&date_to=2026-07-10"

8. 發送建築圖 — POST /api/images/blocks-to-3d/build_send

傳入生圖完成後取得的 building_ai_id。只有經過此 API 發送的圖片才會出現在 latest；重複發送同一 ID 不會建立重複紀錄。

curl -X POST "https://techart.tronk.tw/face_lineart/api/images/blocks-to-3d/build_send" \
  -H "Content-Type: application/json" \
  -d "{\"building_ai_id\": 1421}"

9. 最新已發送圖片 ID — GET /api/images/blocks-to-3d/latest

回傳最近一次經 build_send 發送的圖片；尚未發送任何圖片時 id 為 null。

curl "https://techart.tronk.tw/face_lineart/api/images/blocks-to-3d/latest"

# 回應範例
{
  "success": true,
  "data": {
    "id": 1421,
    "building_ai_id": 1421,
    "userID": "user-001",
    "source": "blocks-to-3d",
    "created_at": "2026-07-10 00:58:39",
    "url": "https://techart.tronk.tw/face_lineart/uploads/blocks_building_....jpg",
    "relative_url": "/uploads/blocks_building_....jpg",
    "filename": "blocks_building_....jpg"
  }
}

10. Latest 呼叫記錄 — GET /api/images/blocks-to-3d/latest/logs

查詢誰呼叫過 latest，含來源 IP、客戶端、回傳的 ID 與耗時。記錄保留 30 天，時間為 UTC。可在上方 呼叫記錄區塊 直接檢視。

curl "https://techart.tronk.tw/face_lineart/api/images/blocks-to-3d/latest/logs?date=2026-07-29&limit=50"

# 回應範例
{
  "success": true,
  "data": {
    "total": 128,
    "retention_days": 30,
    "top_clients": [
      { "client_ip": "203.0.113.5", "user_agent": "UnityPlayer/2022.3", "call_count": 96, "last_called_at": "2026-07-29 12:31:02" }
    ],
    "logs": [
      {
        "id": 128,
        "called_at": "2026-07-29 12:31:02",
        "client_ip": "203.0.113.5",
        "forwarded_for": "203.0.113.5",
        "user_agent": "UnityPlayer/2022.3",
        "referer": "",
        "query_string": "",
        "status_code": 200,
        "returned_id": 60,
        "returned_user_id": "user-001",
        "duration_ms": 3,
        "error": null
      }
    ]
  }
}