Name: MoGe-2 Depth, Normal and Point Cloud Estimation API
Brand: magicapi
SKU: api-magicapi-depth-normal-point-cloud-generator-jasonod888-moge2
Availability: InStock
Author: API Market

Shashank Agarwal

# 🌌 Depth, Normal & Point Cloud Estimation API (jasonod888 MoGe-2)

## Overview
MoGe-2 by jasonod888 recovers the 3D geometry of a scene from a single image. Its developer describes it as a model that outputs depth, normal and point cloud for a given input image.

Send an `image` URL. One request returns a set of files: a depth map (EXR and a PNG preview), a surface normal map (PNG), a validity mask (PNG), the 3D points (EXR), a point cloud (PLY), a mesh (GLB), the camera intrinsics and field of view (JSON), plus the horizontal and vertical field of view in degrees as numbers.

## Features
- **Depth from one image**: depth as an EXR file and a colored PNG preview.
- **Surface normals**: a PNG normal map of the scene.
- **3D outputs**: a point cloud (`.ply`), a mesh (`.glb`) and per-pixel 3D points (`.exr`).
- **Camera estimate**: field of view (`fov_x_deg`, `fov_y_deg`) and an intrinsics matrix. Set `fov_x` if you already know the horizontal field of view.
- **Speed and detail control**: `resolution_level` (0 to 9), `num_tokens`, `resize_to` and `fp16`.

## Use Cases
1. **3D reconstruction from photos**: turn a single photo into a point cloud or mesh for a 3D viewer.
2. **Depth effects**: depth-based blur, fog or parallax for images.
3. **Relighting and compositing**: use the normal map and depth to light or place objects in a still image.
4. **Robotics and vision prototyping**: per-pixel 3D points and camera intrinsics from a single camera frame.

