---
type: AI Model
id: marigold
title: Marigold API
provider: HUAWEI Bayer Lab
description: "Marigold V2 is HUAWEI Bayer Lab's diffusion-transformer depth estimator (SIGGRAPH Asia 2026), built on Qwen-Image-Edit. From a single image it predicts a depth map, a see-through depth map that handles glass and other transparent objects, surface normals, or an albedo (lighting-free base color) map, returned as a PNG visualization."
resource: https://www.pixazo.ai/models/marigold
docs_url: https://www.pixazo.ai/models/marigold
latest_version: V2
tags:
  - image-to-image
  - huawei-bayer-lab
variants:
  - id: marigold-v2
    name: Marigold V2
    version: V2
    capabilities:
      - Image to Image (Depth Estimation)
timestamp: 2026-10-15T13:24:22.073Z
---

# Marigold API

> Provider: **HUAWEI Bayer Lab**
> Source: https://www.pixazo.ai/models/marigold

Marigold V2 is HUAWEI Bayer Lab's diffusion-transformer depth estimator (SIGGRAPH Asia 2026), built on Qwen-Image-Edit. From a single image it predicts a depth map, a see-through depth map that handles glass and other transparent objects, surface normals, or an albedo (lighting-free base color) map, returned as a PNG visualization.

## Marigold V2

### Image to Image (Depth Estimation)

## Marigold V2 Depth API Documentation

Estimate a depth, see-through depth, surface-normal or albedo map from a single image with Marigold V2. Returns a PNG. Asynchronous: submit returns a `request_id`; poll the status endpoint until the request is `COMPLETED`, then download the model from `output.media_url`. Processing usually takes from a few seconds to a few minutes.

```
POST https://gateway.pixazo.ai/marigold-v2/v1/predict
```

## Authentication

All requests require an API key passed via header.

Header

Type

Required

Description

Ocp-Apim-Subscription-Key

string

Yes

Your API subscription key

## Depth Estimation - Marigold V2

## Request Code

HTTP Python JavaScript cURL

```
POST https://gateway.pixazo.ai/marigold-v2/v1/predict
Content-Type: application/json
Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY

{
  "image_url": "https://storage.googleapis.com/falserverless/example_inputs/dog.png",
  "prediction_type": "depth"
}
```

```
import requests

url = "https://gateway.pixazo.ai/marigold-v2/v1/predict"
headers = {
    "Content-Type": "application/json",
    "Ocp-Apim-Subscription-Key": "YOUR_SUBSCRIPTION_KEY"
}
data = {
  "image_url": "https://storage.googleapis.com/falserverless/example_inputs/dog.png",
  "prediction_type": "depth"
}

resp = requests.post(url, json=data, headers=headers)
print(resp.json())
```

```
const res = await fetch("https://gateway.pixazo.ai/marigold-v2/v1/predict", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Ocp-Apim-Subscription-Key": "YOUR_SUBSCRIPTION_KEY"
  },
  body: JSON.stringify({
  "image_url": "https://storage.googleapis.com/falserverless/example_inputs/dog.png",
  "prediction_type": "depth"
})
});
console.log(await res.json());
```

```
curl -X POST 'https://gateway.pixazo.ai/marigold-v2/v1/predict' \
  -H 'Content-Type: application/json' \
  -H 'Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY' \
  --data-raw '{"image_url": "https://storage.googleapis.com/falserverless/example_inputs/dog.png", "prediction_type": "depth"}'
```

## Output

```
{
  "request_id": "marigold-v2_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "QUEUED",
  "polling_url": "https://gateway.pixazo.ai/v2/requests/status/marigold-v2_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}
```

