马上开始
功能开放平台个人中心登录

开放平台

以 API 方式接入 Beematra 材质生成能力。

获取 API Key
认证方式 创建任务 查询进度 查询余额 成果贴图说明 错误码 积分规则

认证方式

所有接口（创建任务、查询进度、查询余额）都需要在 HTTP Header 中携带认证头，缺失或错误一律返回 HTTP 401：

Authorization: Bearer bmk_xxxxxxxxxxxxxxxx

API Key 在个人中心 → API 密钥生成，明文仅显示一次，请妥善保存。每账号最多 5 把有效密钥，可在个人中心随时吊销。

⚠️ 开放 API 仅对订阅会员开放：会员有效期内可创建与使用 Key，到期后所有调用返回 HTTP 403。查询接口同样需要认证，且只能查询本账号自己创建的任务（查他人任务返回 404）。

创建任务

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

上传一张材质照片，提交材质生成任务。受理成功即扣 1 积分，返回 task_id 供后续查询。

请求参数

参数类型描述
imagefile素材图片文件（multipart 表单），≤20MB，JPEG / PNG / WebP。与 image_url 二选一，同时提供时优先 image
image_urlstring素材图片的公网 http(s) 地址（JSON Body 方式），≤20MB。与 image 二选一

请求示例

cURL · 方式一：multipart 直接上传图片（推荐）

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

cURL · 方式二：JSON 传图片 URL

curl -X POST https://beematra.com/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.com/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.com/api/v1/tasks/W20261020_170000_a1b2c3", "balance": 87 }

返回参数

参数类型描述
okboolean请求是否受理成功（true / false）
task_idstring任务唯一标识（W + 日期_时间_随机串），查询进度、获取成果均凭此 ID
statusstring任务状态，创建成功时固定为 running
progressinteger进度百分比，创建成功时为 0（实时进度用查询进度接口轮询）
status_urlstring查询进度接口的完整 URL（路径式写法），可直接 GET 轮询（同样需带认证头）
balanceinteger扣费后的积分余额

▸ 受理成功即扣 1 积分，任务失败自动全额退回。
▸ 图片预处理（EXIF 转正、长边归一 1536px）由服务端自动完成。
▸ API 仅接受完整图片，蒙版 / 区域裁切请调用方自行预处理后再上传。

查询进度

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

轮询任务状态与处理进度。两种地址格式等价，任选其一：路径式 /api/v1/tasks/W20261020_152956_6f5ac1 或查询串式 /api/v1/tasks/?task_id=W20261020_152956_6f5ac1。查询请求同样必须携带认证头，否则返回 401。

请求参数

参数类型描述
task_idstring创建任务时返回的任务标识。路径式写在 URL 路径中，查询串式写在 ?task_id= 参数中

请求示例

cURL

curl "https://beematra.com/api/v1/tasks/?task_id=W20261020_170000_a1b2c3" \ -H "Authorization: Bearer bmk_xxxx"

Python

import requests headers = {"Authorization": "Bearer bmk_xxxx"} resp = requests.get( "https://beematra.com/api/v1/tasks/?task_id=W20261020_170000_a1b2c3", headers=headers, ) print(resp.json())

返回示例（运行中）

{ "ok": true, "task_id": "W20261020_170000_a1b2c3", "status": "running", "progress": 45, "stage_label": "贴图生成中", "error": null, "note": null, "results": null }

返回示例（已完成，results 字段说明见「成果贴图说明」）

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

返回参数

参数类型描述
okboolean请求是否成功（true / false）
task_idstring任务唯一标识，与创建时返回一致
statusstring任务状态：running 处理中 / succeeded 已完成 / failed 已失败（失败时积分自动退回）
progressinteger进度 0-100：30% = 材质识别完成，50% = 参数装配完成，52-90% = 贴图派生中，100% = 渲染完成
stage_labelstring当前处理阶段的可读描述（材质识别中 / 参数生成中 / 贴图生成中 / 任务完成 / 任务失败），可用于界面展示
errorstring|null仅 status=failed 时有值，失败原因
notestring|null仅 status=failed 时有值，附加说明（如「积分已自动退回」）
resultsobject|null仅 status=succeeded 时有值，成果贴图 URL 集合，字段说明见「成果贴图说明」

