생성

이미지 → 3D

POST/v1/models/from-image

어떤 이미지든 — 여러분이 직접 생성한 것도 포함 — 텍스처가 입혀진 메시로 변환합니다.

비동기 id 반환 — 폴링 또는 웹훅일반적 ~60–120s비용 ≈60–80 credits

imageUrl을 전달하거나(JSON) 파일을 업로드하세요(multipart image). 둘 중 정확히 하나가 필요합니다. 더 정밀한 형상을 원하면 같은 대상의 2~4개 뷰를 imageUrls(또는 multipart images 파트)로 보내세요 — 멀티뷰를 참고하세요.

파라미터

파라미터설명
imageUrl조건부
string		소스 이미지 URL(http/https). multipart image 파일을 보내지 않는 한 필수입니다. PicoBerry가 생성한 이미지의 files.image URL도 여기에 사용할 수 있습니다.
imageUrls조건부
string[]		멀티뷰 — 한 대상의 2~4개 뷰, [front, left, back, right] 순서. 로컬 파일은 multipart images 파트에 넣습니다. 멀티뷰는 tripo*, meshy6, hunyuan-3.x에서만 지원됩니다 — 아래 참고.
engine선택
string		사용할 3D 엔진 — 예: tripo, hunyuan-3.1. 생략하면 기본값. 목록: GET /v1/models?category=3d.
polycount선택
integer		목표 폴리곤 수, 100–2,000,000, 모델의 범위로 제한됩니다.
texture선택기본 true
boolean		PBR 텍스처를 생성합니다. 더 빠른 무텍스처 메시를 원하면 false로 설정하세요.
이미지 소스는 정확히 하나 imageUrl, imageUrls, multipart image, multipart images 파트 중 하나를 보내세요. multipart 파일이 URL 필드보다 우선합니다.

요청

multipart 업로드
curl -X POST https://api.picoberry.ai/v1/models/from-image \
  -H "Authorization: Bearer pb_live_xxx" \
  -F "engine=tripo" -F "image=@./ref.png"
requests.post("https://api.picoberry.ai/v1/models/from-image", headers=headers,
    data={"engine": "tripo"}, files={"image": open("ref.png", "rb")})
const fd = new FormData();
fd.append("engine", "tripo"); fd.append("image", fileBlob, "ref.png");
await fetch(`${BASE}/v1/models/from-image`, { method: "POST", headers, body: fd });
이미지 입력 단일 프레임 png, jpeg, webp, 또는 gif, 최대 20 MB. URL은 서버 측에서 가져오므로 공개적으로 접근 가능해야 합니다.

응답

응답 · 200
{ "success": true, "data": { "id": "019…", "taskStatus": 0, "type": "model_3d" } }

호출은 즉시 반환됩니다. GET /v1/assets/{id}를 taskStatus가 2가 될 때까지 폴링하면, 성공 시 files.model이 서명된 GLB가 됩니다. 그런 다음 같은 id를 리메시, 텍스처, 오토리깅으로 정제하세요.

멀티뷰

같은 대상의 2~4개 뷰를 보내면 더 정밀한 하나의 메시가 생성됩니다. 순서는 [front, left, back, right](정면 먼저) — 호스팅된 URL은 imageUrls, 로컬 파일은 multipart images 파트로 전달합니다. 크레딧은 단일 이미지 생성과 동일합니다(뷰당 배수 없음).

2~4개 뷰
curl -X POST https://api.picoberry.ai/v1/models/from-image \
  -H "Content-Type: application/json" \
  -d '{"engine":"meshy6","imageUrls":["https://…/front.png","https://…/left.png"]}'
requests.post("https://api.picoberry.ai/v1/models/from-image", headers=headers,
    json={"engine": "meshy6", "imageUrls": ["https://…/front.png", "https://…/left.png"]})
await fetch(`${BASE}/v1/models/from-image`, { method: "POST",
  headers: { ...headers, "Content-Type": "application/json" },
  body: JSON.stringify({ engine: "meshy6", imageUrls: [front, left] }) });
지원 엔진 tripo, tripo-v3.0, tripo-v3.1, tripo-v3.1-ultra, tripo-game-ready, meshy6, hunyuan-3.0, hunyuan-3.1, hunyuan-3.1-lite. 그 외 엔진은 400을 반환합니다.