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) 주소(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	이미지 형식 미지원——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) 차감.
조회	계정 → 크레딧 내역: 지급·소비·만료·환불 모두 기록되며, 잔액은 미만료 배치의 합계와 항상 일치합니다.

오픈 플랫폼

인증