BeeMatra · Photo to Seamless PBR Materials

Authentication

All endpoints require a Bearer token in the HTTP header. Missing or invalid credentials return HTTP 401:

Authorization: Bearer bmk_xxxxxxxxxxxxxxxx

API keys are generated in Account → API Keys. The plain key is shown only once — store it safely. Up to 5 active keys per account; revoke anytime.

⚠️ The open API is available to active subscribers only. Tasks can only be queried by their owner (other users’ tasks return 404).

Create task

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

Upload a material photo to create a generation task. 1 credit is charged on acceptance; a task_id is returned for polling.

Parameters

Name	Type	Description
image	file	Material image (multipart form), ≤20MB, JPEG / PNG / WebP. Use either image or image_url — image wins when both are provided
image_url	string	Public http(s) URL of the image (JSON body), ≤20MB

Request examples

cURL · multipart upload (recommended)

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

cURL · JSON with image URL

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())

Response

{ "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 credit is charged on acceptance; failed tasks are refunded in full.
▸ Pre-processing (EXIF rotation, long-edge 1536px) is automatic.
▸ Full images only — masks / region crops must be pre-processed by the caller.

Query progress

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

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

Poll task status and progress. Both path-style and query-style addresses are equivalent. Authentication header required.

Response (running)

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

Response (succeeded — see Result textures for the fields)

{ "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" } }

Name	Type	Description
status	string	running / succeeded / failed (failed tasks are auto-refunded)
progress	integer	0-100
stage_label	string	Human-readable stage for UI display
error	string\|null	Failure reason when status=failed
results	object\|null	Texture URL set when status=succeeded

▸ Poll every 3-5 seconds; stop when succeeded/failed (limit 60/min).
▸ You can only query your own tasks.

Query balance

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

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

Returns the credit balance of the key’s account.

Result textures

On success results carries the PBR texture set (2048px seamless) and preview renders:

Field	Type	Description
albedo	string	Seamless albedo (base color, sRGB)
normal	string	Normal map (OpenGL, Y+, linear)
roughness	string	Roughness map (linear)
height	string	Height / displacement map (linear)
ao	string	Ambient occlusion map (linear)
preview_sphere	string	Material sphere render preview
preview_cube	string	Material cube render preview

All URLs are directly downloadable, no authentication. Content is identical to the in-site “download all” bundle (5 textures + 2 previews).

Error codes

Errors return a non-200 HTTP status with {"ok": false, "error": "code", "message": "..."}

HTTP	error	Description
401	missing_or_bad_bearer	Missing/malformed Authorization header
401	invalid_key	API key invalid or revoked
403	subscription_required	Open API requires an active subscription
400	no_image	Missing image field (or upload error)
400	bad_type	Unsupported format — JPEG / PNG / WebP only
400	too_large	Image exceeds the 20MB limit
400	bad_image_url	image_url is not a valid public http(s) address
400	image_download_failed	image_url download failed (or larger than 20MB)
400	bad_task_id	task_id missing or malformed
404	task_not_found	Task not found, or not owned by this key’s account
503	upstream_busy	Execution engine busy (usually near task completion) — simply poll again
429	rate_limited	Rate limit: 2 task submissions / 60 polls per minute
429	queue_busy	Too many queued tasks, retry shortly

Credit rules

Earning	New accounts get 3 free credits. Subscriptions (Standard / Pro / Ultimate) deliver 100 / 500 / 1500 credits monthly. Booster pack adds 50 credits instantly.
Spending	Each Beta material task costs 1 credit, charged on submission; failed tasks are refunded in full. Same pool for the web app and the open API.
Validity	Credits are valid for 30 days from grant; expired credits are cleared automatically. Spending consumes the earliest-expiring batch first (FIFO).
Tracking	Account → Credit ledger: every grant, spend, expiry and refund is logged; balance always equals the sum of unexpired batches.

Open Platform