## Visual Examples
### Example Input
![Example input image for MoGe-2](https://blog.api.market/wp-content/uploads/2026/10/moge2-input-w14-api-market.jpg)

Settings: `resolution_level` 9, `threshold` 0.04, `fp16` `true`, `debug_write_local` `false`.

### Example Output
Depth preview (`depth_vis_png`):

![MoGe-2 output: colored depth preview of the input image](https://blog.api.market/wp-content/uploads/2026/10/moge2-output-2-v3eb7n7n-api-market.png)

Normal map (`normal_png`):

![MoGe-2 output: surface normal map of the input image](https://blog.api.market/wp-content/uploads/2026/10/moge2-output-6-v3eb7n7n-api-market.png)

Validity mask (`mask_png`):

![MoGe-2 output: mask of the pixels with valid geometry](https://blog.api.market/wp-content/uploads/2026/10/moge2-output-4-v3eb7n7n-api-market.png)

Input image as JPEG (`image_jpg`):

![MoGe-2 output: the input image returned as JPEG](https://blog.api.market/wp-content/uploads/2026/10/moge2-output-3-v3eb7n7n-api-market.jpg)

The other files of this run: `fov.json` contained `{"fov_x": 52.37, "fov_y": 52.37}`, `intrinsics.json` contained `{"intrinsics": [[1.0167655944824219, 0.0, 0.5], [0.0, 1.0167655944824219, 0.5], [0.0, 0.0, 1.0]]}`, and the run also returned `depth.exr` (about 0.8 MB), `points.exr` (about 5.3 MB), `pointcloud.ply` (about 26 MB) and `mesh.glb` (about 53 MB). These file types cannot be shown on this page.

## Input Parameters
| Field | Type | Required | Default | Allowed values | Description |
| --- | --- | --- | --- | --- | --- |
| `image` | string (URL) | Yes |  |  | Input image (jpg or png). |
| `resolution_level` | integer | No | `9` | 0 to 9 | Inference resolution level. Higher captures finer detail but is slower. |
| `num_tokens` | integer | No | none |  | Optional token count override (its developer suggests 1200 to 2500). If set, it overrides `resolution_level`. |
| `resize_to` | integer | No | none |  | Optional: resize the long side of the image to this many pixels, keeping the aspect ratio. 0 or unset means no resize. |
| `fov_x` | number | No | none |  | Optional horizontal field of view in degrees. If omitted, the model estimates it. |
| `threshold` | number | No | `0.04` |  | Threshold for removing depth edges before building the mesh. Use a very large number to disable it. |
| `fp16` | boolean | No | `true` |  | Use half precision (FP16) for faster inference. |
| `debug_write_local` | boolean | No | `true` |  | Debug option of the model's developer for writing the outputs to a local folder when running the model locally. Send `false`, as the example does. |

## Pricing
- **Pay As You Go (PAYG) pricing**: you only pay for what you use.
- **Price**: $0.0065 per API unit.
- **1 API unit = one request with up to 26 seconds of processing.** A request that takes longer is billed one more unit for every started 26-second block (for example, 26 to 52 seconds is 2 units, $0.013).
- Larger images and a higher `resolution_level` or `num_tokens` take longer to process.
- **Example cost**: the example request took 8.6 seconds of processing: 1 unit, $0.0065.
- **Failed or cancelled predictions are not billed.**
- **GET requests to check prediction status** are free and don't count toward API unit usage.
- **No monthly subscription fee.**

## API Documentation

### Base URL
All API requests go to: `https://prod.api.market/api/v1/magicapi/depth-normal-point-cloud-generator-jasonod888-moge2`

### Authentication
Send your api.market API key in the `x-api-market-key` header:
```
x-api-market-key: YOUR_API_MARKET_KEY
```

### Asynchronous Processing
**IMPORTANT**: This API is asynchronous. The flow is:
1. Send a POST request to `/predictions`. A successful request returns **201 Created** with a prediction `id` and a `status` of `starting` or `processing`.
2. Poll GET `/predictions/{id}` with that ID.
3. Keep polling while `status` is `starting` or `processing`.
4. Stop when `status` is `succeeded` (read `output`), `failed` or `canceled` (read `error`).

A polling interval of 1 second and an overall timeout of 600 seconds (10 minutes) work well.

### Endpoints

#### Create a Prediction
```bash
curl -X POST "https://prod.api.market/api/v1/magicapi/depth-normal-point-cloud-generator-jasonod888-moge2/predictions" \
  -H "Content-Type: application/json" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY" \
  -d '{
    "version": "daa7a9329b3d6bb513f3a20def9451b6e3cf234afe2bb60ba38f96ecd33c81f7",
    "input": {
      "fp16": true,
      "image": "https://blog.api.market/wp-content/uploads/2026/10/moge2-input-w14-api-market.jpg",
      "threshold": 0.04,
      "resolution_level": 9,
      "debug_write_local": false
    }
  }'
```

Response (201 Created):
```json
{
  "id": "v3eb7n7n2drgc0d1f57antd5c0",
  "version": "daa7a9329b3d6bb513f3a20def9451b6e3cf234afe2bb60ba38f96ecd33c81f7",
  "status": "starting",
  "created_at": "2026-10-26T17:43:00.284Z"
}
```

#### Check Prediction Status
```bash
curl -X GET "https://prod.api.market/api/v1/magicapi/depth-normal-point-cloud-generator-jasonod888-moge2/predictions/{id}" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY"
```

Response when the prediction has finished (200 OK):
```json
{
  "id": "v3eb7n7n2drgc0d1f57antd5c0",
  "status": "succeeded",
  "output": {
    "debug_out_dir": "/tmp/moge2_82bb8a81",
    "depth_exr": "<URL of depth.exr>",
    "depth_vis_png": "https://blog.api.market/wp-content/uploads/2026/10/moge2-output-2-v3eb7n7n-api-market.png",
    "fov_json": "<URL of fov.json>",
    "fov_x_deg": 52.37,
    "fov_y_deg": 52.37,
    "image_jpg": "https://blog.api.market/wp-content/uploads/2026/10/moge2-output-3-v3eb7n7n-api-market.jpg",
    "intrinsics_json": "<URL of intrinsics.json>",
    "mask_png": "https://blog.api.market/wp-content/uploads/2026/10/moge2-output-4-v3eb7n7n-api-market.png",
    "mesh_glb": "<URL of mesh.glb>",
    "normal_png": "https://blog.api.market/wp-content/uploads/2026/10/moge2-output-6-v3eb7n7n-api-market.png",
    "pointcloud_ply": "<URL of pointcloud.ply>",
    "points_exr": "<URL of points.exr>"
  },
  "error": null,
  "created_at": "2026-10-26T17:43:00.284Z",
  "started_at": "2026-10-26T17:45:03.544Z",
  "completed_at": "2026-10-26T17:45:12.162Z"
}
```

`output` is an object. Image previews and files are URLs: `depth_exr`, `depth_vis_png`, `normal_png`, `mask_png`, `image_jpg`, `points_exr`, `pointcloud_ply`, `mesh_glb`, `fov_json` and `intrinsics_json`. `fov_x_deg` and `fov_y_deg` are numbers in degrees. `debug_out_dir` is a folder path on the model server and can be ignored. Above, `<URL of ...>` stands for the URLs of the files that cannot be shown on this page; your response contains real URLs for them. Download the files promptly after the prediction finishes.

### Status Codes
- **201 Created**: prediction created (POST `/predictions`). This is the normal success response.
- **200 OK**: prediction details returned (GET `/predictions/{id}`).
- **400 Bad Request**: invalid input, for example a missing `image`.
- **401 Unauthorized**: missing or invalid API key.
- **404 Not Found**: no prediction with that ID.
- **429 Too Many Requests**: rate limit exceeded.
- **500 Internal Server Error** or **503 Service Unavailable**: temporary server problem; retry later.

## Rate Limits
Requests are rate limited to keep usage fair. If you receive a 429 response, wait and retry with exponential backoff.

## Error Handling
- Check the HTTP status code of every request and read the response body for the error message.
- A prediction can also end with `status` set to `failed`; the `error` field then explains why. Failed predictions are not billed.
- Retry 429, 500 and 503 responses with exponential backoff. Fix the input before retrying a 400.

## Implementation Guide
### Example Code

#### JavaScript
```javascript
const apiKey = "YOUR_API_MARKET_KEY";
const baseUrl = "https://prod.api.market/api/v1/magicapi/depth-normal-point-cloud-generator-jasonod888-moge2";

async function createAndWaitForPrediction(input) {
  const response = await fetch(`${baseUrl}/predictions`, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "x-api-market-key": apiKey
    },
    body: JSON.stringify({ version: "daa7a9329b3d6bb513f3a20def9451b6e3cf234afe2bb60ba38f96ecd33c81f7", input })
  });

  if (response.status !== 201) {
    throw new Error(`API error: ${response.status} ${await response.text()}`);
  }

  const prediction = await response.json();
  return pollForResults(prediction.id);
}

const delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

async function pollForResults(predictionId) {
  const maxTimeout = 600000;
  const pollInterval = 1000;
  const startTime = Date.now();

  while (Date.now() - startTime < maxTimeout) {
    const response = await fetch(`${baseUrl}/predictions/${predictionId}`, {
      headers: { "x-api-market-key": apiKey }
    });

    if (!response.ok) {
      throw new Error(`API error: ${response.status} ${await response.text()}`);
    }

    const prediction = await response.json();

    if (prediction.status === "succeeded") {
      return prediction.output;
    }

    if (prediction.status === "failed" || prediction.status === "canceled") {
      throw new Error(`Prediction ${prediction.status}: ${prediction.error || "Unknown error"}`);
    }

    await delay(pollInterval);
  }

  throw new Error("Prediction timed out after 10 minutes");
}

createAndWaitForPrediction({
  "fp16": true,
  "image": "https://blog.api.market/wp-content/uploads/2026/10/moge2-input-w14-api-market.jpg",
  "threshold": 0.04,
  "resolution_level": 9,
  "debug_write_local": false
}).then((output) => console.log(output));
```

#### Python
```python
import time
import requests

API_KEY = "YOUR_API_MARKET_KEY"
BASE_URL = "https://prod.api.market/api/v1/magicapi/depth-normal-point-cloud-generator-jasonod888-moge2"


def create_and_wait_for_prediction(input_data):
    headers = {"Content-Type": "application/json", "x-api-market-key": API_KEY}
    response = requests.post(
        f"{BASE_URL}/predictions",
        headers=headers,
        json={"version": "daa7a9329b3d6bb513f3a20def9451b6e3cf234afe2bb60ba38f96ecd33c81f7", "input": input_data},
    )

    if response.status_code != 201:
        raise Exception(f"API error: {response.status_code} {response.text}")

    return poll_for_results(response.json()["id"])


def poll_for_results(prediction_id):
    max_timeout = 600
    poll_interval = 1
    headers = {"x-api-market-key": API_KEY}
    start_time = time.time()

    while time.time() - start_time < max_timeout:
        response = requests.get(f"{BASE_URL}/predictions/{prediction_id}", headers=headers)

        if response.status_code != 200:
            raise Exception(f"API error: {response.status_code} {response.text}")

        prediction = response.json()

        if prediction["status"] == "succeeded":
            return prediction["output"]

        if prediction["status"] in ("failed", "canceled"):
            raise Exception(f"Prediction {prediction['status']}: {prediction.get('error') or 'Unknown error'}")

        time.sleep(poll_interval)

    raise Exception("Prediction timed out after 10 minutes")


print(create_and_wait_for_prediction({
  "fp16": True,
  "image": "https://blog.api.market/wp-content/uploads/2026/10/moge2-input-w14-api-market.jpg",
  "threshold": 0.04,
  "resolution_level": 9,
  "debug_write_local": False
}))
```

## FAQ
- **What files does one request return?**
  - Depth (`depth_exr`, `depth_vis_png`), normals (`normal_png`), a validity mask (`mask_png`), the input image as JPEG (`image_jpg`), 3D points (`points_exr`), a point cloud (`pointcloud_ply`), a mesh (`mesh_glb`), and the camera field of view and intrinsics (`fov_json`, `intrinsics_json`, `fov_x_deg`, `fov_y_deg`).
- **How do I trade speed for detail?**
  - Lower `resolution_level` (default 9, the highest) for faster runs, or set `num_tokens` directly (its developer suggests 1200 to 2500); `num_tokens` overrides `resolution_level`. `resize_to` shrinks large images first.
- **I know my camera's field of view. Can I pass it?**
  - Yes. Set `fov_x` to the horizontal field of view in degrees; otherwise the model estimates it (52.37 degrees in the example).
- **What does `threshold` do?**
  - It removes depth edges before the mesh is built, so the mesh does not stretch across object borders. Use a very large number to keep all edges.
- **How much does one request cost?**
  - One unit ($0.0065) covers up to 26 seconds of processing; longer requests use one more unit per started 26-second block. The example took 8.6 seconds, so it cost 1 unit ($0.0065).
- **What if my prediction fails?**
  - Failed predictions are not billed. Read the `error` field, check that the image URL is reachable and try again.

## Contact Us
If you have any questions or need assistance, you can reach out to us through the embedded chat on the bottom right corner of the page or send an email to hello@magicapi.com.


Get a depth map, normal map, point cloud, GLB mesh and field of view from one image with MoGe-2. $0.0065 per request, pay as you go.