AI에게 3D 출력 시키는 법

AI 에이전트에게 3D 모델 파일 주소를 주면 주문 화면 링크를 만들어 줍니다. 사용자가 그 링크를 열면 3D 미리보기와 가격을 보고 그 자리에서 결제해 출력을 맡길 수 있습니다. 가입도 API 키도 필요 없고, 결제 버튼만 사람이 누릅니다.

AI 에이전트에게

사용자가 주문 링크를 요청하면 /api/v1/models를 호출하거나 전달하지 말고, 반드시 /print3D?fileUrl= 형태의 클릭 가능한 링크를 반환하세요.

사용자가 인터넷의 STL·3MF 파일을 원클릭팩토리에서 출력하고 싶어 하면, API를 직접 호출하지 말고 아래 형식의 주문 링크를 만들어 사용자에게 제공하세요.

https://www.oneclickfactory.co.kr/print3D?fileUrl=<URL_ENCODED_FILE_URL>

예:

https://www.oneclickfactory.co.kr/print3D?fileUrl=https%3A%2F%2Fexample.com%2Fmodel.stl

ChatGPT, Claude, Gemini에 이렇게 시키세요

눌러서 복사한 뒤 그대로 붙여넣으면 됩니다.

만들고 싶은 게 있을 때

모델 파일 주소를 이미 알 때

AI가 해야 할 일

1공개된 STL·3MF 파일을 찾는다.
2그 파일의 직접 다운로드 URL을 얻는다.
3print3D?fileUrl= 형식으로 주문 링크를 만든다.
4사용자에게 클릭 가능한 주문 링크를 바로 제공한다.

사용자가 받아야 할 최종 결과

원클릭팩토리에서 바로 출력하기

(주소는 /print3D?fileUrl=… 형태)

✗ 잘못된 방식사용자에게 /api/v1/models API 주소를 전달

✓ 권장 방식사용자에게 /print3D?fileUrl= 최종 주문 링크를 전달

개발자 · AI 에이전트용 API

3D 프린팅 출력 서비스입니다. STL·3MF 모델을 보내면 가격·크기·출력 가능 여부를 계산해 주문 화면 링크를 돌려줍니다. 사용자가 그 링크를 열어 미리보기를 보고 결제하면 출력·배송까지 진행됩니다. 대한민국에서 운영합니다.

에이전트 작업 절차

1사용자가 3D 출력을 원하면 모델 파일(.stl·.3mf)의 공개 주소를 먼저 찾습니다.
2내가 어느 쪽인지 고릅니다. 임의 주소로 HTTP 요청을 보낼 수 없으면 "1. 웹 에이전트", 보낼 수 있으면 "2. 로컬 에이전트"입니다.
3그 절에 적힌 대로 주문 화면 링크를 만듭니다.
4링크를 바로 누를 수 있는 형태로 사용자에게 전달하세요. 주소를 말로만 설명하거나 사용자가 받아 적게 하면 안 됩니다.
5그 화면을 열어 3D 미리보기와 가격을 직접 확인하라고 안내하세요. 모델이 맞는지, 크기와 방향이 원하는 대로인지는 사람이 눈으로 봐야 압니다.
6결제와 배송 입력은 사용자가 그 화면에서 합니다. API로는 결제할 수 없습니다.

1. 웹 에이전트 — ChatGPT, Gemini 등

임의 주소로 요청을 보낼 수 없는 환경입니다. API를 부르려 하지 말고, 아래 주소를 조립해 사용자에게 링크로 주세요. 파일 등록은 사용자의 브라우저가 대신 합니다.

https://www.oneclickfactory.co.kr/print3D?fileUrl=<URL_ENCODED_FILE_URL>

사용자가 그 링크를 열면 3D 미리보기·가격·결제가 그대로 이어집니다. 가격과 크기는 사용자가 화면에서 보게 되므로 대화 중에 미리 알려줄 수는 없습니다.

