Antigravity AI 설치 및 설정 가이드: Python SDK, API 키 관리, Blender 통합까지
Antigravity AI란?
Antigravity AI는 머신러닝 기반의 물리 시뮬레이션 엔진으로, 유체 역학, 강체 충돌, 천체 역학 등 복잡한 물리 연산을 GPU 가속과 AI 예측 모델을 결합하여 처리합니다. Python SDK를 통해 프로그래밍 방식으로 시뮬레이션을 정의하고 실행할 수 있으며, Blender와의 네이티브 통합으로 시각화 파이프라인까지 자동화할 수 있습니다.
사전 요구 사항
- Python 3.9 이상
- pip 또는 conda 패키지 관리자
- Blender 3.6 이상 (Blender 통합 시)
- CUDA 지원 GPU (선택 사항, 성능 향상에 권장)
- Antigravity AI 계정 (platform.antigravity.ai에서 가입)
1단계: Python SDK 설치
터미널에서 pip를 사용하여 Antigravity AI SDK를 설치합니다.
pip install antigravity-aiGPU 가속을 활용하려면 CUDA 확장 패키지를 함께 설치합니다.
pip install antigravity-ai[cuda]설치가 완료되면 다음 명령어로 버전을 확인하세요.
python -c "import antigravity_ai; print(antigravity_ai.__version__)"2단계: API 키 발급 및 관리
Antigravity AI 대시보드에 로그인한 뒤 Settings > API Keys 메뉴에서 새 키를 생성합니다.
환경 변수로 설정 (권장)
API 키를 코드에 직접 입력하지 말고 환경 변수로 관리하세요.
# Linux / macOS export ANTIGRAVITY_API_KEY="YOUR_API_KEY"Windows PowerShell
$env:ANTIGRAVITY_API_KEY=“YOUR_API_KEY”
영구적으로 저장하려면 .env 파일을 프로젝트 루트에 생성합니다.
# .env
ANTIGRAVITY_API_KEY=YOUR_API_KEY
ANTIGRAVITY_PROJECT_ID=YOUR_PROJECT_IDCLI를 통한 인증 확인
antigravity auth verify
출력: ✓ Authenticated as user@example.com (Project: my-project)
3단계: 첫 번째 물리 시뮬레이션 실행
SDK를 임포트하고 간단한 강체 낙하 시뮬레이션을 작성해 봅니다.
import antigravity_ai as ag클라이언트 초기화 (환경 변수에서 API 키 자동 로드)
client = ag.Client()
시뮬레이션 씬 생성
scene = client.create_scene( name=“rigid_body_drop”, gravity=[0, -9.81, 0], time_step=0.016 )
오브젝트 추가
scene.add_rigid_body( shape=“sphere”, radius=0.5, mass=2.0, position=[0, 10, 0], restitution=0.7 )
scene.add_static_plane( normal=[0, 1, 0], offset=0 )
시뮬레이션 실행 (3초, 서버 측 GPU 연산)
result = scene.simulate(duration=3.0, engine=“gpu”)
결과 조회
for frame in result.frames[:5]: print(f”t={frame.time:.3f}s | pos={frame.positions[0]}“)
4단계: Blender 통합 설정
Blender 연동을 위해 전용 애드온을 설치합니다.
antigravity blender install —blender-path “/path/to/blender”또는 Blender 내부에서 수동 설치할 수 있습니다.
- Blender를 열고 Edit > Preferences > Add-ons으로 이동합니다.
- Install 버튼을 클릭하고 SDK에 포함된
antigravity_blender_addon.zip파일을 선택합니다. Physics: Antigravity AI애드온을 활성화합니다.- 애드온 설정에서 API 키를 입력하거나, 환경 변수를 사용하도록 Use Environment Variable을 체크합니다.
Blender에서 시뮬레이션 결과 불러오기
import antigravity_ai as ag import antigravity_ai.blender as ag_blenderclient = ag.Client() result = client.get_simulation(“sim_abc123”)
Blender 씬에 키프레임 자동 적용
ag_blender.apply_to_scene( result, target_collection=“Simulation”, fps=60, scale_factor=1.0 )
5단계: 자동화 워크플로우 구축
여러 시뮬레이션을 배치로 실행하고 결과를 자동으로 렌더링하는 파이프라인을 구성합니다.
import antigravity_ai as agclient = ag.Client()
배치 시뮬레이션 정의
configs = [ {“gravity”: [0, -9.81, 0], “restitution”: 0.3}, {“gravity”: [0, -9.81, 0], “restitution”: 0.6}, {“gravity”: [0, -9.81, 0], “restitution”: 0.9}, ]
batch = client.create_batch(“bounce_comparison”)
for i, cfg in enumerate(configs): scene = batch.add_scene(name=f”bounce_{i}”) scene.set_gravity(cfg[“gravity”]) scene.add_rigid_body( shape=“sphere”, radius=0.5, mass=1.0, position=[0, 10, 0], restitution=cfg[“restitution”] ) scene.add_static_plane(normal=[0, 1, 0], offset=0)
병렬 실행
results = batch.run(duration=5.0, parallel=True)
결과 내보내기
for r in results: r.export(format=“alembic”, path=f”./output/{r.name}.abc”) print(f”{r.name}: {len(r.frames)} frames exported”)
Pro Tips
- 캐시 활용:
client.create_scene(cache=True)를 설정하면 동일한 파라미터의 시뮬레이션 결과를 재사용하여 API 호출 비용을 절약할 수 있습니다. - Webhook 연동: 장시간 시뮬레이션에는
batch.run(webhook_url=“https://your-server.com/hook”)을 설정하여 완료 시 알림을 받으세요. - 로컬 프리뷰:
antigravity preview sim_abc123 —viewer명령으로 웹 브라우저에서 빠르게 결과를 미리 볼 수 있습니다. - 정밀도 조절:
time_step을 0.008 이하로 설정하면 유체 시뮬레이션의 정확도가 크게 향상됩니다. 단, 연산 시간이 증가합니다. - 팀 협업:
ANTIGRAVITY_PROJECT_ID를 공유하면 팀원 간 시뮬레이션 결과와 씬을 공동으로 관리할 수 있습니다.
Troubleshooting
| 오류 메시지 | 원인 | 해결 방법 |
|---|---|---|
AuthenticationError: Invalid API key | API 키가 누락되었거나 잘못됨 | 환경 변수 ANTIGRAVITY_API_KEY가 올바르게 설정되어 있는지 확인하세요. antigravity auth verify로 인증 상태를 점검합니다. |
CUDANotAvailable: No GPU detected | CUDA 드라이버 미설치 또는 GPU 미감지 | nvidia-smi로 GPU 상태를 확인하고, pip install antigravity-ai[cuda]로 CUDA 확장을 재설치하세요. CPU 모드로 전환하려면 engine=“cpu”를 사용합니다. |
BlenderAddonError: Version mismatch | Blender 버전과 애드온 호환성 문제 | Blender 3.6 이상인지 확인하고 pip install —upgrade antigravity-ai로 SDK를 최신 버전으로 업데이트한 뒤 애드온을 재설치하세요. |
SimulationTimeout: Exceeded max duration | 시뮬레이션이 서버 제한 시간을 초과 | duration 값을 줄이거나 time_step을 늘려 프레임 수를 줄이세요. Pro 플랜에서는 제한 시간이 확장됩니다. |
ExportError: Unsupported format | 지원되지 않는 내보내기 형식 | 지원 형식: alembic, usd, fbx, csv. 올바른 형식 문자열을 export(format=…)에 전달하세요. |
자주 묻는 질문 (FAQ)
Q1: Antigravity AI 무료 플랜에서 사용할 수 있는 시뮬레이션 제한은 어떻게 되나요?
무료 플랜에서는 월 100회의 시뮬레이션 실행과 최대 10초 duration, CPU 엔진만 사용할 수 있습니다. GPU 가속, 배치 병렬 실행, Webhook 연동 등의 고급 기능은 Pro 플랜 이상에서 지원됩니다. 프로젝트 대시보드의 Usage 탭에서 현재 사용량을 실시간으로 확인할 수 있습니다.
Q2: Blender 없이 시뮬레이션 결과를 시각화할 수 있나요?
네, 가능합니다. antigravity preview <simulation_id> —viewer CLI 명령을 사용하면 웹 브라우저 기반 3D 뷰어에서 결과를 확인할 수 있습니다. 또한 result.export(format=“csv”)로 데이터를 내보내 Matplotlib이나 다른 시각화 라이브러리에서 분석하는 것도 가능합니다. USD 형식으로 내보내면 다른 3D 소프트웨어에서도 열 수 있습니다.
Q3: 기존 Blender 물리 시뮬레이션 프로젝트를 Antigravity AI로 마이그레이션할 수 있나요?
Blender 애드온의 Import Scene 기능을 사용하면 현재 Blender 씬의 강체, 충돌체, 물리 속성을 자동으로 Antigravity AI 씬 구성으로 변환할 수 있습니다. Blender 스크립팅 콘솔에서 ag_blender.import_from_blender(collection=“Physics”)를 실행하면 지정된 컬렉션의 오브젝트를 변환합니다. 다만 Blender 고유의 일부 시뮬레이션 유형(Cloth, Soft Body의 특정 파라미터)은 수동 조정이 필요할 수 있습니다.