빠른 시작
API 키를 생성하는 것부터 시작하세요
이 가이드의 모든 요청에는 API 키가 필요합니다. 키 생성은 몇 초면 끝납니다.
API 키 생성하기API 키를 생성하는 것부터 모델을 다운로드하는 것까지, 네 단계로 Meshy REST API를 사용해 첫 3D 모델을 만들어 보세요.
1API 키 받기
Developer Platform의 API Keys 페이지에서 API 키를 생성하세요. 해당 화면을 벗어나면 키를 다시 확인할 수 없으므로 안전한 곳에 보관하세요. 모든 요청에서 Authorization 헤더에 Bearer 토큰으로 키를 전송하세요. 인증을 참고하세요.
API 키를 생성하고 관리하려면 유료 플랜이 필요합니다. Free 플랜에서는 직접 키를 생성할 수 없으며, Playground는 테스트를 위해 내장된 키를 사용합니다.

키를 스크립트에 넣지 마세요. 다음 단계에서 보여주는 것처럼 환경 변수에 저장하세요.
2이미지로 3D 작업 생성하기
이미지로 3D에 이미지를 전송하세요. 텍스트 prompt나 여러 장의 사진으로 시작하려면 대신 텍스트로 3D나 멀티 이미지로 3D를 사용하세요.
먼저 환경 변수에 키를 저장하세요:
Export your key
export MESHY_API_KEY="<your-api-key>"
이 명령은 브라우저가 아니라 터미널(macOS의 Terminal, Windows의 Command Prompt 또는 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작업 상태 확인하기
작업은 백그라운드에서 실행되며 보통 몇 분 정도 걸립니다. status가 SUCCEEDED, FAILED, CANCELED 중 하나가 될 때까지 같은 엔드포인트에서 작업을 조회하세요. 다음 요청에서 <task_id>를 2단계에서 반환된 ID로 바꾸세요. 요청 사이에는 Retry-After 헤더에 담긴 초만큼 대기하세요.
일반적인 처리 시간과 포기하기까지 기다려야 할 시간은 작업 수명 주기를 참고하세요.
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": null
}
작업이 실패하면 status가 FAILED가 되며, task_error에 그 이유가 담깁니다. 입력을 수정하거나 새 작업을 생성하세요. 오류를 참고하세요.
4모델 다운로드하기
파일은 앞선 응답의 model_urls에 들어 있습니다. 각 형식(GLB, FBX, OBJ, USDZ, STL)에는 제한된 시간 동안만 유효한 서명된 URL이 있습니다. 브라우저에 URL을 붙여넣어 파일을 다운로드할 수도 있습니다.
Download
curl -L "<model_urls.glb from the response above>" -o model.glb

Enterprise를 제외한 모든 플랜에서 Meshy는 파일을 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, timeout: 60_000 },
);
const taskId = created.result;
// 2. Poll until it finishes, for up to 60 minutes
const deadline = Date.now() + 60 * 60 * 1000;
let task;
while (true) {
const { data, headers: resHeaders } = await axios.get(
`https://api.meshy.ai/openapi/v1/image-to-3d/${taskId}`,
{ headers, timeout: 30_000 },
);
task = data;
if (['SUCCEEDED', 'FAILED', 'CANCELED'].includes(task.status)) break;
if (Date.now() > deadline) {
// The task is still running. Check it again later with the same task ID instead of creating a new one.
throw new Error(`Task ${taskId} is still ${task.status}; check it again later`);
}
const waitSeconds = Number(resHeaders['retry-after']) || 5;
await new Promise((resolve) => setTimeout(resolve, waitSeconds * 1000));
}
// 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 →Smart Topology 메시
이미지로 3D에서 model_type을 smart-topology로 설정하면 깔끔하고 게임 제작에 바로 쓸 수 있는 삼각형 메시를 얻을 수 있습니다.
3D 프린트 모델
완성된 모델을 멀티컬러 3MF 파일로 변환하여 슬라이싱과 출력 준비를 마치세요.
Learn more →