# StableMesh API Reference

## Authentication

All creation endpoints require micropayment. Include payment headers as per the HTTP 402 specification. Payments are processed on Base mainnet (eip155:8453), Solana, or Tempo.

Retrieval (GET) and deletion (DELETE) endpoints are free but require SIWX wallet authentication. Only the wallet that created a task can retrieve or delete it.

## Base URL

https://stablemesh.dev

All endpoints are relative to this base URL.

## Workflow

All 3D generation tasks are **asynchronous**:
1. **Create** a task via POST (paid) — returns a task ID
2. **Poll** the task via GET `/api/{type}/{id}` (free, SIWX) until status is SUCCEEDED
3. **Download** model URLs from the completed task response

**Important:** Store the task ID returned from POST — there is no list endpoint.

## Endpoints

### Text to 3D
- `POST /api/text-to-3d` — Create text-to-3d task (preview or refine mode). $0.20–$0.80
- `GET /api/text-to-3d/{id}` — Get task status
- `DELETE /api/text-to-3d/{id}` — Delete task

### Image to 3D
- `POST /api/image-to-3d` — Create image-to-3d task. $0.20–$1.20
- `GET /api/image-to-3d/{id}` — Get task status
- `DELETE /api/image-to-3d/{id}` — Delete task

### Multi Image to 3D
- `POST /api/multi-image-to-3d` — Create multi-image-to-3d task (1-4 images). $0.20–$1.20
- `GET /api/multi-image-to-3d/{id}` — Get task status
- `DELETE /api/multi-image-to-3d/{id}` — Delete task

### Retexture
- `POST /api/retexture` — Retexture an existing 3D model. $0.40
- `GET /api/retexture/{id}` — Get task status
- `DELETE /api/retexture/{id}` — Delete task

### Remesh
- `POST /api/remesh` — Re-topology and format conversion. $0.20
- `GET /api/remesh/{id}` — Get task status
- `DELETE /api/remesh/{id}` — Delete task

### Rigging
- `POST /api/rigging` — Auto-rig a humanoid character. $0.20
- `GET /api/rigging/{id}` — Get task status
- `DELETE /api/rigging/{id}` — Delete task

### Animation
- `POST /api/animation` — Animate a rigged character. $0.12
- `GET /api/animation/{id}` — Get task status
- `DELETE /api/animation/{id}` — Delete task

## Output Formats

3D models are returned as download URLs in formats: GLB, FBX, OBJ, STL, USDZ.