빠른 시작
Meshy와 프로그래밍 방식으로 상호작용하기 위한 API 참조입니다.
Meshy API는 텍스트 prompt와 이미지에서 3D 모델 및 텍스처를 생성하는 간단한 인터페이스를 제공합니다. 이 가이드를 따라 빠르게 시작하세요.
API 키 생성
여기 API 설정 페이지에서 API 키를 생성하세요. 이 키를 사용하여 요청을 안전하게 인증합니다. API 키의 형식은 msy-<random-string>입니다.
API 키를 생성한 후에는 안전한 위치에 저장하세요.
테스트 모드 API 키
개발 및 테스트 중에는 크레딧을 소비하지 않고 API를 탐색할 수 있도록 테스트 모드 API 키를 사용할 수 있습니다.
msy_dummy_api_key_for_test_mode_12345678
이 특별한 API 키에는 다음과 같은 특징이 있습니다.
- 모든 Meshy API 엔드포인트에 요청을 보낼 때 사용할 수 있습니다
- 이 키를 사용할 때는 크레딧이 소비되지 않습니다
- 입력 파라미터와 관계없이 모든 유효한 요청은 동일한 샘플 작업 결과를 반환합니다
- 응답 데이터 구조는 프로덕션 API와 정확히 일치합니다
- 실제 API 키로 전환하기 전에 API 연동을 테스트하는 데 적합합니다
테스트 모드 API 키는 개발 목적으로만 사용해야 합니다. 프로덕션 용도로는 본인의 API 키를 사용하세요.
첫 번째 "텍스트로 3D" API 요청 보내기
이 예제에서는 text-to-3d 엔드포인트를 사용하여 텍스트 prompt에서 3D 모델을 생성합니다. 이 과정은 미리보기 단계와 정제 단계의 두 단계로 구성됩니다. 미리보기 단계에서는 텍스처가 적용되지 않은 기본 메시가 생성되어 지오메트리를 평가할 수 있습니다. 정제 단계에서는 텍스트 prompt를 기반으로 미리보기 메시가 텍스처링됩니다.
Python 스크립트에서 이러한 요청을 보내는 방법을 보여드리겠습니다.
미리보기
Meshy는 REST API 엔드포인트 세트를 제공합니다. 원하는 어떤 HTTP 클라이언트와도 함께 사용할 수 있습니다. 어떤 API를 호출하든 API 키는 항상 Authorization이라는 이름의 헤더로 전달됩니다. 이 스크립트를 사용하기 전에 API 키를 MESHY_API_KEY라는 환경 변수로 내보내는 것을 잊지 마세요.
미리보기 요청의 핵심 파라미터는 항상 "preview"인 mode와 필요한 모델에 대한 설명인 prompt입니다. 이 예제에서는 should_remesh도 지정했지만, 이는 선택 사항입니다.
api_request.py
import requests
import os
import time
headers = {
"Authorization": f"Bearer {os.environ['MESHY_API_KEY']}"
}
# 1. Generate a preview model and get the task ID
generate_preview_request = {
"mode": "preview",
"prompt": "a monster mask",
"should_remesh": True,
}
generate_preview_response = requests.post(
"https://api.meshy.ai/openapi/v2/text-to-3d",
headers=headers,
json=generate_preview_request,
)
generate_preview_response.raise_for_status()
preview_task_id = generate_preview_response.json()["result"]
print("Preview task created. Task ID:", preview_task_id)
이것으로 미리보기 API 호출이 완료됩니다.
Meshy API는 비동기 실행 모델을 채택하고 있다는 점을 유의하세요. 즉, 작업을 생성하면 API 엔드포인트는 작업 ID만 반환합니다. 그런 다음 이 ID로 작업 상태 엔드포인트를 폴링하여 작업이 완료되었는지 확인해야 합니다.
api_request.py
# 2. Poll the preview task status until it's finished
preview_task = None
while True:
preview_task_response = requests.get(
f"https://api.meshy.ai/openapi/v2/text-to-3d/{preview_task_id}",
headers=headers,
)
preview_task_response.raise_for_status()
preview_task = preview_task_response.json()
if preview_task["status"] == "SUCCEEDED":
print("Preview task finished.")
break
print("Preview task status:", preview_task["status"], "| Progress:", preview_task["progress"], "| Retrying in 5 seconds...")
time.sleep(5)
작업이 완료되면 응답에서 모델 URL에 액세스할 수 있습니다. 응답의 model_urls 필드에서 모델을 다운로드해 보겠습니다.
api_request.py
# 3. Download the preview model in glb format
preview_model_url = preview_task["model_urls"]["glb"]
preview_model_response = requests.get(preview_model_url)
preview_model_response.raise_for_status()
with open("preview_model.glb", "wb") as f:
f.write(preview_model_response.content)
print("Preview model downloaded.")
지금까지 모든 것이 제대로 작동했다면 preview_model.glb는 다음과 비슷하게 보일 것입니다. AI 파이프라인의 내재적 무작위성 때문에 정확히 일치하지는 않습니다.
정제
이제 정제 단계로 진행하겠습니다. 정제 요청을 시작하려면 미리보기 작업 ID를 입력 파라미터로 제공하세요.
api_request.py
# 4. Generate a refined model and get the task ID
generate_refined_request = {
"mode": "refine",
"preview_task_id": preview_task_id,
}
generate_refined_response = requests.post(
"https://api.meshy.ai/openapi/v2/text-to-3d",
headers=headers,
json=generate_refined_request,
)
generate_refined_response.raise_for_status()
refined_task_id = generate_refined_response.json()["result"]
print("Refined task created. Task ID:", refined_task_id)
# 5. Poll the refined task status until it's finished
refined_task = None
while True:
refined_task_response = requests.get(
f"https://api.meshy.ai/openapi/v2/text-to-3d/{refined_task_id}",
headers=headers,
)
refined_task_response.raise_for_status()
refined_task = refined_task_response.json()
if refined_task["status"] == "SUCCEEDED":
print("Refined task finished.")
break
print("Refined task status:", refined_task["status"], "| Progress:", refined_task["progress"], "| Retrying in 5 seconds...")
time.sleep(5)
# 6. Download the refined model in glb format
refined_model_url = refined_task["model_urls"]["glb"]
refined_model_response = requests.get(refined_model_url)
refined_model_response.raise_for_status()
with open("refined_model.glb", "wb") as f:
f.write(refined_model_response.content)
print("Refined model downloaded.")
이제 3D 모델 refined_model.glb에 텍스처가 완전히 적용되었습니다 ✨.
모두 합치기
다음은 텍스트로 3D API를 사용하기 위한 전체 코드입니다.
api_request.py
import requests
import os
import time
headers = {
"Authorization": f"Bearer {os.environ['MESHY_API_KEY']}"
}
# 1. Generate a preview model and get the task ID
generate_preview_request = {
"mode": "preview",
"prompt": "a monster mask",
"should_remesh": True,
}
generate_preview_response = requests.post(
"https://api.meshy.ai/openapi/v2/text-to-3d",
headers=headers,
json=generate_preview_request,
)
generate_preview_response.raise_for_status()
preview_task_id = generate_preview_response.json()["result"]
print("Preview task created. Task ID:", preview_task_id)
# 2. Poll the preview task status until it's finished
preview_task = None
while True:
preview_task_response = requests.get(
f"https://api.meshy.ai/openapi/v2/text-to-3d/{preview_task_id}",
headers=headers,
)
preview_task_response.raise_for_status()
preview_task = preview_task_response.json()
if preview_task["status"] == "SUCCEEDED":
print("Preview task finished.")
break
print("Preview task status:", preview_task["status"], "| Progress:", preview_task["progress"], "| Retrying in 5 seconds...")
time.sleep(5)
# 3. Download the preview model in glb format
preview_model_url = preview_task["model_urls"]["glb"]
preview_model_response = requests.get(preview_model_url)
preview_model_response.raise_for_status()
with open("preview_model.glb", "wb") as f:
f.write(preview_model_response.content)
print("Preview model downloaded.")
# 4. Generate a refined model and get the task ID
generate_refined_request = {
"mode": "refine",
"preview_task_id": preview_task_id,
}
generate_refined_response = requests.post(
"https://api.meshy.ai/openapi/v2/text-to-3d",
headers=headers,
json=generate_refined_request,
)
generate_refined_response.raise_for_status()
refined_task_id = generate_refined_response.json()["result"]
print("Refined task created. Task ID:", refined_task_id)
# 5. Poll the refined task status until it's finished
refined_task = None
while True:
refined_task_response = requests.get(
f"https://api.meshy.ai/openapi/v2/text-to-3d/{refined_task_id}",
headers=headers,
)
refined_task_response.raise_for_status()
refined_task = refined_task_response.json()
if refined_task["status"] == "SUCCEEDED":
print("Refined task finished.")
break
print("Refined task status:", refined_task["status"], "| Progress:", refined_task["progress"], "| Retrying in 5 seconds...")
time.sleep(5)
# 6. Download the refined model in glb format
refined_model_url = refined_task["model_urls"]["glb"]
refined_model_response = requests.get(refined_model_url)
refined_model_response.raise_for_status()
with open("refined_model.glb", "wb") as f:
f.write(refined_model_response.content)
print("Refined model downloaded.")
코드를 Python 스크립트에 복사하여 붙여넣고 실행하세요.
Run the script
python api_request.py
터미널에서 다음과 같은 출력이 표시됩니다.
다음 단계
- 먼저 코드를 작성하지 않고 엔드포인트를 사용해 보고 싶으신가요? API Playground를 사용하여 요청을 구성하고 실행한 다음, 생성된 스니펫을 복사하세요.
- 전체 API 참조는 "API 엔드포인트" 섹션에서 확인할 수 있으며, 각 API에 대한 자세한 정보를 제공합니다.
- 요금, Rate Limits, 그리고 일반적인 오류를 해결하는 방법에 대한 세부 정보를 살펴보세요.
- 업데이트와 버그 수정을 확인하려면 변경 로그를 정기적으로 확인하는 것을 잊지 마세요.
- 피드백이 있거나 문제가 발생했나요? Discord 커뮤니티에 참여해 주세요. 여러분의 의견을 듣고 싶습니다!