빠른 시작
API 키 생성부터 시작하세요
이 가이드의 모든 요청에는 API 키가 필요합니다. 키 생성은 1분도 걸리지 않습니다.
API 키 생성하기Meshy REST API를 사용하여 첫 번째 3D 모델을 만드는 네 가지 단계.
1API 키 받기
API 키를 생성하세요 계정 설정에서 — 이 화면 이후에는 다시 볼 수 없으므로 안전한 곳에 저장하세요. 모든 요청은 Authorization 헤더의 Bearer 토큰으로 인증됩니다 — 인증을 참조하세요.
보안 팁: 키를 스크립트에 직접 붙여넣지 말고 환경 변수로 저장하세요: export MESHY_API_KEY="msy_...".
2첫 이미지로 3D 요청하기
키를 내보낸 다음 이미지로 3D로 첫 작업을 만드세요. 텍스트 prompt 또는 여러 사진에서 작업하시나요? 텍스트로 3D 또는 멀티 이미지로 3D를 참조하세요.
키 내보내기
export MESHY_API_KEY="<your-api-key>"
터미널(macOS의 Terminal, Windows의 명령 프롬프트 또는 PowerShell)에서 실행하세요 — 브라우저에서는 실행하지 마세요.
아래의 모든 예제는 이 사진을 사용합니다 — 다른 것을 시도하려면 자신의 image_url을 교체하세요.
요청
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.cn/images/api/quick-start/source-photo.webp"
}'
3작업 상태 확인하기
요청은 즉시 작업 ID를 반환합니다. status가 SUCCEEDED가 될 때까지 동일한 엔드포인트를 폴링하세요 — 아래의 <task_id>를 2단계에서 반환된 ID로 교체하세요.
요청
curl https://api.meshy.ai/openapi/v1/image-to-3d/<task_id> \
-H "Authorization: Bearer ${MESHY_API_KEY}"
응답 — 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을 브라우저 주소창에 직접 붙여넣어 다운로드할 수 있습니다.
다운로드
curl -L "<model_urls.glb from the response above>" -o model.glb
파일은 비엔터프라이즈 플랜에서 3일 동안 보존됩니다 — 에셋 보존을 참조하세요.
모두 합치기
하나의 스크립트로 모든 것을 처리하고 싶으신가요 — 생성, 폴링, 다운로드?
전체 스크립트
import axios from 'axios';
import fs from 'fs';
const headers = { Authorization: `Bearer ${process.env.MESHY_API_KEY}` };
const imageUrl = 'https://docs.meshy.cn/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 →