BeeMatra · 照片一鍵變無縫 PBR 材質

驗證方式

所有介面都需要在 HTTP Header 中攜帶 Bearer Token，缺失或錯誤一律返回 HTTP 401：

Authorization: Bearer bmk_xxxxxxxxxxxxxxxx

API 金鑰在「個人中心 → API 金鑰」生成，明文僅顯示一次，請妥善保存。每帳號最多 5 把有效金鑰，可隨時吊銷。

⚠️ 開放 API 僅對生效訂閱用戶開放。任務僅能由建立者查詢（查詢他人任務返回 404）。

建立任務

POST https://beematra.net/api/v1/tasks

上傳一張材質照片即可建立生成任務。受理成功即扣 1 積分，並返回 task_id 供後續輪詢。

請求參數

名稱	類型	描述
image	file	素材圖片檔案（multipart 表單），≤20MB，JPEG / PNG / WebP。與 image_url 二選一，同時提供時以 image 為優先
image_url	string	素材圖片的公網 http(s) 位址（JSON Body 方式），≤20MB

請求範例

cURL · multipart 直接上傳圖片（推薦）

curl -X POST https://beematra.net/api/v1/tasks \ -H "Authorization: Bearer bmk_xxxx" \ -F "image=@/path/to/photo.jpg"

cURL · JSON 傳圖片網址

curl -X POST https://beematra.net/api/v1/tasks \ -H "Authorization: Bearer bmk_xxxx" \ -H "Content-Type: application/json" \ -d '{"image_url": "https://example.com/photo.jpg"}'

Python

import requests resp = requests.post( "https://beematra.net/api/v1/tasks", headers={"Authorization": "Bearer bmk_xxxx"}, files={"image": open("photo.jpg", "rb")}, ) print(resp.json())

返回範例

{ "ok": true, "task_id": "W20261020_170000_a1b2c3", "status": "running", "progress": 0, "status_url": "https://beematra.net/api/v1/tasks/W20261020_170000_a1b2c3", "balance": 87 }

▸ 受理成功即扣 1 積分，任務失敗自動全額退回。
▸ 圖片預處理（EXIF 轉正、長邊歸一 1536px）由服務端自動完成。
▸ 僅接受完整圖片——蒙版 / 區域裁切請呼叫方自行預處理後再上傳。

查詢進度

GET https://beematra.net/api/v1/tasks/{task_id}

GET https://beematra.net/api/v1/tasks/?task_id={task_id}

輪詢任務狀態與進度。路徑式與查詢串式兩種地址等價，需攜帶驗證 Header。

返回範例（進行中）

{ "ok": true, "task_id": "W20261020_170000_a1b2c3", "status": "running", "progress": 45, "stage_label": "Generating textures…", "error": null, "note": null, "results": null }

返回範例（已完成——欄位說明見「成果貼圖說明」）

{ "ok": true, "task_id": "W20261020_170000_a1b2c3", "status": "succeeded", "progress": 100, "stage_label": "Completed", "error": null, "note": null, "results": { "albedo": "/uploads/derived/…/seamless_albedo.png", "normal": "/uploads/derived/…/normal.png", "roughness": "/uploads/derived/…/roughness.png", "height": "/uploads/derived/…/height.png", "ao": "/uploads/derived/…/ao.png", "preview_sphere": "/uploads/derived/…/preview_sphere.png", "preview_cube": "/uploads/derived/…/preview_cube.png" } }

名稱	類型	描述
status	string	running / succeeded / failed（失敗任務自動退回積分）
progress	integer	0-100
stage_label	string	目前處理階段的可讀描述（可用於介面展示）
error	string\|null	僅 status=failed 時有值，失敗原因
results	object\|null	僅 status=succeeded 時有值，成果貼圖 URL 集合

▸ 建議每 3-5 秒輪詢一次，status 變為 succeeded 或 failed 後停止（限頻 60 次/分鐘）。
▸ 任務僅能查詢本帳號自己建立的。

查詢餘額

GET https://beematra.net/api/v1/balance

curl https://beematra.net/api/v1/balance \ -H "Authorization: Bearer bmk_xxxx"

查詢該金鑰對應帳號的積分餘額。

成果貼圖說明

成功時 results 返回 PBR 貼圖組（2048px 無縫）與渲染預覽：

欄位	類型	描述
albedo	string	無縫化反照率貼圖（基礎顏色，sRGB）
normal	string	法線貼圖（OpenGL 約定，Y+ 向上，linear）
roughness	string	粗糙度貼圖（linear）
height	string	高度 / 置換貼圖（linear）
ao	string	環境光遮蔽貼圖（linear）
preview_sphere	string	材質球渲染預覽圖
preview_cube	string	材質塊渲染預覽圖

所有 URL 均可直接下載，無需驗證。交付內容與站內「一鍵下載全部」壓縮包完全一致（5 張貼圖 + 2 張預覽）。

錯誤碼

出錯時 HTTP 狀態碼非 200，回應體格式統一為 {"ok": false, "error": "錯誤碼", "message": "說明"}

HTTP	error	描述
401	missing_or_bad_bearer	缺少 Authorization 請求頭或格式錯誤
401	invalid_key	API 金鑰無效或已被吊銷
403	subscription_required	開放 API 需要生效中的訂閱
400	no_image	缺少 image 檔案欄位（或上傳出錯）
400	bad_type	圖片格式不支援，僅支援 JPEG / PNG / WebP
400	too_large	圖片超過 20MB 上限
400	bad_image_url	image_url 不是合法的公網 http(s) 位址
400	image_download_failed	image_url 下載失敗（或超過 20MB）
400	bad_task_id	task_id 缺失或格式不正確
404	task_not_found	任務不存在，或不屬於當前金鑰對應帳號
503	upstream_busy	Execution engine busy (usually near task completion) — simply poll again
429	rate_limited	限頻：任務提交 2 次/分鐘，進度查詢 60 次/分鐘
429	queue_busy	目前排隊任務過多，請稍後再試

積分規則

獲取	新用戶註冊贈送 3 積分。訂閱（Standard / Pro / Ultimate）每月發放 100 / 500 / 1500 積分。加油包即時增加 50 積分。
消耗	Beta 版材質生成任務每次消耗 1 積分，提交時即時扣除；任務失敗自動全額退回。開放 API 與站內共用同一積分池。
有效期	積分自發放之日起 30 天內有效，到期未使用部分自動失效清零。消耗時按「先到期先消耗」（FIFO）規則優先扣減。
查詢	個人中心 → 積分明細：每筆發放、消耗、失效、退回均逐條可查，餘額恆等於所有未過期批次剩餘之和。

開放平台