BeeMatra · 写真からシームレスPBRマテリアルを一瞬で

認証

すべてのエンドポイントには HTTP ヘッダーで Bearer トークンが必要です。欠落・不正な場合は 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 と image_url のどちらか一方、両方時は image 優先
image_url	string	素材画像の公開 http(s) URL（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 で画像 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())

レスポンス例

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

タスクのステータスと進捗をポーリング。パス式・クエリ式どちらも等価です。認証ヘッダーが必要です。

レスポンス例（実行中）

{ "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	UI 表示用の現在ステージの説明
error	string\|null	status=failed 時のみ値あり、失敗理由
results	object\|null	status=succeeded 時のみ値あり、成果テクスチャ URL セット

▸ 3〜5 秒ごとのポーリングを推奨。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	画像形式 non対応——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 回 = 1 クレジット、投稿時に消費。失敗時は全額自動返金。オープン API も同じプールを共有。
有効期限	クレジットの有効期限は付与から 30 日間。期限切れ分は自動消去。消費は期限切れが早いものから（FIFO）。
照会	アカウント → クレジット明細：付与・消費・失効・返金のすべてが記録され、残高は未失効バッチの合計と一致します。

オープンプラットフォーム

認証