▸ 建议每 3-5 秒轮询一次，status 变为 succeeded 或 failed 后停止轮询（限频 60 次/分钟）。
▸ 任务只能查询本账号自己创建的，查他人任务返回 404。

查询余额

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

查询当前 API Key 对应账号的积分余额与会员有效期，同样需携带认证头。

请求参数

无（仅认证头）。

请求示例

cURL

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

Python

import requests resp = requests.get( "https://beematra.com/api/v1/balance", headers={"Authorization": "Bearer bmk_xxxx"}, ) print(resp.json())

返回示例

{ "ok": true, "balance": 87, "vip_until": "2026-11-20 17:43:52" }

返回参数

参数类型描述
okboolean请求是否成功（true / false）
balanceinteger当前积分余额
vip_untilstring订阅会员有效期（会员到期后 API 调用返回 403）

成果贴图说明

任务成功（status=succeeded）后 results 返回 PBR 贴图组（2048px 无缝）与渲染预览的下载 URL，各字段说明：

字段类型描述
albedostring无缝化反照率贴图（基础颜色，sRGB）
normalstring法线贴图（OpenGL 约定，Y+ 向上，linear）
roughnessstring粗糙度贴图（linear）
heightstring高度 / 置换贴图（linear）
aostring环境光遮蔽贴图（linear）
preview_spherestring材质球渲染预览图
preview_cubestring材质块渲染预览图

所有 URL 均可直接下载，无需认证。API 交付内容与站内「一键下载全部」压缩包完全一致（5 张贴图 + 2 张预览）。任务失败时 error 给出原因，对应积分已自动退回。

错误码

出错时 HTTP 状态码非 200，响应体格式统一为 {"ok": false, "error": "错误码", "message": "说明"}。

HTTPerror描述
401missing_or_bad_bearer缺少 Authorization 请求头或格式错误（所有接口均需认证头）
401invalid_keyAPI Key 无效或已被吊销
403vip_required非订阅会员或会员已到期
402insufficient_credits积分余额不足（响应体含当前 balance），请先充值
400no_image缺少 image 文件字段（或上传出错）
400bad_type图片格式不支持，仅支持 JPEG / PNG / WebP
400too_large图片超过 20MB 上限
400bad_image_urlimage_url 不是合法公网 http(s) 地址，或指向内网
400image_download_failedimage_url 下载失败（或超过 20MB）
400bad_task_id查询时 task_id 缺失或格式不正确
404task_not_found任务不存在，或不属于当前 API Key 对应账号
429rate_limited触发限频：任务提交 2 次/分钟，进度查询 60 次/分钟
429queue_busy当前排队任务过多，请稍后再试

积分规则

Beematra 以「积分」计量能力消耗（Beta 公测期，2026-10-13 起执行）。英文版产品发布后，同一体系将统一以 token 表述，规则不变。

获取新用户注册赠送 5 积分；充值套餐即将上线（见 套餐与充值）。
消耗Beta 版材质生成任务每次消耗 1 积分，提交任务时即时扣除；任务失败自动全额退回。开放 API 同一口径：1 次任务调用 = 1 积分，与站内共享同一积分池与有效期规则。
有效期积分自发放之日起 30 天内有效，到期未使用部分自动失效清零。消耗时按「先到期先消耗」（FIFO）规则优先扣减最早到期的积分。
查询个人中心 → 财务信息 → 积分明细：每笔发放（含到期日）、消耗、失效、退回均逐条可查，余额恒等于所有未过期批次剩余之和。
使用前提生成功能需登录后使用；积分余额不足时无法提交任务，需充值后继续。