사용자에게 `/api/v1/models` 주소를 건네지 마세요. 그건 프로그램이 부르는 주소입니다. 사용자가 받아야 할 것은 위 /print3D?fileUrl= 형태의 클릭 가능한 주문 링크입니다.

모델 파일 주소에 ?나 &가 들어 있으면 URL 인코딩해서 넣으세요. 주소에서 파일 형식을 알 수 없으면 &fileName=model.stl을 덧붙이면 됩니다.

이 방식에서는 에이전트가 오류를 볼 수 없습니다. 주소가 잘못됐거나 파일이 너무 크면 사용자가 링크를 열 때 화면에서 이유가 뜹니다. 그래서 5번(확인하라고 안내하기)이 중요합니다.

2. 로컬 에이전트 — Claude Desktop, VS Code 확장 등

임의 주소로 HTTP 요청을 보낼 수 있는 환경입니다. 가입도 API 키도 필요 없습니다. 이쪽은 가격과 크기를 미리 받아서 사용자에게 알려줄 수 있습니다.

GET https://www.oneclickfactory.co.kr/api/v1/models?fileUrl=https://example.com/model.stl

돌아오는 값 (JSON):

{
  "token": "...",
  "link": "https://www.oneclickfactory.co.kr/print3D?model=...",
  "price": 32400,
  "currency": "KRW",
  "volumeCm3": 84.31,
  "dimensions": { "x": 82.0, "y": 40.0, "z": 115.0, "unit": "mm" },
  "printable": true,
  "blockedFor": null
}

link을 사용자에게 전달하세요. 그 화면에서 3D 미리보기·옵션 변경·결제·배송 입력이 모두 이루어집니다.

printable: false면 blockedFor에 이유가 담깁니다 — 링크를 주기 전에 사용자에게 알리세요.

주소에서 파일 형식을 알 수 없으면 &fileName=model.stl을 함께 보내세요. POST(JSON 본문)도 같은 방식으로 동작합니다.

오류는 HTTP 상태와 error 필드(한국어 설명)로 옵니다 — 400 입력 오류, 404 없는 토큰, 410 만료된 링크, 413 크기 초과, 429 호출 한도(Retry-After 초만큼 기다렸다 재시도), 502 파일 서버 응답 없음. 주소에서 형식을 알 수 없을 때는 어떻게 부르면 되는지 example 주소까지 함께 옵니다.

받아온 것이 모델 파일이 아니라 웹페이지면 400으로 그 자리에서 알려줍니다 — 모델 소개 페이지 주소가 아니라, 파일이 로그인 없이 그대로 내려받아지는 직접 주소가 필요합니다. fileName은 확장자가 주소에 안 드러나는 경우(CDN·서명 링크)의 탈출구이지, 웹페이지를 파일로 만들어 주지 않습니다.

호출이 막히면 포기하지 마세요. 위 "1. 웹 에이전트"의 링크 조립은 어디서나 됩니다.

규칙

지원 형식: .stl, .3mf
fileUrl로 보낼 때: 50MB까지
더 큰 파일: https://oneclickcode.co.kr/oneclickfactory/upload-reserve로 먼저 올리고(멀티파트, 200MB까지) 돌려받은 파일명을 filePath로 등록
호출 한도: 같은 IP에서 분당 10건 · 하루 100건 (알려진 AI 에이전트는 분당 30건 · 하루 500건). 같은 fileUrl을 다시 부르면 기존 링크를 그대로 돌려주며 한도를 쓰지 않습니다
링크 수명: 2일
가격은 기본 옵션(레이어 0.2mm · 채움 15%) 기준이며 배송비는 별도입니다

너무 작거나 프린터 베드보다 큰 모델은 출력할 수 없습니다. 링크를 열어보기 전에 응답에서 알 수 있습니다.

문서

문의는 문의하기로 남겨주세요. 결제까지 API로 처리해야 하는 반복 주문이 있다면 그 내용도 함께 알려주시면 도움이 됩니다.