빠른 시작
먼저 API 키를 생성하세요
이 가이드의 모든 요청에는 API 키가 필요합니다. 키 생성은 몇 초면 충분합니다.
API 키 생성하기Meshy REST API를 사용해 첫 3D 모델을 만드는 네 단계입니다.
1API 키 발급받기
Developer Platform의 API Keys 페이지에서 API 키를 생성하세요. 이 화면을 벗어나면 다시 확인할 수 없으니 안전한 곳에 보관해야 합니다. 모든 요청은 Authorization 헤더에 Bearer 토큰을 담아 인증합니다 — 인증 문서를 참고하세요.
API 키 생성 및 관리는 유료 플랜에서만 가능합니다. 무료 계정에는 Playground 테스트용 전용 내장 키가 제공되지만, 직접 키를 생성하거나 관리할 수는 없습니다.
보안 팁: 키를 스크립트에 직접 붙여넣지 말고, 대신 환경 변수로 저장하세요: export MESHY_API_KEY="msy_...".
2첫 번째 Image-to-3D 요청 보내기
키를 export한 다음 이미지로 3D로 첫 번째 작업을 생성하세요. 텍스트 prompt나 여러 장의 사진으로 작업하고 싶으신가요? 텍스트로 3D 또는 멀티 이미지로 3D를 참고하세요.
Export your key
export MESHY_API_KEY="<your-api-key>"
브라우저가 아닌 터미널(macOS의 Terminal, Windows의 명령 프롬프트 또는 PowerShell)에서 실행하세요.
아래의 모든 예시는 이 사진을 사용합니다 — 다른 것을 시도하려면 image_url을 원하는 이미지로 바꾸세요.
Request
curl https://api.meshy.ai/openapi/v1/image-to-3d \
-X POST \
-H "Authorization: Bearer ${MESHY_API_KEY}" \
-H "Content-Type: application/json" \
-d '{
"image_url": "https://docs.meshy.ai/images/api/quick-start/source-photo.webp"
}'
3작업 상태 확인하기
요청을 보내면 즉시 작업 ID가 반환됩니다. status가 SUCCEEDED가 될 때까지 같은 엔드포인트를 폴링하세요 — 아래 <task_id>를 2단계에서 반환받은 ID로 바꾸세요.
Request
curl https://api.meshy.ai/openapi/v1/image-to-3d/<task_id> \
-H "Authorization: Bearer ${MESHY_API_KEY}"
Response — SUCCEEDED
{
"id": "018a210d-8ba4-705c-b111-1f1776f7f578",
"status": "SUCCEEDED",
"progress": 100,
"model_urls": {
"glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***",
"fbx": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.fbx?Expires=***"
},
"thumbnail_url": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***",
"task_error": {
"message": ""
}
}
4모델 다운로드하기
위 응답의 model_urls에서 모델을 가져오세요. 각 포맷(GLB, FBX, OBJ, USDZ, STL)은 서명되고 유효기간이 있는 URL입니다 — 명령줄 대신 브라우저 주소창에 URL을 직접 붙여넣어 다운로드할 수도 있습니다.
Download
curl -L "<model_urls.glb from the response above>" -o model.glb
Enterprise 플랜이 아닌 경우 파일은 3일간 보관됩니다 — 에셋 보존을 참고하세요.
전체 과정 한 번에 처리하기
생성, 폴링, 다운로드까지 한 번에 처리하는 스크립트를 원하시나요?
Full script
import axios from 'axios';
import fs from 'fs';
const headers = { Authorization: `Bearer ${process.env.MESHY_API_KEY}` };
const imageUrl = 'https://docs.meshy.ai/images/api/quick-start/source-photo.webp';
// 1. Create the task
const { data: created } = await axios.post(
'https://api.meshy.ai/openapi/v1/image-to-3d',
{ image_url: imageUrl },
{ headers },
);
const taskId = created.result;
// 2. Poll until it finishes
let task;
while (true) {
const { data } = await axios.get(`https://api.meshy.ai/openapi/v1/image-to-3d/${taskId}`, { headers });
task = data;
if (task.status === 'SUCCEEDED' || task.status === 'FAILED') break;
await new Promise((resolve) => setTimeout(resolve, 5000));
}
// 3. Download the result (only if the task succeeded)
if (task.status !== 'SUCCEEDED') {
throw new Error(`Task ${task.status}: ${task.task_error?.message || 'unknown error'}`);
}
const { data: model } = await axios.get(task.model_urls.glb, { responseType: 'arraybuffer' });
fs.writeFileSync('model.glb', model);
console.log('Saved model.glb');
일반적인 워크플로 살펴보기
게임용 캐릭터
휴머노이드 메시에 스켈레톤을 리깅하여 Unity나 Unreal에서 바로 애니메이션할 수 있도록 준비하세요.
Learn more →로우폴리 에셋
이미지로 3D에서 model_type을 lowpoly로 설정해 깔끔한 게임용 메시를 만드세요.
3D 프린트 모델
완성된 모델을 멀티컬러 3MF 파일로 변환해 바로 슬라이싱하고 프린트할 수 있도록 준비하세요.
Learn more →