AI 3D 생성 API — 여러 엔진을 하나의 API로
제품에 AI 3D 생성 기능을 붙이고 싶은데, 엔진 갈아 끼우고 작업 큐 돌리고 결과 내보내는 스택까지 직접 짜자니 부담입니다. 그 일을 PicoBerry가 비동기 API로 대신 처리합니다. text-to-3D와 image-to-3D는 물론, 다듬는 단계와 다운로드할 수 있는 게임 에셋으로 내보내는 것까지 지원합니다.
# 이미지에서 3D 모델 생성
curl -X POST https://api.picoberry.ai/v1/models/from-image \
-H "Authorization: Bearer ***" \
-H "Content-Type: application/json" \
-d '{"imageUrl":"https://.../ref.png","engine":"tripo"}'
내 서비스에 AI 3D 생성을 붙이려면 어떻게 하나요?
PicoBerry 대시보드에서 API 키를 만들어 서버 쪽에 두고, 프롬프트나 이미지 URL에 엔진 선택과 출력 옵션을 실어 /v1 엔드포인트로 보냅니다. 응답으로 태스크 식별자가 오니 그걸로 폴링하거나, 웹훅을 등록해 작업이 끝났을 때 백엔드가 알림을 받게 하면 됩니다. 완료되면 모델을 내려받아 그대로 제품에 붙이면 됩니다.
파이프라인 직접 안 짜도 3D 생성 기능 붙여 출시하세요
모델 엔드포인트 하나만으로는 부족합니다. 제품에 제대로 붙이려면 이런 게 다 필요합니다.
- 업로드 처리
- 엔진 선택
- 작업 상태 추적
- 결과 저장
- 내보내기 포맷
- 사용량 관리
- 제품에 에셋 연결
이걸 PicoBerry가 API 하나로 다 묶어 뒀습니다.
# prompt/image → 3D
POST /v1/models/from-image
{ "imageUrl": "ref.png", "engine": "tripo" }텍스트나 이미지로 3D 뽑기
텍스트 프롬프트나 레퍼런스 이미지를 넣으면 3D 초안이 나옵니다. 이어서 remesh와 retexture, 리깅, 내보내기까지 한자리에서 하니, 업체 여러 곳 오가며 파일 주고받을 일이 없습니다.
# same request, switch engines
{ ..., "engine": "tripo" }
{ ..., "engine": "meshy" }
{ ..., "engine": "hunyuan3d" }엔진은 여럿, 다루는 API는 그대로
요청마다 알맞은 엔진으로 보냅니다. 어떤 프롬프트는 Tripo로, 어떤 건 Meshy로, 또 어떤 건 Hunyuan3D로 갑니다. 그래도 코드에서 인증하고 작업 걸고 결과 받아 내보내는 방식은 언제나 똑같습니다.
# submit → get a task id
{ "taskId": "job_a1b2", "status": "queued" }
# poll/webhook until succeeded처음부터 비동기로 설계
3D 생성은 바로 안 끝납니다. 그래서 실제 프로덕션 큐 환경을 그대로 상정하고 설계했습니다. 작업을 넣고 task ID를 저장한 다음, poll로 확인하거나 webhook을 받다가 결과가 준비되면 다음 단계로 넘어가면 됩니다.
파이프라인을 직접 짜거나, API를 한 번 부르거나
어느 쪽이든 완성된 3D 에셋은 똑같이 나옵니다. 다른 건 큐와 엔진 연결, 저장, 전달을 어디까지 직접 떠안느냐입니다.
API 키 하나 만들면 에셋 다운로드까지
작게 시작하면 됩니다. API 키를 만들고 생성 작업을 넣은 다음, 상태를 확인하다가 완성된 에셋을 유저 플로우나 워크스페이스, 인벤토리처럼 필요한 자리에 연결하세요.
API 키 만들기
PicoBerry 대시보드에서 키를 만드세요. 필요한 범위로만 권한을 좁히고 서버 사이드에 보관하세요. 사용량을 나눠 보고 싶으면 환경이나 툴, 팀별로 키를 따로 두면 됩니다.
작업 넣기
/v1 엔드포인트로 프롬프트나 이미지 URL, 엔진 선택, 출력 옵션을 보냅니다. 응답에 task나 asset 식별자가 바로 담겨 오니, UI는 멈추지 않습니다.
poll로 확인하거나 webhook으로 받기
task ID로 상태를 확인하거나 webhook을 등록해 두세요. webhook이 오면 백엔드에서 사용자에게 알리고, 워크스페이스를 새로고침하고, 자동화 콘텐츠 파이프라인의 다음 단계를 트리거합니다.
완성 에셋 받기
완성된 모델을 가져와 제품에 넘기세요. 웹 뷰어로 보여주거나 프로젝트에 연결하고, 게임 엔진 워크플로우로 보내거나, 나중에 편집하려고 저장해 둬도 됩니다.
개발자 입장에서 만든 기능
에셋을 계속 찍어내야 하는 제품과 팀을 위한 기능입니다. 한 번 보여주고 마는 데모가 아니라, 이런 곳에서 계속 굴러가라고 만들었습니다.
OpenAPI 스펙과 타입 지원 클라이언트
요청과 응답은 OpenAPI 스펙에 맞춰 둡니다. 이것저것 눌러 보며 익힐 땐 Postman에 임포트하고, 프로덕션에 올릴 땐 백엔드 언어에 맞는 타입 클라이언트를 뽑아 쓰면 됩니다.
Webhook으로 알림 받기
서명된 콜백 방식의 webhook을 씁니다. 이걸 쓰면 폴링을 걷어내고 이벤트에 반응할 수 있습니다. 생성이 끝나면 프로젝트 상태를 갱신하고, 사용자에게 알리고, 리뷰를 큐에 넣고, 내보내기를 시작하도록 짜면 됩니다.
AI 에이전트가 쓰는 MCP 서버
PicoBerry MCP 서버로 생성 기능을 AI 코딩 툴이나 에이전트 워크플로우에 연결하세요. 에이전트가 더 큰 앱이나 게임, 툴을 만드는 흐름 속에서 에셋 초안을 직접 요청할 수 있습니다.
사용량과 크레딧 확인
대시보드에서 크레딧 사용량을 확인하세요. 생성 워크플로우를 키우기 전에 개발용과 사내 툴, 고객용 기능, 실험을 따로 떼어 볼 수 있습니다.
API 한 번이면 3D 생성이 붙습니다
서버 쪽에 키를 만들고 첫 작업을 넣으세요. 모델이 준비되면 webhook이 백엔드에 알려 주니, 그때 내려받으면 됩니다.
API 키는 서버 사이드 · 사용량은 대시보드에서 확인
진짜로 돌아가는 게임 에셋 워크플로우
아래 데모를 보면 이 API가 왜 결과 하나 뽑고 끝이 아닌지 알 수 있습니다. 만든 에셋을 실제 씬으로 옮기고, 엔진 워크플로우와 맞물려 돌린 뒤, 게임에 올려놓고 쓸 만한지 판단합니다.
데모 영상 — 만들고 편집한 3D 에셋이 Unity 씬에 자리 잡는 모습. 에셋 생성에서 인게임 검증까지 이어지는 과정을 담았습니다.
초안 빠르게 뽑기
프롬프트나 레퍼런스 이미지로 프롭과 아이템, 캐릭터, 환경 요소를 만듭니다. 고른 결과는 기록으로 남겨 두면 나중에 다시 찾아볼 수 있습니다.
에셋을 게임 씬에 맞춰 보기
데모에서는 생성 이후의 진짜 단계를 짚어 봅니다. 만든 3D 에셋을 Unity 워크플로우에 올려놓고, 스케일과 실루엣, 조명, 마스크, 씬 구성이 맞는지 하나씩 살펴 씬에 쓸 만한지 가늠합니다.
플레이테스트로 루프 마무리
동떨어진 모델 프리뷰나 전시용이 아닙니다. 생성하고 통합해 테스트하는 루프를 더 빨리 돌려, 실제 게임 안에서 에셋이 쓸 만한지 확인하는 게 목표입니다.
직접 돌려보면 이렇습니다
결국 중요한 건 이 API로 제품에서 뭘 할 수 있느냐입니다. 초안을 만들고, 결과를 비교하고, 기록을 남기고, 다음 단계에 쓸 파일을 넘기는 일까지입니다.
여러 갈래로 뽑은 3D 초안을 늘어놓고, 리뷰해 고른 뒤 다듬어 다음 단계로 넘기는 화면.
Quickstart 경로 — 인증하고, 첫 요청을 보내고, 응답을 확인한 다음, 생성 기능을 자체 백엔드 플로우에 붙입니다.
{ "success": true, "data": {
"id": "019f3a39-0db2-…",
"taskStatus": 0,
"type": "model_3d"
} }
# later
{ "modelUrls": { "glb": ".../model.glb" } }비동기 흐름 예시 — 작업을 넣고, 받은 식별자를 저장하고, poll로 확인하거나 완료를 받은 뒤, 생성된 모델 URL을 가져옵니다.
자주 묻는 질문
PicoBerry API는 뭘 하는 건가요?
PicoBerry API는 AI 3D 생성용 비동기 REST API입니다. 백엔드에서 생성 작업을 넣고, 상태를 확인하고, 완료 이벤트를 받고, 생성된 모델 파일을 가져올 수 있습니다. 제품에든 파이프라인에든 붙여 쓰면 됩니다.
API 하나로 여러 생성 엔진을 쓸 수 있나요?
네, 됩니다. 요청은 알맞은 엔진으로 나눠 보내지만, 제품 쪽에서는 PicoBerry API 하나만 상대하면 됩니다. 인증과 작업 추적, 에셋 기록, 내보내기 흐름은 어느 엔진을 쓰든 그대로입니다.
이 API는 게임 전용인가요?
아니요. 게임을 앞세운 건 게임 툴과 3D 에셋 파이프라인이 PicoBerry의 핵심 워크플로우이기 때문입니다. 크리에이터 툴이나 마켓플레이스, 사내 자동화, AI 에이전트, 교육 툴처럼 3D를 다루는 다른 제품에도 같은 API 패턴을 그대로 씁니다.
생성된 에셋을 그대로 최종본으로 쓸 수 있나요?
생성된 에셋은 초안으로 보는 게 안전합니다. 프로토타이핑이나 반복 작업, 리뷰, 다음 단계로 넘기기에 좋습니다. 최종본으로 쓸지는 프로젝트마다 다른데, 토폴로지와 머티리얼, 스케일, 리깅이 맞는지, 콜리전이나 라이선스, 엔진별 요구사항은 없는지 따로 확인해야 합니다.
PicoBerry가 webhook을 지원하나요?
네, 지원합니다. 워크플로우가 비동기라, 생성 작업을 넣으면 식별자가 나오는데, 그걸 보관해 두고 상태를 poll로 확인하거나 webhook으로 완료를 받으면 됩니다.
개발자는 어떻게 시작하나요?
PicoBerry 계정을 만들고, API 사용을 신청한 다음, 첫 호출을 서버 사이드에 붙이면 됩니다. API 키는 클라이언트 코드에 두지 말고, 필요하면 환경이나 제품별로 키를 나눠 두세요.
3D 생성 레이어는 한 번만 만들어 두면 에셋 필요한 곳 어디서든 꺼내 쓰세요
API 호출 하나로 시작하세요. 그다음 생성 기능을 앱과 툴, 에이전트, 게임 에셋 파이프라인에 연결하면 됩니다.
하나의 비동기 API · 엔진을 바꿔도 연동은 그대로