[Try Now](https://api.pixazo.ai/api-details#api=marigold-v2&operation=image-to-3d)

## Webhook (Optional)

Instead of polling, you can receive a Webhook callback when the request reaches a terminal state. Provide a Webhook URL via header on the submit request.

Header

Required

Description

X-Webhook-URL

To enable

HTTPS URL to receive the Webhook callback.

X-Webhook-Mode

No

`terminal` (default, one callback on COMPLETED/ERROR) or `sync` (per-poll callbacks).

### Example: enable Webhook

```
curl -X POST 'https://gateway.pixazo.ai/marigold-v2/v1/predict' \
  -H 'Content-Type: application/json' \
  -H 'Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY' \
  -H 'X-Webhook-URL: https://your-server.com/webhook' \
  --data-raw '{"image_url": "https://storage.googleapis.com/falserverless/example_inputs/dog.png", "prediction_type": "depth"}'
```

### Callback Payload (success)

```
{
  "request_id": "marigold-v2_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "COMPLETED",
  "model_id": "marigold-v2",
  "output": {
    "media_url": [
      "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/v1/{request_id}/output.png"
    ],
    "media_type": "image/png"
  },
  "created_at": "2026-09-22T11:56:21.804Z",
  "completed_at": "2026-09-22T12:01:44.210Z"
}
```

### Failure callback shape

```
{
  "request_id": "marigold-v2_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "ERROR",
  "model_id": "marigold-v2",
  "error": "Description of the failure"
}
```

#### Delivery semantics

-   **terminal** mode: one Webhook callback when the request is COMPLETED or ERROR.
-   **sync** mode: a Webhook callback on each status change.
-   Callbacks are idempotent on `request_id` — de-duplicate on it.
-   Respond `200` within a few seconds; the Webhook endpoint must be HTTPS.

## Request Parameters

Parameter

Required

Type

Default

Allowed values / range

Description

`image_url`

Yes

string

—

https URL · `.jpg`, `.jpeg`, `.png`, `.webp`

The input image. Must be publicly reachable; the gateway fetches it before the job runs.

`prediction_type`

No

string

`"depth"`

`"depth"`, `"see-through-depth"`, `"normals"`, `"albedo"`

Which map to produce. `see-through-depth` handles glass and other transparent objects; `normals` returns surface normals; `albedo` returns the lighting-free base color.

`image_size`

No

string or object

input size

`"square_hd"`, `"square"`, `"portrait_4_3"`, `"portrait_16_9"`, `"landscape_4_3"`, `"landscape_16_9"`, or `{"width", "height"}`

Processing size. Width and height must be multiples of 16 and at most 2048, with an aspect ratio between 1:16 and 16:1. Defaults to the input image's size rounded to the nearest multiple of 16.

`seed`

No

integer

—

any integer

Makes the result reproducible: the same seed and image give the same map.

### Good to know

-   Exactly **one map** is returned per request. There is no batch option: `num_images`, `n`, `count`, `batch_size` and `number_of_images` are rejected.
-   To get several maps of the same image (for example depth and normals), send one request per `prediction_type`.
-   The output is a PNG visualization at the processing size — good for viewing, previews and as an input to other image tools, but not a metric (absolute-distance) depth measurement.
-   The cost is the same for every `prediction_type` and `image_size`; the current rate is in the pricing panel on this page.

## Example Request

```
{
  "image_url": "https://storage.googleapis.com/falserverless/example_inputs/dog.png",
  "prediction_type": "depth"
}
```

## Example Response

```
{
  "request_id": "marigold-v2_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "QUEUED",
  "polling_url": "https://gateway.pixazo.ai/v2/requests/status/marigold-v2_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}
```

## Request Headers

Header

Required

Description

Content-Type

Yes

`application/json`

Ocp-Apim-Subscription-Key

Yes

Your API subscription key.

X-Webhook-URL

No

Enable Webhook callbacks (see Webhook section).

## Response Handling

Status Code

Meaning

202

Accepted — request queued; returns `request_id` and `polling_url`.

400

Bad request — `image_url` missing, a `prediction_type` that is not one of the four, or a batch option such as `num_images`. Anything checkable from the request body alone.

401

Unauthorized — missing or invalid subscription key.

402

Insufficient balance.

429

Too many requests.

500

Internal server error.

Only what can be judged from the request body itself is rejected synchronously. Everything that needs an input to be fetched or the model to run is reported through the status endpoint instead, as `status: "ERROR"`. Failed requests are not billed — the hold is released in full.

Condition

How it surfaces

`image_url` missing, or not a string

synchronous `400`

`prediction_type` not one of `depth`, `see-through-depth`, `normals`, `albedo`

synchronous `400`

`num_images`, `n`, `count`, `batch_size` or `number_of_images` sent

synchronous `400`

`image_url` unreachable or not an image, or an invalid `image_size`

`status: "ERROR"` on the status endpoint (not billed)

## Retrieving Results

Poll the status endpoint with the `request_id` from the submit response until `status` is `COMPLETED` (or `FAILED`/`ERROR`), then download the model from `output.media_url`. Processing usually takes from a few seconds to a few minutes, so poll every 10–15 seconds rather than continuously.

```
curl 'https://gateway.pixazo.ai/v2/requests/status/marigold-v2_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx' \
  -H 'Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY'
```

### Completed response

```
{
  "request_id": "marigold-v2_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "COMPLETED",
  "model_id": "marigold-v2",
  "output": {
    "media_url": [
      "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/v1/{request_id}/output.png"
    ],
    "media_type": "image/png"
  },
  "created_at": "2026-09-22T11:56:21.804Z",
  "completed_at": "2026-09-22T12:01:44.210Z"
}
```

The result is a PNG visualization of the requested map (for `depth`, a colorized depth map). It is meant for viewing and as an image input to other tools; it is not a lossless numeric depth tensor.

## Response Fields

Field

Type

Description

request\_id

string

Unique request identifier.

status

string

QUEUED, PROCESSING, COMPLETED, FAILED, or ERROR.

model\_id

string

The model that handled the request.

output.media\_url

array

URL of the generated map (PNG).

output.media\_type

string

`image/png`.

created\_at

string

Request creation timestamp.

completed\_at

string

Completion timestamp.

error

string

Error message when `status` is FAILED/ERROR.

## Status Values & Flow

`QUEUED` → `PROCESSING` → `COMPLETED` (success) or `FAILED`/`ERROR` (failure).

### How billing is measured

Billing is **per generated map**, and every request returns exactly one, so the amount held when the request is submitted is the amount charged on completion. The price is the same for every `prediction_type` and `image_size`. If the request fails, the hold is released in full.