# AI3D API v2 model: moge3

Image-to-3D geometry estimation through the Yosun MoGe-3 Hugging Face Space, which runs the `Ruicheng/moge-3-vitg` weights.

- AI3D model ID: `moge3`
- Task: `image_to_3d`
- AI3D provider adapter: `gradio`
- Availability: Check `GET https://api.ai3d.dev/v2/models` before use; key model allowlists may also restrict access.
- Provider Space: https://huggingface.co/spaces/Yosun/MoGe-3 (used in place of the official `Ruicheng/MoGe-3` Space, which is currently unavailable)
- Shared implementation guide: <https://api.ai3d.dev/v2/llms.txt>
- AI3D API reference: <https://api.ai3d.dev/v2/openapi.json>

## Request

Submit through the AI3D v2 asynchronous job API. Do not call the provider directly or put provider credentials in the client.

- Method and URL: `POST https://api.ai3d.dev/v2/jobs`
- Authentication: `Authorization: Bearer <AI3D_API_KEY>` with write permission and this model allowed on the key.
- Content type: `application/json`
- Source: Requires a publicly reachable HTTPS source image in `image_url`.
- Request body: `input` is optional model-specific JSON. The API supplies these defaults; caller values override defaults for these supported fields:

```json
{
  "max_size": 1024,
  "resolution_level": "High",
  "apply_mask": true,
  "remove_edges": true,
  "refine_steps": 3
}
```

`max_size` accepts 256–4096 and controls the maximum processed image dimension. `resolution_level` accepts `Low`, `Medium`, `High`, or `Ultra`. `apply_mask` and `remove_edges` are booleans. `refine_steps` controls MoGe-3's refinement pass count; the Space supports values from 0 through 5.

Example request body:

```json
{
  "model": "moge3",
  "image_url": "https://example.com/object.png",
  "input": {}
}
```

## Job lifecycle

1. Check `GET https://api.ai3d.dev/v2/models`; this model must appear in the enabled catalog. Check `GET https://api.ai3d.dev/v2/billing/prices` for the current reservation estimate.
2. Submit to `POST /v2/jobs` with a fresh `Idempotency-Key` header (maximum 128 characters). A successful submission returns `202 Accepted` and a job ID.
3. Poll `GET /v2/jobs/{job_id}` until `status` is `succeeded`, `failed`, or `submission_unknown`.
4. On success, download artifacts using the authenticated `download_url` values returned in the job response. Do not depend on fixed artifact names or ordering.

Hugging Face Space jobs are currently billed at the fixed AI3D rate shown by `/v2/billing/prices` (currently $0.10 per job). Cold starts and provider queue time can affect completion time. The Space runs on Hugging Face ZeroGPU, so a job can also wait for a GPU slot. A public Space's availability is controlled by its owner.

## Output notes

The Space exposes textured mesh and point-cloud files in GLB and PLY, plus float EXR geometry outputs when returned by the provider. The exact artifact set can vary. Use returned artifact metadata and `artifact_warnings`; do not assume all outputs are present or that an artifact named `mesh.glb` is guaranteed.

MoGe-3 estimates metric-scale geometry from one image. The result is a view-derived surface/point cloud, not a complete hidden-side object reconstruction.