# HiDream API

> Provider: **HiDream**
> Source: https://www.pixazo.ai/models/hidream

Open-source image generative foundation model family from HiDream-ai. The I1 Full (17B) and O1 / O1 Dev variants deliver state-of-the-art text-to-image and image-to-image (edit) generation.

## HiDream O1

### Text to Image

## Base URL

```
https://gateway.pixazo.ai/hidream-o1-image/v1
```

## Authentication

All requests require an API key passed via header.

Header

Type

Required

Description

Ocp-Apim-Subscription-Key

string

Yes

Your API subscription key

## HiDream O1 Image generate request

## Request Code

HTTP Python JavaScript cURL

```
POST https://gateway.pixazo.ai/hidream-o1-image/v1/hidream-o1-image-request
Content-Type: application/json
Cache-Control: no-cache
Ocp-Apim-Subscription-Key: YOUR_API_KEY

{
  "prompt": "A cinematic product photo of a ceramic mug on a marble counter, soft window light, shallow depth of field",
  "image_size": {
    "width": 2048,
    "height": 2048
  },
  "num_inference_steps": 50,
  "guidance_scale": 5,
  "num_images": 1,
  "output_format": "png",
  "enable_safety_checker": true
}
```

```
import requests

url = "https://gateway.pixazo.ai/hidream-o1-image/v1/hidream-o1-image-request"
headers = {
    "Content-Type": "application/json",
    "Cache-Control": "no-cache",
    "Ocp-Apim-Subscription-Key": "YOUR_API_KEY"
}
data = {
    "prompt": "A cinematic product photo of a ceramic mug on a marble counter, soft window light, shallow depth of field",
    "image_size": {
        "width": 2048,
        "height": 2048
    },
    "num_inference_steps": 50,
    "guidance_scale": 5,
    "num_images": 1,
    "output_format": "png",
    "enable_safety_checker": true
}

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

```
const url = "https://gateway.pixazo.ai/hidream-o1-image/v1/hidream-o1-image-request";

const data = {
  prompt: "A cinematic product photo of a ceramic mug on a marble counter, soft window light, shallow depth of field",
  image_size: {
    width: 2048,
    height: 2048
  },
  num_inference_steps: 50,
  guidance_scale: 5,
  num_images: 1,
  output_format: "png",
  enable_safety_checker: true
};

fetch(url, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Cache-Control": "no-cache",
    "Ocp-Apim-Subscription-Key": "YOUR_API_KEY"
  },
  body: JSON.stringify(data)
})
.then(response => response.json())
.then(data => console.log(data));
```

```
curl -X POST "https://gateway.pixazo.ai/hidream-o1-image/v1/hidream-o1-image-request" \
  -H "Content-Type: application/json" \
  -H "Cache-Control: no-cache" \
  -H "Ocp-Apim-Subscription-Key: YOUR_API_KEY" \
  --data-raw '{
    "prompt": "A cinematic product photo of a ceramic mug on a marble counter, soft window light, shallow depth of field",
    "image_size": {
        "width": 2048,
        "height": 2048
    },
    "num_inference_steps": 50,
    "guidance_scale": 5,
    "num_images": 1,
    "output_format": "png",
    "enable_safety_checker": true
}'
```

## Output

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

[Try Now](https://api.pixazo.ai/api-details#api=hidream-o1-image&operation=hidream-o1-image-request)

## Webhook (Optional)

Add the `X-Webhook-URL` header to your generate request to receive a POST callback instead of polling.

```
X-Webhook-URL: https://your-server.com/webhook/callback
```

## Request Parameters - HiDream O1 Image generate request

Parameter

Required

Type

Default

Allowed values / range

Description

prompt

Yes

string

—

—

Text prompt for image generation, editing, or subject-driven personalization. Must describe the desired visual content clearly.

reference\_image\_urls

No

string\[\]

\[\]

—

Array of URLs to reference images. Use empty array for text-to-image, one URL for image editing, or multiple URLs for subject-driven personalization.

image\_size

No

enum or {width,height}

square\_hd

square\_hd, square, portrait\_4\_3, portrait\_16\_9, landscape\_4\_3, landscape\_16\_9

Output resolution. Accepts predefined enums: square\_hd, square, portrait\_4\_3, portrait\_16\_9, landscape\_4\_3, landscape\_16\_9. Alternatively, specify exact width and height as an object (e.g., {"width": 2048, "height": 2048}), snapped to nearest supported resolution up to 2048x2048.

num\_inference\_steps

No

integer

50

—

Number of denoising steps during generation. Higher values improve quality but increase processing time.

guidance\_scale

No

float

5

1–15

Classifier-free guidance scale. Controls how closely the output adheres to the prompt. Values typically range from 1 to 15.

seed

No

integer

—

—

Random seed for reproducible results. Use the same seed with identical parameters to generate identical outputs.

num\_images

No

integer

1

1–4

Number of images to generate in a single request. Must be between 1 and 4.

output\_format

No

enum

"png"

jpeg, png, webp

Output image format. Allowed values: jpeg, png, webp.

sync\_mode

No

boolean

false

—

If true, returns base64-encoded data URI instead of a public URL. Use only for small-scale or testing purposes.

enable\_safety\_checker

No

boolean

true

—

Enables or disables the NSFW content filter. Disable only if you are certain your content complies with safety policies.

keep\_original\_aspect

No

boolean

false

—

When exactly one reference\_image\_url is provided, preserves the original aspect ratio of the reference image instead of snapping to image\_size.

## Example Request

```
{
  "prompt": "A cinematic product photo of a ceramic mug on a marble counter, soft window light, shallow depth of field",
  "image_size": {
    "width": 2048,
    "height": 2048
  },
  "num_inference_steps": 50,
  "guidance_scale": 5,
  "num_images": 1,
  "output_format": "png",
  "enable_safety_checker": true
}
```

## Response

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

## Request Headers

Header

Value

Content-Type

application/json

Cache-Control

no-cache

Ocp-Apim-Subscription-Key

YOUR\_API\_KEY

## Response Handling

Common status codes.

Code

Meaning

202

Accepted — Request queued

400

Bad Request

401

Unauthorized

402

Insufficient Balance

403

Forbidden

429

Too Many Requests

500

Internal Server Error

## Error Responses

Queue system errors and model validation errors.

### Queue System Errors

```
// 402 — Insufficient balance
{
  "error": "Insufficient Balance",
  "message": "Your wallet does not have enough balance."
}
```

```
// 400 — Model not found
{
  "error": "Model not found",
  "message": "Model 'hidream-o1-image' not found or is disabled"
}
```

### Error via Status/Webhook

```
{
  "request_id": "hidream-o1-image_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "ERROR",
  "model_id": "hidream-o1-image",
  "error": "Description of the error",
  "output": null
}
```

## Retrieving Results

Poll the universal status endpoint to check progress and retrieve results.

### Endpoint

```
GET https://gateway.pixazo.ai/v2/requests/status/{request_id}
Ocp-Apim-Subscription-Key: YOUR_API_KEY
```

## cURL Example

```
curl -H "Ocp-Apim-Subscription-Key: YOUR_API_KEY" \
  "https://gateway.pixazo.ai/v2/requests/status/hidream-o1-image_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
```

## Response (Completed)

```
{
  "request_id": "hidream-o1-image_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "COMPLETED",
  "model_id": "hidream-o1-image",
  "error": null,
  "output": {
    "media_url": ["https://pub-582b7213209642b9b995c96c95a30381.r2.dev/v1/hidream-o1-image_019dxxxx/output.png"],
    "media_type": "image/png"
  },
  "created_at": "2026-03-31T10:00:00.000Z",
  "updated_at": "2026-03-31T10:00:15.000Z",
  "completed_at": "2026-03-31T10:00:15.000Z"
}
```

## Response Fields

Field

Type

Description

request\_id

string

Unique request identifier

status

string

QUEUED, PROCESSING, COMPLETED, FAILED, or ERROR

model\_id

string

Model that processed the request

error

string|null

Error message if failed

output.media\_url

array

URLs to generated media (R2 CDN)

output.media\_type

string

MIME type of the output

created\_at

string

When request was created

completed\_at

string

When request completed

polling\_url

string

Status URL (initial response only)

## Status Values

Status

Description

QUEUED

Request accepted, waiting to be processed

PROCESSING

Being processed by the model

COMPLETED

Done — output contains the result

FAILED

Failed — check error field

ERROR

System error — not charged

## Status Flow

```
QUEUED → PROCESSING → COMPLETED
                    → FAILED
                    → ERROR
```

## Typical Workflow

1.  **Send a generate request** to the API endpoint
2.  **Save the `request_id`** from the response
3.  **Poll** every 5-10 seconds: `GET /v2/requests/status/{request_id}`
4.  **When `status` is `"COMPLETED"`**, download from `output.media_url`

**Tip:** Use `X-Webhook-URL` header to get a callback instead of polling.

### Image to Image (Image Editing)

## Base URL

```
https://gateway.pixazo.ai/hidream-o1-image-edit/v1
```

## Authentication

All requests require an API key passed via header.

Header

Type

Required

Description

Ocp-Apim-Subscription-Key

string

Yes

Your API subscription key

## HiDream O1 Image (Edit) generate request

## Request Code

HTTP Python JavaScript cURL

```
POST https://gateway.pixazo.ai/hidream-o1-image-edit/v1/hidream-o1-image-edit-request
Content-Type: application/json
Cache-Control: no-cache
Ocp-Apim-Subscription-Key: YOUR_API_KEY

{
  "prompt": "A cinematic product photo of a ceramic mug on a marble counter, soft window light, shallow depth of field",
  "reference_image_urls": [
    "https://example.com/model_tests/hidream/woman.png"
  ],
  "image_size": {
    "width": 2048,
    "height": 2048
  },
  "num_inference_steps": 50,
  "guidance_scale": 5,
  "num_images": 1,
  "output_format": "png",
  "enable_safety_checker": true
}
```

```
import requests

url = "https://gateway.pixazo.ai/hidream-o1-image-edit/v1/hidream-o1-image-edit-request"
headers = {
    "Content-Type": "application/json",
    "Cache-Control": "no-cache",
    "Ocp-Apim-Subscription-Key": "YOUR_API_KEY"
}
data = {
    "prompt": "A cinematic product photo of a ceramic mug on a marble counter, soft window light, shallow depth of field",
    "reference_image_urls": [
        "https://example.com/model_tests/hidream/woman.png"
    ],
    "image_size": {
        "width": 2048,
        "height": 2048
    },
    "num_inference_steps": 50,
    "guidance_scale": 5,
    "num_images": 1,
    "output_format": "png",
    "enable_safety_checker": true
}

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

```
const url = "https://gateway.pixazo.ai/hidream-o1-image-edit/v1/hidream-o1-image-edit-request";
const headers = {
  "Content-Type": "application/json",
  "Cache-Control": "no-cache",
  "Ocp-Apim-Subscription-Key": "YOUR_API_KEY"
};
const data = {
  "prompt": "A cinematic product photo of a ceramic mug on a marble counter, soft window light, shallow depth of field",
  "reference_image_urls": [
    "https://example.com/model_tests/hidream/woman.png"
  ],
  "image_size": {
    "width": 2048,
    "height": 2048
  },
  "num_inference_steps": 50,
  "guidance_scale": 5,
  "num_images": 1,
  "output_format": "png",
  "enable_safety_checker": true
};

fetch(url, {
  method: "POST",
  headers: headers,
  body: JSON.stringify(data)
})
.then(response => response.json())
.then(data => console.log(data));
```

```
curl -X POST "https://gateway.pixazo.ai/hidream-o1-image-edit/v1/hidream-o1-image-edit-request" \
  -H "Content-Type: application/json" \
  -H "Cache-Control: no-cache" \
  -H "Ocp-Apim-Subscription-Key: YOUR_API_KEY" \
  --data-raw '{
    "prompt": "A cinematic product photo of a ceramic mug on a marble counter, soft window light, shallow depth of field",
    "reference_image_urls": [
        "https://example.com/model_tests/hidream/woman.png"
    ],
    "image_size": {
        "width": 2048,
        "height": 2048
    },
    "num_inference_steps": 50,
    "guidance_scale": 5,
    "num_images": 1,
    "output_format": "png",
    "enable_safety_checker": true
}'
```

## Output

```
{
  "request_id": "hidream-o1-image-edit_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "QUEUED",
  "polling_url": "https://gateway.pixazo.ai/v2/requests/status/hidream-o1-image-edit_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}
```

[Try Now](https://api.pixazo.ai/api-details#api=hidream-o1-image-edit&operation=hidream-o1-image-edit-request)

## Webhook (Optional)

Add the `X-Webhook-URL` header to your generate request to receive a POST callback instead of polling.

```
X-Webhook-URL: https://your-server.com/webhook/callback
```

## Request Parameters - HiDream O1 Image (Edit) generate request

Parameter

Required

Type

Default

Allowed values / range

Description

prompt

Yes

string

—

—

Text prompt describing the desired edit or generation. Must be detailed for best results.

reference\_image\_urls

Yes

string\[\]

—

—

Array of URLs to reference images used for editing or subject-driven personalization. Use one image for editing, multiple for multi-subject personalization.

image\_size

No

enum or {width,height}

—

square\_hd, square, portrait\_4\_3, portrait\_16\_9, landscape\_4\_3, landscape\_16\_9

Output resolution. Accepts predefined enums: square\_hd, square, portrait\_4\_3, portrait\_16\_9, landscape\_4\_3, landscape\_16\_9, or a custom object with width and height (both must be ≤ 2048 and snapped to nearest supported resolution).

num\_inference\_steps

No

integer

50

—

Number of denoising steps during generation. Higher values improve quality but increase processing time.

guidance\_scale

No

float

5

1–15

Classifier-free guidance scale. Controls how closely the output follows the prompt. Values typically range from 1 to 15.

seed

No

integer

—

—

Random seed for reproducible results. Use the same seed with identical inputs to generate identical outputs.

num\_images

No

integer

1

1–4

Number of images to generate in a single request. Must be ≥ 1 and ≤ 4.

output\_format

No

enum

"png"

jpeg, png, webp

Output image format. Allowed values: jpeg, png, webp.

sync\_mode

No

boolean

—

—

If true, returns base64-encoded data URI in output.media\_url instead of a public URL. Use for low-latency applications.

enable\_safety\_checker

No

boolean

true

—

Enables or disables the NSFW content filter. Disable only if you are certain your inputs are safe.

keep\_original\_aspect

No

boolean

—

—

When exactly one reference image is provided, preserves its original aspect ratio in the output. Overrides image\_size if specified.

## Example Request

```
{
  "prompt": "A cinematic product photo of a ceramic mug on a marble counter, soft window light, shallow depth of field",
  "reference_image_urls": [
    "https://example.com/model_tests/hidream/woman.png"
  ],
  "image_size": {
    "width": 2048,
    "height": 2048
  },
  "num_inference_steps": 50,
  "guidance_scale": 5,
  "num_images": 1,
  "output_format": "png",
  "enable_safety_checker": true
}
```

## Response

```
{
  "request_id": "hidream-o1-image-edit_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "QUEUED",
  "polling_url": "https://gateway.pixazo.ai/v2/requests/status/hidream-o1-image-edit_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}
```

## Request Headers

Header

Value

Content-Type

application/json

Cache-Control

no-cache

Ocp-Apim-Subscription-Key

YOUR\_API\_KEY

## Response Handling

Common status codes.

Code

Meaning

202

Accepted — Request queued

400

Bad Request

401

Unauthorized

402

Insufficient Balance

403

Forbidden

429

Too Many Requests

500

Internal Server Error

## Error Responses

Queue system errors and model validation errors.

### Queue System Errors

```
// 402 — Insufficient balance
{
  "error": "Insufficient Balance",
  "message": "Your wallet does not have enough balance."
}
```

```
// 400 — Model not found
{
  "error": "Model not found",
  "message": "Model 'hidream-o1-image-edit' not found or is disabled"
}
```

### Error via Status/Webhook

```
{
  "request_id": "hidream-o1-image-edit_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "ERROR",
  "model_id": "hidream-o1-image-edit",
  "error": "Description of the error",
  "output": null
}
```

## Retrieving Results

Poll the universal status endpoint to check progress and retrieve results.

### Endpoint

```
GET https://gateway.pixazo.ai/v2/requests/status/{request_id}
Ocp-Apim-Subscription-Key: YOUR_API_KEY
```

## cURL Example

```
curl -H "Ocp-Apim-Subscription-Key: YOUR_API_KEY" \
  "https://gateway.pixazo.ai/v2/requests/status/hidream-o1-image-edit_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
```

## Response (Completed)

```
{
  "request_id": "hidream-o1-image-edit_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "COMPLETED",
  "model_id": "hidream-o1-image-edit",
  "error": null,
  "output": {
    "media_url": [
      "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/v1/hidream-o1-image-edit_019dxxxx/output.png"
    ],
    "media_type": "image/png"
  },
  "created_at": "2026-03-31T10:00:00.000Z",
  "updated_at": "2026-03-31T10:00:15.000Z",
  "completed_at": "2026-03-31T10:00:15.000Z"
}
```

## Response Fields

Field

Type

Description

request\_id

string

Unique request identifier

status

string

QUEUED, PROCESSING, COMPLETED, FAILED, or ERROR

model\_id

string

Model that processed the request

error

string|null

Error message if failed

output.media\_url

array

URLs to generated media (R2 CDN)

output.media\_type

string

MIME type of the output

created\_at

string

When request was created

completed\_at

string

When request completed

polling\_url

string

Status URL (initial response only)

## Status Values

Status

Description

QUEUED

Request accepted, waiting to be processed

PROCESSING

Being processed by the model

COMPLETED

Done — output contains the result

FAILED

Failed — check error field

ERROR

System error — not charged

## Status Flow

```
QUEUED → PROCESSING → COMPLETED
                    → FAILED
                    → ERROR
```

## Typical Workflow

1.  **Send a generate request** to the API endpoint
2.  **Save the `request_id`** from the response
3.  **Poll** every 5-10 seconds: `GET /v2/requests/status/{request_id}`
4.  **When `status` is `"COMPLETED"`**, download from `output.media_url`

**Tip:** Use `X-Webhook-URL` header to get a callback instead of polling.

## HiDream O1 Dev

### Text to Image

## Base URL

```
https://gateway.pixazo.ai/hidream-o1-image-dev/v1
```

## Authentication

All requests require an API key passed via header.

Header

Type

Required

Description

Ocp-Apim-Subscription-Key

string

Yes

Your API subscription key

## HiDream O1 Image (Dev) generate request

## Request Code

HTTP Python JavaScript cURL

```
POST https://gateway.pixazo.ai/hidream-o1-image-dev/v1/hidream-o1-image-dev-request
Content-Type: application/json
Cache-Control: no-cache
Ocp-Apim-Subscription-Key: YOUR_API_KEY

{
  "prompt": "A cinematic product photo of a ceramic mug on a marble counter, soft window light, shallow depth of field",
  "image_size": {
    "width": 1024,
    "height": 1024
  },
  "num_inference_steps": 28,
  "num_images": 1,
  "output_format": "png",
  "enable_safety_checker": true
}
```

```
import requests

url = "https://gateway.pixazo.ai/hidream-o1-image-dev/v1/hidream-o1-image-dev-request"
headers = {
    "Content-Type": "application/json",
    "Cache-Control": "no-cache",
    "Ocp-Apim-Subscription-Key": "YOUR_API_KEY"
}
data = {
    "prompt": "A cinematic product photo of a ceramic mug on a marble counter, soft window light, shallow depth of field",
    "image_size": {
        "width": 1024,
        "height": 1024
    },
    "num_inference_steps": 28,
    "num_images": 1,
    "output_format": "png",
    "enable_safety_checker": true
}

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

```
const url = "https://gateway.pixazo.ai/hidream-o1-image-dev/v1/hidream-o1-image-dev-request";
const headers = {
  "Content-Type": "application/json",
  "Cache-Control": "no-cache",
  "Ocp-Apim-Subscription-Key": "YOUR_API_KEY"
};
const data = {
  "prompt": "A cinematic product photo of a ceramic mug on a marble counter, soft window light, shallow depth of field",
  "image_size": {
    "width": 1024,
    "height": 1024
  },
  "num_inference_steps": 28,
  "num_images": 1,
  "output_format": "png",
  "enable_safety_checker": true
};

fetch(url, {
  method: "POST",
  headers: headers,
  body: JSON.stringify(data)
})
.then(response => response.json())
.then(data => console.log(data));
```

```
curl -X POST "https://gateway.pixazo.ai/hidream-o1-image-dev/v1/hidream-o1-image-dev-request" \
  -H "Content-Type: application/json" \
  -H "Cache-Control: no-cache" \
  -H "Ocp-Apim-Subscription-Key: YOUR_API_KEY" \
  --data-raw '{
    "prompt": "A cinematic product photo of a ceramic mug on a marble counter, soft window light, shallow depth of field",
    "image_size": {
      "width": 1024,
      "height": 1024
    },
    "num_inference_steps": 28,
    "num_images": 1,
    "output_format": "png",
    "enable_safety_checker": true
  }'
```

## Output

```
{
  "request_id": "hidream-o1-image-dev_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "QUEUED",
  "polling_url": "https://gateway.pixazo.ai/v2/requests/status/hidream-o1-image-dev_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}
```

[Try Now](https://api.pixazo.ai/api-details#api=hidream-o1-image-dev&operation=hidream-o1-image-dev-request)

## Webhook (Optional)

Add the `X-Webhook-URL` header to your generate request to receive a POST callback instead of polling.

```
X-Webhook-URL: https://your-server.com/webhook/callback
```

## Request Parameters - HiDream O1 Image (Dev) generate request

Parameter

Required

Type

Default

Allowed values / range

Description

prompt

Yes

string

—

—

Text prompt for image generation, editing, or subject-driven personalization. Must describe the desired visual content clearly.

reference\_image\_urls

No

string\[\]

—

—

Array of URLs to reference images. Use empty array for text-to-image, one URL for image editing, or multiple URLs for subject-driven personalization.

image\_size

No

enum or {width,height}

square\_hd

square\_hd, square, portrait\_4\_3, portrait\_16\_9, landscape\_4\_3, landscape\_16\_9

Output image dimensions. Allowed enum values: square\_hd, square, portrait\_4\_3, portrait\_16\_9, landscape\_4\_3, landscape\_16\_9. Alternatively, specify exact width and height as integers, rounded down to the nearest multiple of 32, with maximum 2048x2048.

num\_inference\_steps

No

integer

28

—

Number of denoising steps. The distilled model is optimized for 28 steps; increasing beyond this may not improve quality.

guidance\_scale

No

float

0.0

—

Classifier-free guidance scale. The dev model uses 0.0 by default for faster inference; values above 0.0 may increase adherence to prompt but reduce speed.

seed

No

integer

—

—

Random seed for reproducible results. Use the same seed with identical inputs to generate identical outputs.

num\_images

No

integer

1

1–4

Number of images to generate in a single request. Must be between 1 and 4.

output\_format

No

enum

"png"

jpeg, png, webp

Output image format. Allowed values: jpeg, png, webp.

sync\_mode

No

boolean

false

—

If true, returns base64-encoded data URI in output.media\_data instead of a public URL. Use only for small-scale or testing purposes.

enable\_safety\_checker

No

boolean

true

—

Toggle the NSFW content safety checker. Disable only if you are certain your prompts are safe and comply with platform policies.

keep\_original\_aspect

No

boolean

false

—

When exactly one reference\_image\_url is provided, preserve its original aspect ratio instead of conforming to image\_size.

## Example Request

```
{
  "prompt": "A cinematic product photo of a ceramic mug on a marble counter, soft window light, shallow depth of field",
  "image_size": {
    "width": 1024,
    "height": 1024
  },
  "num_inference_steps": 28,
  "num_images": 1,
  "output_format": "png",
  "enable_safety_checker": true
}
```

## Response

```
{
  "request_id": "hidream-o1-image-dev_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "QUEUED",
  "polling_url": "https://gateway.pixazo.ai/v2/requests/status/hidream-o1-image-dev_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}
```

## Request Headers

Header

Value

Content-Type

application/json

Cache-Control

no-cache

Ocp-Apim-Subscription-Key

YOUR\_API\_KEY

## Response Handling

Common status codes.

Code

Meaning

202

Accepted — Request queued

400

Bad Request

401

Unauthorized

402

Insufficient Balance

403

Forbidden

429

Too Many Requests

500

Internal Server Error

## Error Responses

Queue system errors and model validation errors.

### Queue System Errors

```
// 402 — Insufficient balance
{
  "error": "Insufficient Balance",
  "message": "Your wallet does not have enough balance."
}
```

```
// 400 — Model not found
{
  "error": "Model not found",
  "message": "Model 'hidream-o1-image-dev' not found or is disabled"
}
```

### Error via Status/Webhook

```
{
  "request_id": "hidream-o1-image-dev_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "ERROR",
  "model_id": "hidream-o1-image-dev",
  "error": "Description of the error",
  "output": null
}
```

## Retrieving Results

Poll the universal status endpoint to check progress and retrieve results.

### Endpoint

```
GET https://gateway.pixazo.ai/v2/requests/status/{request_id}
Ocp-Apim-Subscription-Key: YOUR_API_KEY
```

## cURL Example

```
curl -H "Ocp-Apim-Subscription-Key: YOUR_API_KEY" \
  "https://gateway.pixazo.ai/v2/requests/status/hidream-o1-image-dev_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
```

## Response (Completed)

```
{
  "request_id": "hidream-o1-image-dev_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "COMPLETED",
  "model_id": "hidream-o1-image-dev",
  "error": null,
  "output": {
    "media_url": ["https://pub-582b7213209642b9b995c96c95a30381.r2.dev/v1/hidream-o1-image-dev_019dxxxx/output.png"],
    "media_type": "image/png"
  },
  "created_at": "2026-03-31T10:00:00.000Z",
  "updated_at": "2026-03-31T10:00:15.000Z",
  "completed_at": "2026-03-31T10:00:15.000Z"
}
```

## Response Fields

Field

Type

Description

request\_id

string

Unique request identifier

status

string

QUEUED, PROCESSING, COMPLETED, FAILED, or ERROR

model\_id

string

Model that processed the request

error

string|null

Error message if failed

output.media\_url

array

URLs to generated media (R2 CDN)

output.media\_type

string

MIME type of the output

created\_at

string

When request was created

completed\_at

string

When request completed

polling\_url

string

Status URL (initial response only)

## Status Values

Status

Description

QUEUED

Request accepted, waiting to be processed

PROCESSING

Being processed by the model

COMPLETED

Done — output contains the result

FAILED

Failed — check error field

ERROR

System error — not charged

## Status Flow

```
QUEUED → PROCESSING → COMPLETED
                    → FAILED
                    → ERROR
```

## Typical Workflow

1.  **Send a generate request** to the API endpoint
2.  **Save the `request_id`** from the response
3.  **Poll** every 5-10 seconds: `GET /v2/requests/status/{request_id}`
4.  **When `status` is `"COMPLETED"`**, download from `output.media_url`

**Tip:** Use `X-Webhook-URL` header to get a callback instead of polling.

### Image to Image (Image Editing)

## Base URL

```
https://gateway.pixazo.ai/hidream-o1-image-dev-edit/v1
```

## Authentication

All requests require an API key passed via header.

Header

Type

Required

Description

Ocp-Apim-Subscription-Key

string

Yes

Your API subscription key

## HiDream O1 Image (Dev Edit) generate request

## Request Code

HTTP Python JavaScript cURL

```
POST https://gateway.pixazo.ai/hidream-o1-image-dev-edit/v1/hidream-o1-image-dev-edit-request
Content-Type: application/json
Cache-Control: no-cache
Ocp-Apim-Subscription-Key: YOUR_API_KEY

{
  "prompt": "A cinematic product photo of a ceramic mug on a marble counter, soft window light, shallow depth of field",
  "reference_image_urls": [
    "https://example.com/model_tests/hidream/woman.png"
  ],
  "image_size": {
    "width": 2048,
    "height": 2048
  },
  "num_inference_steps": 28,
  "num_images": 1,
  "output_format": "png",
  "enable_safety_checker": true
}
```

```
import requests

url = "https://gateway.pixazo.ai/hidream-o1-image-dev-edit/v1/hidream-o1-image-dev-edit-request"
headers = {
    "Content-Type": "application/json",
    "Cache-Control": "no-cache",
    "Ocp-Apim-Subscription-Key": "YOUR_API_KEY"
}
data = {
    "prompt": "A cinematic product photo of a ceramic mug on a marble counter, soft window light, shallow depth of field",
    "reference_image_urls": [
        "https://example.com/model_tests/hidream/woman.png"
    ],
    "image_size": {
        "width": 2048,
        "height": 2048
    },
    "num_inference_steps": 28,
    "num_images": 1,
    "output_format": "png",
    "enable_safety_checker": true
}

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

```
const url = "https://gateway.pixazo.ai/hidream-o1-image-dev-edit/v1/hidream-o1-image-dev-edit-request";
const headers = {
    "Content-Type": "application/json",
    "Cache-Control": "no-cache",
    "Ocp-Apim-Subscription-Key": "YOUR_API_KEY"
};
const data = {
    "prompt": "A cinematic product photo of a ceramic mug on a marble counter, soft window light, shallow depth of field",
    "reference_image_urls": [
        "https://example.com/model_tests/hidream/woman.png"
    ],
    "image_size": {
        "width": 2048,
        "height": 2048
    },
    "num_inference_steps": 28,
    "num_images": 1,
    "output_format": "png",
    "enable_safety_checker": true
};

fetch(url, {
    method: "POST",
    headers: headers,
    body: JSON.stringify(data)
})
.then(response => response.json())
.then(data => console.log(data));
```

```
curl -X POST "https://gateway.pixazo.ai/hidream-o1-image-dev-edit/v1/hidream-o1-image-dev-edit-request" \
  -H "Content-Type: application/json" \
  -H "Cache-Control: no-cache" \
  -H "Ocp-Apim-Subscription-Key: YOUR_API_KEY" \
  --data-raw '{
    "prompt": "A cinematic product photo of a ceramic mug on a marble counter, soft window light, shallow depth of field",
    "reference_image_urls": [
        "https://example.com/model_tests/hidream/woman.png"
    ],
    "image_size": {
        "width": 2048,
        "height": 2048
    },
    "num_inference_steps": 28,
    "num_images": 1,
    "output_format": "png",
    "enable_safety_checker": true
}'
```

## Output

```
{
  "request_id": "hidream-o1-image-dev-edit_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "QUEUED",
  "polling_url": "https://gateway.pixazo.ai/v2/requests/status/hidream-o1-image-dev-edit_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}
```

[Try Now](https://api.pixazo.ai/api-details#api=hidream-o1-image-dev-edit&operation=hidream-o1-image-dev-edit-request)

## Webhook (Optional)

Add the `X-Webhook-URL` header to your generate request to receive a POST callback instead of polling.

```
X-Webhook-URL: https://your-server.com/webhook/callback
```

## Request Parameters - HiDream O1 Image (Dev Edit) generate request

Parameter

Required

Type

Default

Allowed values / range

Description

prompt

Yes

string

—

—

Text prompt describing the desired edit or generation. Must be detailed for best results.

reference\_image\_urls

Yes

string\[\]

—

—

Array of HTTPS URLs to reference images used for editing or subject-driven personalization. Must be publicly accessible.

image\_size

No

object or string

—

square\_hd, square, portrait\_4\_3, portrait\_16\_9, landscape\_4\_3, landscape\_16\_9

Output resolution. Accepts either an object with \`width\` and \`height\` (e.g., \`{ "width": 2048, "height": 2048 }\`) or a preset string. Allowed presets: \`square\_hd\`, \`square\`, \`portrait\_4\_3\`, \`portrait\_16\_9\`, \`landscape\_4\_3\`, \`landscape\_16\_9\`. Values are snapped to nearest supported resolution up to 2048x2048.

num\_inference\_steps

No

integer

28

—

Number of denoising steps. This model is distilled for optimal performance at 28 steps.

guidance\_scale

No

float

0.0

—

Classifier-free guidance scale. The dev edition uses 0.0 by default for faster inference. Values above 0.0 may increase fidelity but slow generation.

seed

No

integer

—

—

Random seed for reproducible results. If omitted, a random seed is used.

num\_images

No

integer

1

—

Number of images to generate in a single request.

output\_format

No

string

"png"

jpeg, png, webp

Output image format. Allowed values: \`jpeg\`, \`png\`, \`webp\`.

sync\_mode

No

boolean

—

—

If \`true\`, returns base64-encoded data URI in \`output.media\_url\` instead of a public URL. If \`false\` or omitted, returns a public URL.

enable\_safety\_checker

No

boolean

true

—

Toggle the NSFW content safety checker. Set to \`false\` to disable filtering.

keep\_original\_aspect

No

boolean

—

—

When exactly one reference image is provided, preserve its original aspect ratio in the output. If omitted, output is resized to match \`image\_size\`.

## Example Request

```
{
  "prompt": "A cinematic product photo of a ceramic mug on a marble counter, soft window light, shallow depth of field",
  "reference_image_urls": [
    "https://example.com/model_tests/hidream/woman.png"
  ],
  "image_size": {
    "width": 2048,
    "height": 2048
  },
  "num_inference_steps": 28,
  "num_images": 1,
  "output_format": "png",
  "enable_safety_checker": true
}
```

## Response

```
{
  "request_id": "hidream-o1-image-dev-edit_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "QUEUED",
  "polling_url": "https://gateway.pixazo.ai/v2/requests/status/hidream-o1-image-dev-edit_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}
```

## Request Headers

Header

Value

Content-Type

application/json

Cache-Control

no-cache

Ocp-Apim-Subscription-Key

YOUR\_API\_KEY

## Response Handling

Common status codes.

Code

Meaning

202

Accepted — Request queued

400

Bad Request

401

Unauthorized

402

Insufficient Balance

403

Forbidden

429

Too Many Requests

500

Internal Server Error

## Error Responses

Queue system errors and model validation errors.

### Queue System Errors

```
// 402 — Insufficient balance
{
  "error": "Insufficient Balance",
  "message": "Your wallet does not have enough balance."
}
```

```
// 400 — Model not found
{
  "error": "Model not found",
  "message": "Model 'hidream-o1-image-dev-edit' not found or is disabled"
}
```

### Error via Status/Webhook

```
{
  "request_id": "hidream-o1-image-dev-edit_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "ERROR",
  "model_id": "hidream-o1-image-dev-edit",
  "error": "Description of the error",
  "output": null
}
```

## Retrieving Results

Poll the universal status endpoint to check progress and retrieve results.

### Endpoint

```
GET https://gateway.pixazo.ai/v2/requests/status/{request_id}
Ocp-Apim-Subscription-Key: YOUR_API_KEY
```

## cURL Example

```
curl -H "Ocp-Apim-Subscription-Key: YOUR_API_KEY" \
  "https://gateway.pixazo.ai/v2/requests/status/hidream-o1-image-dev-edit_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
```

## Response (Completed)

```
{
  "request_id": "hidream-o1-image-dev-edit_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "COMPLETED",
  "model_id": "hidream-o1-image-dev-edit",
  "error": null,
  "output": { "media_url": ["https://pub-582b7213209642b9b995c96c95a30381.r2.dev/v1/hidream-o1-image-dev-edit_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/output.png"], "media_type": "image/png" },
  "created_at": "2026-03-31T10:00:00.000Z",
  "updated_at": "2026-03-31T10:00:15.000Z",
  "completed_at": "2026-03-31T10:00:15.000Z"
}
```

## Response Fields

Field

Type

Description

request\_id

string

Unique request identifier

status

string

QUEUED, PROCESSING, COMPLETED, FAILED, or ERROR

model\_id

string

Model that processed the request

error

string|null

Error message if failed

output.media\_url

array

URLs to generated media (R2 CDN)

output.media\_type

string

MIME type of the output

created\_at

string

When request was created

completed\_at

string

When request completed

polling\_url

string

Status URL (initial response only)

## Status Values

Status

Description

QUEUED

Request accepted, waiting to be processed

PROCESSING

Being processed by the model

COMPLETED

Done — output contains the result

FAILED

Failed — check error field

ERROR

System error — not charged

## Status Flow

```
QUEUED → PROCESSING → COMPLETED
                    → FAILED
                    → ERROR
```

## Typical Workflow

1.  **Send a generate request** to the API endpoint
2.  **Save the `request_id`** from the response
3.  **Poll** every 5-10 seconds: `GET /v2/requests/status/{request_id}`
4.  **When `status` is `"COMPLETED"`**, download from `output.media_url`

**Tip:** Use `X-Webhook-URL` header to get a callback instead of polling.

## HiDream I1 Full

### Text to Image

## Base URL

```
https://gateway.pixazo.ai/hidream-o1-image/v1
```

## Authentication

All requests require an API key passed via header.

Header

Type

Required

Description

Ocp-Apim-Subscription-Key

string

Yes

Your API subscription key

## HiDream O1 Image generate request

## Request Code

HTTP Python JavaScript cURL

```
POST https://gateway.pixazo.ai/hidream-o1-image/v1/hidream-o1-image-request
Content-Type: application/json
Cache-Control: no-cache
Ocp-Apim-Subscription-Key: YOUR_API_KEY

{
  "prompt": "A cinematic product photo of a ceramic mug on a marble counter, soft window light, shallow depth of field",
  "image_size": {
    "width": 2048,
    "height": 2048
  },
  "num_inference_steps": 50,
  "guidance_scale": 5,
  "num_images": 1,
  "output_format": "png",
  "enable_safety_checker": true
}
```

```
import requests

url = "https://gateway.pixazo.ai/hidream-o1-image/v1/hidream-o1-image-request"
headers = {
    "Content-Type": "application/json",
    "Cache-Control": "no-cache",
    "Ocp-Apim-Subscription-Key": "YOUR_API_KEY"
}
data = {
    "prompt": "A cinematic product photo of a ceramic mug on a marble counter, soft window light, shallow depth of field",
    "image_size": {
        "width": 2048,
        "height": 2048
    },
    "num_inference_steps": 50,
    "guidance_scale": 5,
    "num_images": 1,
    "output_format": "png",
    "enable_safety_checker": true
}

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

```
const url = "https://gateway.pixazo.ai/hidream-o1-image/v1/hidream-o1-image-request";

const data = {
  prompt: "A cinematic product photo of a ceramic mug on a marble counter, soft window light, shallow depth of field",
  image_size: {
    width: 2048,
    height: 2048
  },
  num_inference_steps: 50,
  guidance_scale: 5,
  num_images: 1,
  output_format: "png",
  enable_safety_checker: true
};

fetch(url, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Cache-Control": "no-cache",
    "Ocp-Apim-Subscription-Key": "YOUR_API_KEY"
  },
  body: JSON.stringify(data)
})
.then(response => response.json())
.then(data => console.log(data));
```

```
curl -X POST "https://gateway.pixazo.ai/hidream-o1-image/v1/hidream-o1-image-request" \
  -H "Content-Type: application/json" \
  -H "Cache-Control: no-cache" \
  -H "Ocp-Apim-Subscription-Key: YOUR_API_KEY" \
  --data-raw '{
    "prompt": "A cinematic product photo of a ceramic mug on a marble counter, soft window light, shallow depth of field",
    "image_size": {
        "width": 2048,
        "height": 2048
    },
    "num_inference_steps": 50,
    "guidance_scale": 5,
    "num_images": 1,
    "output_format": "png",
    "enable_safety_checker": true
}'
```

## Output

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

[Try Now](https://api.pixazo.ai/api-details#api=hidream-o1-image&operation=hidream-o1-image-request)

## Webhook (Optional)

Add the `X-Webhook-URL` header to your generate request to receive a POST callback instead of polling.

```
X-Webhook-URL: https://your-server.com/webhook/callback
```

## Request Parameters - HiDream O1 Image generate request

Parameter

Required

Type

Default

Allowed values / range

Description

prompt

Yes

string

—

—

Text prompt for image generation, editing, or subject-driven personalization. Must describe the desired visual content clearly.

reference\_image\_urls

No

string\[\]

\[\]

—

Array of URLs to reference images. Use empty array for text-to-image, one URL for image editing, or multiple URLs for subject-driven personalization.

image\_size

No

enum or {width,height}

square\_hd

square\_hd, square, portrait\_4\_3, portrait\_16\_9, landscape\_4\_3, landscape\_16\_9

Output resolution. Accepts predefined enums: square\_hd, square, portrait\_4\_3, portrait\_16\_9, landscape\_4\_3, landscape\_16\_9. Alternatively, specify exact width and height as an object (e.g., {"width": 2048, "height": 2048}), snapped to nearest supported resolution up to 2048x2048.

num\_inference\_steps

No

integer

50

—

Number of denoising steps during generation. Higher values improve quality but increase processing time.

guidance\_scale

No

float

5

1–15

Classifier-free guidance scale. Controls how closely the output adheres to the prompt. Values typically range from 1 to 15.

seed

No

integer

—

—

Random seed for reproducible results. Use the same seed with identical parameters to generate identical outputs.

num\_images

No

integer

1

1–4

Number of images to generate in a single request. Must be between 1 and 4.

output\_format

No

enum

"png"

jpeg, png, webp

Output image format. Allowed values: jpeg, png, webp.

sync\_mode

No

boolean

false

—

If true, returns base64-encoded data URI instead of a public URL. Use only for small-scale or testing purposes.

enable\_safety\_checker

No

boolean

true

—

Enables or disables the NSFW content filter. Disable only if you are certain your content complies with safety policies.

keep\_original\_aspect

No

boolean

false

—

When exactly one reference\_image\_url is provided, preserves the original aspect ratio of the reference image instead of snapping to image\_size.

## Example Request

```
{
  "prompt": "A cinematic product photo of a ceramic mug on a marble counter, soft window light, shallow depth of field",
  "image_size": {
    "width": 2048,
    "height": 2048
  },
  "num_inference_steps": 50,
  "guidance_scale": 5,
  "num_images": 1,
  "output_format": "png",
  "enable_safety_checker": true
}
```

## Response

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

## Request Headers

Header

Value

Content-Type

application/json

Cache-Control

no-cache

Ocp-Apim-Subscription-Key

YOUR\_API\_KEY

## Response Handling

Common status codes.

Code

Meaning

202

Accepted — Request queued

400

Bad Request

401

Unauthorized

402

Insufficient Balance

403

Forbidden

429

Too Many Requests

500

Internal Server Error

## Error Responses

Queue system errors and model validation errors.

### Queue System Errors

```
// 402 — Insufficient balance
{
  "error": "Insufficient Balance",
  "message": "Your wallet does not have enough balance."
}
```

```
// 400 — Model not found
{
  "error": "Model not found",
  "message": "Model 'hidream-o1-image' not found or is disabled"
}
```

### Error via Status/Webhook

```
{
  "request_id": "hidream-o1-image_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "ERROR",
  "model_id": "hidream-o1-image",
  "error": "Description of the error",
  "output": null
}
```

## Retrieving Results

Poll the universal status endpoint to check progress and retrieve results.

### Endpoint

```
GET https://gateway.pixazo.ai/v2/requests/status/{request_id}
Ocp-Apim-Subscription-Key: YOUR_API_KEY
```

## cURL Example

```
curl -H "Ocp-Apim-Subscription-Key: YOUR_API_KEY" \
  "https://gateway.pixazo.ai/v2/requests/status/hidream-o1-image_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
```

## Response (Completed)

```
{
  "request_id": "hidream-o1-image_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "COMPLETED",
  "model_id": "hidream-o1-image",
  "error": null,
  "output": {
    "media_url": ["https://pub-582b7213209642b9b995c96c95a30381.r2.dev/v1/hidream-o1-image_019dxxxx/output.png"],
    "media_type": "image/png"
  },
  "created_at": "2026-03-31T10:00:00.000Z",
  "updated_at": "2026-03-31T10:00:15.000Z",
  "completed_at": "2026-03-31T10:00:15.000Z"
}
```

## Response Fields

Field

Type

Description

request\_id

string

Unique request identifier

status

string

QUEUED, PROCESSING, COMPLETED, FAILED, or ERROR

model\_id

string

Model that processed the request

error

string|null

Error message if failed

output.media\_url

array

URLs to generated media (R2 CDN)

output.media\_type

string

MIME type of the output

created\_at

string

When request was created

completed\_at

string

When request completed

polling\_url

string

Status URL (initial response only)

## Status Values

Status

Description

QUEUED

Request accepted, waiting to be processed

PROCESSING

Being processed by the model

COMPLETED

Done — output contains the result

FAILED

Failed — check error field

ERROR

System error — not charged

## Status Flow

```
QUEUED → PROCESSING → COMPLETED
                    → FAILED
                    → ERROR
```

## Typical Workflow

1.  **Send a generate request** to the API endpoint
2.  **Save the `request_id`** from the response
3.  **Poll** every 5-10 seconds: `GET /v2/requests/status/{request_id}`
4.  **When `status` is `"COMPLETED"`**, download from `output.media_url`

**Tip:** Use `X-Webhook-URL` header to get a callback instead of polling.

### Image to Image (Image Editing)

## Base URL

```
https://gateway.pixazo.ai/hidream-o1-image-edit/v1
```

## Authentication

All requests require an API key passed via header.

Header

Type

Required

Description

Ocp-Apim-Subscription-Key

string

Yes

Your API subscription key

## HiDream O1 Image (Edit) generate request

## Request Code

HTTP Python JavaScript cURL

```
POST https://gateway.pixazo.ai/hidream-o1-image-edit/v1/hidream-o1-image-edit-request
Content-Type: application/json
Cache-Control: no-cache
Ocp-Apim-Subscription-Key: YOUR_API_KEY

{
  "prompt": "A cinematic product photo of a ceramic mug on a marble counter, soft window light, shallow depth of field",
  "reference_image_urls": [
    "https://example.com/model_tests/hidream/woman.png"
  ],
  "image_size": {
    "width": 2048,
    "height": 2048
  },
  "num_inference_steps": 50,
  "guidance_scale": 5,
  "num_images": 1,
  "output_format": "png",
  "enable_safety_checker": true
}
```

```
import requests

url = "https://gateway.pixazo.ai/hidream-o1-image-edit/v1/hidream-o1-image-edit-request"
headers = {
    "Content-Type": "application/json",
    "Cache-Control": "no-cache",
    "Ocp-Apim-Subscription-Key": "YOUR_API_KEY"
}
data = {
    "prompt": "A cinematic product photo of a ceramic mug on a marble counter, soft window light, shallow depth of field",
    "reference_image_urls": [
        "https://example.com/model_tests/hidream/woman.png"
    ],
    "image_size": {
        "width": 2048,
        "height": 2048
    },
    "num_inference_steps": 50,
    "guidance_scale": 5,
    "num_images": 1,
    "output_format": "png",
    "enable_safety_checker": true
}

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

```
const url = "https://gateway.pixazo.ai/hidream-o1-image-edit/v1/hidream-o1-image-edit-request";
const headers = {
  "Content-Type": "application/json",
  "Cache-Control": "no-cache",
  "Ocp-Apim-Subscription-Key": "YOUR_API_KEY"
};
const data = {
  "prompt": "A cinematic product photo of a ceramic mug on a marble counter, soft window light, shallow depth of field",
  "reference_image_urls": [
    "https://example.com/model_tests/hidream/woman.png"
  ],
  "image_size": {
    "width": 2048,
    "height": 2048
  },
  "num_inference_steps": 50,
  "guidance_scale": 5,
  "num_images": 1,
  "output_format": "png",
  "enable_safety_checker": true
};

fetch(url, {
  method: "POST",
  headers: headers,
  body: JSON.stringify(data)
})
.then(response => response.json())
.then(data => console.log(data));
```

```
curl -X POST "https://gateway.pixazo.ai/hidream-o1-image-edit/v1/hidream-o1-image-edit-request" \
  -H "Content-Type: application/json" \
  -H "Cache-Control: no-cache" \
  -H "Ocp-Apim-Subscription-Key: YOUR_API_KEY" \
  --data-raw '{
    "prompt": "A cinematic product photo of a ceramic mug on a marble counter, soft window light, shallow depth of field",
    "reference_image_urls": [
        "https://example.com/model_tests/hidream/woman.png"
    ],
    "image_size": {
        "width": 2048,
        "height": 2048
    },
    "num_inference_steps": 50,
    "guidance_scale": 5,
    "num_images": 1,
    "output_format": "png",
    "enable_safety_checker": true
}'
```

## Output

```
{
  "request_id": "hidream-o1-image-edit_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "QUEUED",
  "polling_url": "https://gateway.pixazo.ai/v2/requests/status/hidream-o1-image-edit_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}
```

[Try Now](https://api.pixazo.ai/api-details#api=hidream-o1-image-edit&operation=hidream-o1-image-edit-request)

## Webhook (Optional)

Add the `X-Webhook-URL` header to your generate request to receive a POST callback instead of polling.

```
X-Webhook-URL: https://your-server.com/webhook/callback
```

## Request Parameters - HiDream O1 Image (Edit) generate request

Parameter

Required

Type

Default

Allowed values / range

Description

prompt

Yes

string

—

—

Text prompt describing the desired edit or generation. Must be detailed for best results.

reference\_image\_urls

Yes

string\[\]

—

—

Array of URLs to reference images used for editing or subject-driven personalization. Use one image for editing, multiple for multi-subject personalization.

image\_size

No

enum or {width,height}

—

square\_hd, square, portrait\_4\_3, portrait\_16\_9, landscape\_4\_3, landscape\_16\_9

Output resolution. Accepts predefined enums: square\_hd, square, portrait\_4\_3, portrait\_16\_9, landscape\_4\_3, landscape\_16\_9, or a custom object with width and height (both must be ≤ 2048 and snapped to nearest supported resolution).

num\_inference\_steps

No

integer

50

—

Number of denoising steps during generation. Higher values improve quality but increase processing time.

guidance\_scale

No

float

5

1–15

Classifier-free guidance scale. Controls how closely the output follows the prompt. Values typically range from 1 to 15.

seed

No

integer

—

—

Random seed for reproducible results. Use the same seed with identical inputs to generate identical outputs.

num\_images

No

integer

1

1–4

Number of images to generate in a single request. Must be ≥ 1 and ≤ 4.

output\_format

No

enum

"png"

jpeg, png, webp

Output image format. Allowed values: jpeg, png, webp.

sync\_mode

No

boolean

—

—

If true, returns base64-encoded data URI in output.media\_url instead of a public URL. Use for low-latency applications.

enable\_safety\_checker

No

boolean

true

—

Enables or disables the NSFW content filter. Disable only if you are certain your inputs are safe.

keep\_original\_aspect

No

boolean

—

—

When exactly one reference image is provided, preserves its original aspect ratio in the output. Overrides image\_size if specified.

## Example Request

```
{
  "prompt": "A cinematic product photo of a ceramic mug on a marble counter, soft window light, shallow depth of field",
  "reference_image_urls": [
    "https://example.com/model_tests/hidream/woman.png"
  ],
  "image_size": {
    "width": 2048,
    "height": 2048
  },
  "num_inference_steps": 50,
  "guidance_scale": 5,
  "num_images": 1,
  "output_format": "png",
  "enable_safety_checker": true
}
```

## Response

```
{
  "request_id": "hidream-o1-image-edit_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "QUEUED",
  "polling_url": "https://gateway.pixazo.ai/v2/requests/status/hidream-o1-image-edit_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}
```

## Request Headers

Header

Value

Content-Type

application/json

Cache-Control

no-cache

Ocp-Apim-Subscription-Key

YOUR\_API\_KEY

## Response Handling

Common status codes.

Code

Meaning

202

Accepted — Request queued

400

Bad Request

401

Unauthorized

402

Insufficient Balance

403

Forbidden

429

Too Many Requests

500

Internal Server Error

## Error Responses

Queue system errors and model validation errors.

### Queue System Errors

```
// 402 — Insufficient balance
{
  "error": "Insufficient Balance",
  "message": "Your wallet does not have enough balance."
}
```

```
// 400 — Model not found
{
  "error": "Model not found",
  "message": "Model 'hidream-o1-image-edit' not found or is disabled"
}
```

### Error via Status/Webhook

```
{
  "request_id": "hidream-o1-image-edit_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "ERROR",
  "model_id": "hidream-o1-image-edit",
  "error": "Description of the error",
  "output": null
}
```

## Retrieving Results

Poll the universal status endpoint to check progress and retrieve results.

### Endpoint

```
GET https://gateway.pixazo.ai/v2/requests/status/{request_id}
Ocp-Apim-Subscription-Key: YOUR_API_KEY
```

## cURL Example

```
curl -H "Ocp-Apim-Subscription-Key: YOUR_API_KEY" \
  "https://gateway.pixazo.ai/v2/requests/status/hidream-o1-image-edit_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
```

## Response (Completed)

```
{
  "request_id": "hidream-o1-image-edit_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "COMPLETED",
  "model_id": "hidream-o1-image-edit",
  "error": null,
  "output": {
    "media_url": [
      "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/v1/hidream-o1-image-edit_019dxxxx/output.png"
    ],
    "media_type": "image/png"
  },
  "created_at": "2026-03-31T10:00:00.000Z",
  "updated_at": "2026-03-31T10:00:15.000Z",
  "completed_at": "2026-03-31T10:00:15.000Z"
}
```

## Response Fields

Field

Type

Description

request\_id

string

Unique request identifier

status

string

QUEUED, PROCESSING, COMPLETED, FAILED, or ERROR

model\_id

string

Model that processed the request

error

string|null

Error message if failed

output.media\_url

array

URLs to generated media (R2 CDN)

output.media\_type

string

MIME type of the output

created\_at

string

When request was created

completed\_at

string

When request completed

polling\_url

string

Status URL (initial response only)

## Status Values

Status

Description

QUEUED

Request accepted, waiting to be processed

PROCESSING

Being processed by the model

COMPLETED

Done — output contains the result

FAILED

Failed — check error field

ERROR

System error — not charged

## Status Flow

```
QUEUED → PROCESSING → COMPLETED
                    → FAILED
                    → ERROR
```

## Typical Workflow

1.  **Send a generate request** to the API endpoint
2.  **Save the `request_id`** from the response
3.  **Poll** every 5-10 seconds: `GET /v2/requests/status/{request_id}`
4.  **When `status` is `"COMPLETED"`**, download from `output.media_url`

**Tip:** Use `X-Webhook-URL` header to get a callback instead of polling.

## HiDream O1 Dev

### Text to Image

## Base URL

```
https://gateway.pixazo.ai/hidream-o1-image-dev/v1
```

## Authentication

All requests require an API key passed via header.

Header

Type

Required

Description

Ocp-Apim-Subscription-Key

string

Yes

Your API subscription key

## HiDream O1 Image (Dev) generate request

## Request Code

HTTP Python JavaScript cURL

```
POST https://gateway.pixazo.ai/hidream-o1-image-dev/v1/hidream-o1-image-dev-request
Content-Type: application/json
Cache-Control: no-cache
Ocp-Apim-Subscription-Key: YOUR_API_KEY

{
  "prompt": "A cinematic product photo of a ceramic mug on a marble counter, soft window light, shallow depth of field",
  "image_size": {
    "width": 1024,
    "height": 1024
  },
  "num_inference_steps": 28,
  "num_images": 1,
  "output_format": "png",
  "enable_safety_checker": true
}
```

```
import requests

url = "https://gateway.pixazo.ai/hidream-o1-image-dev/v1/hidream-o1-image-dev-request"
headers = {
    "Content-Type": "application/json",
    "Cache-Control": "no-cache",
    "Ocp-Apim-Subscription-Key": "YOUR_API_KEY"
}
data = {
    "prompt": "A cinematic product photo of a ceramic mug on a marble counter, soft window light, shallow depth of field",
    "image_size": {
        "width": 1024,
        "height": 1024
    },
    "num_inference_steps": 28,
    "num_images": 1,
    "output_format": "png",
    "enable_safety_checker": true
}

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

```
const url = "https://gateway.pixazo.ai/hidream-o1-image-dev/v1/hidream-o1-image-dev-request";
const headers = {
  "Content-Type": "application/json",
  "Cache-Control": "no-cache",
  "Ocp-Apim-Subscription-Key": "YOUR_API_KEY"
};
const data = {
  "prompt": "A cinematic product photo of a ceramic mug on a marble counter, soft window light, shallow depth of field",
  "image_size": {
    "width": 1024,
    "height": 1024
  },
  "num_inference_steps": 28,
  "num_images": 1,
  "output_format": "png",
  "enable_safety_checker": true
};

fetch(url, {
  method: "POST",
  headers: headers,
  body: JSON.stringify(data)
})
.then(response => response.json())
.then(data => console.log(data));
```

```
curl -X POST "https://gateway.pixazo.ai/hidream-o1-image-dev/v1/hidream-o1-image-dev-request" \
  -H "Content-Type: application/json" \
  -H "Cache-Control: no-cache" \
  -H "Ocp-Apim-Subscription-Key: YOUR_API_KEY" \
  --data-raw '{
    "prompt": "A cinematic product photo of a ceramic mug on a marble counter, soft window light, shallow depth of field",
    "image_size": {
      "width": 1024,
      "height": 1024
    },
    "num_inference_steps": 28,
    "num_images": 1,
    "output_format": "png",
    "enable_safety_checker": true
  }'
```

## Output

```
{
  "request_id": "hidream-o1-image-dev_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "QUEUED",
  "polling_url": "https://gateway.pixazo.ai/v2/requests/status/hidream-o1-image-dev_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}
```

[Try Now](https://api.pixazo.ai/api-details#api=hidream-o1-image-dev&operation=hidream-o1-image-dev-request)

## Webhook (Optional)

Add the `X-Webhook-URL` header to your generate request to receive a POST callback instead of polling.

```
X-Webhook-URL: https://your-server.com/webhook/callback
```

## Request Parameters - HiDream O1 Image (Dev) generate request

Parameter

Required

Type

Default

Allowed values / range

Description

prompt

Yes

string

—

—

Text prompt for image generation, editing, or subject-driven personalization. Must describe the desired visual content clearly.

reference\_image\_urls

No

string\[\]

—

—

Array of URLs to reference images. Use empty array for text-to-image, one URL for image editing, or multiple URLs for subject-driven personalization.

image\_size

No

enum or {width,height}

square\_hd

square\_hd, square, portrait\_4\_3, portrait\_16\_9, landscape\_4\_3, landscape\_16\_9

Output image dimensions. Allowed enum values: square\_hd, square, portrait\_4\_3, portrait\_16\_9, landscape\_4\_3, landscape\_16\_9. Alternatively, specify exact width and height as integers, rounded down to the nearest multiple of 32, with maximum 2048x2048.

num\_inference\_steps

No

integer

28

—

Number of denoising steps. The distilled model is optimized for 28 steps; increasing beyond this may not improve quality.

guidance\_scale

No

float

0.0

—

Classifier-free guidance scale. The dev model uses 0.0 by default for faster inference; values above 0.0 may increase adherence to prompt but reduce speed.

seed

No

integer

—

—

Random seed for reproducible results. Use the same seed with identical inputs to generate identical outputs.

num\_images

No

integer

1

1–4

Number of images to generate in a single request. Must be between 1 and 4.

output\_format

No

enum

"png"

jpeg, png, webp

Output image format. Allowed values: jpeg, png, webp.

sync\_mode

No

boolean

false

—

If true, returns base64-encoded data URI in output.media\_data instead of a public URL. Use only for small-scale or testing purposes.

enable\_safety\_checker

No

boolean

true

—

Toggle the NSFW content safety checker. Disable only if you are certain your prompts are safe and comply with platform policies.

keep\_original\_aspect

No

boolean

false

—

When exactly one reference\_image\_url is provided, preserve its original aspect ratio instead of conforming to image\_size.

## Example Request

```
{
  "prompt": "A cinematic product photo of a ceramic mug on a marble counter, soft window light, shallow depth of field",
  "image_size": {
    "width": 1024,
    "height": 1024
  },
  "num_inference_steps": 28,
  "num_images": 1,
  "output_format": "png",
  "enable_safety_checker": true
}
```

## Response

```
{
  "request_id": "hidream-o1-image-dev_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "QUEUED",
  "polling_url": "https://gateway.pixazo.ai/v2/requests/status/hidream-o1-image-dev_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}
```

## Request Headers

Header

Value

Content-Type

application/json

Cache-Control

no-cache

Ocp-Apim-Subscription-Key

YOUR\_API\_KEY

## Response Handling

Common status codes.

Code

Meaning

202

Accepted — Request queued

400

Bad Request

401

Unauthorized

402

Insufficient Balance

403

Forbidden

429

Too Many Requests

500

Internal Server Error

## Error Responses

Queue system errors and model validation errors.

### Queue System Errors

```
// 402 — Insufficient balance
{
  "error": "Insufficient Balance",
  "message": "Your wallet does not have enough balance."
}
```

```
// 400 — Model not found
{
  "error": "Model not found",
  "message": "Model 'hidream-o1-image-dev' not found or is disabled"
}
```

### Error via Status/Webhook

```
{
  "request_id": "hidream-o1-image-dev_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "ERROR",
  "model_id": "hidream-o1-image-dev",
  "error": "Description of the error",
  "output": null
}
```

## Retrieving Results

Poll the universal status endpoint to check progress and retrieve results.

### Endpoint

```
GET https://gateway.pixazo.ai/v2/requests/status/{request_id}
Ocp-Apim-Subscription-Key: YOUR_API_KEY
```

## cURL Example

```
curl -H "Ocp-Apim-Subscription-Key: YOUR_API_KEY" \
  "https://gateway.pixazo.ai/v2/requests/status/hidream-o1-image-dev_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
```

## Response (Completed)

```
{
  "request_id": "hidream-o1-image-dev_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "COMPLETED",
  "model_id": "hidream-o1-image-dev",
  "error": null,
  "output": {
    "media_url": ["https://pub-582b7213209642b9b995c96c95a30381.r2.dev/v1/hidream-o1-image-dev_019dxxxx/output.png"],
    "media_type": "image/png"
  },
  "created_at": "2026-03-31T10:00:00.000Z",
  "updated_at": "2026-03-31T10:00:15.000Z",
  "completed_at": "2026-03-31T10:00:15.000Z"
}
```

## Response Fields

Field

Type

Description

request\_id

string

Unique request identifier

status

string

QUEUED, PROCESSING, COMPLETED, FAILED, or ERROR

model\_id

string

Model that processed the request

error

string|null

Error message if failed

output.media\_url

array

URLs to generated media (R2 CDN)

output.media\_type

string

MIME type of the output

created\_at

string

When request was created

completed\_at

string

When request completed

polling\_url

string

Status URL (initial response only)

## Status Values

Status

Description

QUEUED

Request accepted, waiting to be processed

PROCESSING

Being processed by the model

COMPLETED

Done — output contains the result

FAILED

Failed — check error field

ERROR

System error — not charged

## Status Flow

```
QUEUED → PROCESSING → COMPLETED
                    → FAILED
                    → ERROR
```

## Typical Workflow

1.  **Send a generate request** to the API endpoint
2.  **Save the `request_id`** from the response
3.  **Poll** every 5-10 seconds: `GET /v2/requests/status/{request_id}`
4.  **When `status` is `"COMPLETED"`**, download from `output.media_url`

**Tip:** Use `X-Webhook-URL` header to get a callback instead of polling.

### Image to Image (Image Editing)

## Base URL

```
https://gateway.pixazo.ai/hidream-o1-image-dev-edit/v1
```

## Authentication

All requests require an API key passed via header.

Header

Type

Required

Description

Ocp-Apim-Subscription-Key

string

Yes

Your API subscription key

## HiDream O1 Image (Dev Edit) generate request

## Request Code

HTTP Python JavaScript cURL

```
POST https://gateway.pixazo.ai/hidream-o1-image-dev-edit/v1/hidream-o1-image-dev-edit-request
Content-Type: application/json
Cache-Control: no-cache
Ocp-Apim-Subscription-Key: YOUR_API_KEY

{
  "prompt": "A cinematic product photo of a ceramic mug on a marble counter, soft window light, shallow depth of field",
  "reference_image_urls": [
    "https://example.com/model_tests/hidream/woman.png"
  ],
  "image_size": {
    "width": 2048,
    "height": 2048
  },
  "num_inference_steps": 28,
  "num_images": 1,
  "output_format": "png",
  "enable_safety_checker": true
}
```

```
import requests

url = "https://gateway.pixazo.ai/hidream-o1-image-dev-edit/v1/hidream-o1-image-dev-edit-request"
headers = {
    "Content-Type": "application/json",
    "Cache-Control": "no-cache",
    "Ocp-Apim-Subscription-Key": "YOUR_API_KEY"
}
data = {
    "prompt": "A cinematic product photo of a ceramic mug on a marble counter, soft window light, shallow depth of field",
    "reference_image_urls": [
        "https://example.com/model_tests/hidream/woman.png"
    ],
    "image_size": {
        "width": 2048,
        "height": 2048
    },
    "num_inference_steps": 28,
    "num_images": 1,
    "output_format": "png",
    "enable_safety_checker": true
}

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

```
const url = "https://gateway.pixazo.ai/hidream-o1-image-dev-edit/v1/hidream-o1-image-dev-edit-request";
const headers = {
    "Content-Type": "application/json",
    "Cache-Control": "no-cache",
    "Ocp-Apim-Subscription-Key": "YOUR_API_KEY"
};
const data = {
    "prompt": "A cinematic product photo of a ceramic mug on a marble counter, soft window light, shallow depth of field",
    "reference_image_urls": [
        "https://example.com/model_tests/hidream/woman.png"
    ],
    "image_size": {
        "width": 2048,
        "height": 2048
    },
    "num_inference_steps": 28,
    "num_images": 1,
    "output_format": "png",
    "enable_safety_checker": true
};

fetch(url, {
    method: "POST",
    headers: headers,
    body: JSON.stringify(data)
})
.then(response => response.json())
.then(data => console.log(data));
```

```
curl -X POST "https://gateway.pixazo.ai/hidream-o1-image-dev-edit/v1/hidream-o1-image-dev-edit-request" \
  -H "Content-Type: application/json" \
  -H "Cache-Control: no-cache" \
  -H "Ocp-Apim-Subscription-Key: YOUR_API_KEY" \
  --data-raw '{
    "prompt": "A cinematic product photo of a ceramic mug on a marble counter, soft window light, shallow depth of field",
    "reference_image_urls": [
        "https://example.com/model_tests/hidream/woman.png"
    ],
    "image_size": {
        "width": 2048,
        "height": 2048
    },
    "num_inference_steps": 28,
    "num_images": 1,
    "output_format": "png",
    "enable_safety_checker": true
}'
```

## Output

```
{
  "request_id": "hidream-o1-image-dev-edit_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "QUEUED",
  "polling_url": "https://gateway.pixazo.ai/v2/requests/status/hidream-o1-image-dev-edit_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}
```

[Try Now](https://api.pixazo.ai/api-details#api=hidream-o1-image-dev-edit&operation=hidream-o1-image-dev-edit-request)

## Webhook (Optional)

Add the `X-Webhook-URL` header to your generate request to receive a POST callback instead of polling.

```
X-Webhook-URL: https://your-server.com/webhook/callback
```

## Request Parameters - HiDream O1 Image (Dev Edit) generate request

Parameter

Required

Type

Default

Allowed values / range

Description

prompt

Yes

string

—

—

Text prompt describing the desired edit or generation. Must be detailed for best results.

reference\_image\_urls

Yes

string\[\]

—

—

Array of HTTPS URLs to reference images used for editing or subject-driven personalization. Must be publicly accessible.

image\_size

No

object or string

—

square\_hd, square, portrait\_4\_3, portrait\_16\_9, landscape\_4\_3, landscape\_16\_9

Output resolution. Accepts either an object with \`width\` and \`height\` (e.g., \`{ "width": 2048, "height": 2048 }\`) or a preset string. Allowed presets: \`square\_hd\`, \`square\`, \`portrait\_4\_3\`, \`portrait\_16\_9\`, \`landscape\_4\_3\`, \`landscape\_16\_9\`. Values are snapped to nearest supported resolution up to 2048x2048.

num\_inference\_steps

No

integer

28

—

Number of denoising steps. This model is distilled for optimal performance at 28 steps.

guidance\_scale

No

float

0.0

—

Classifier-free guidance scale. The dev edition uses 0.0 by default for faster inference. Values above 0.0 may increase fidelity but slow generation.

seed

No

integer

—

—

Random seed for reproducible results. If omitted, a random seed is used.

num\_images

No

integer

1

—

Number of images to generate in a single request.

output\_format

No

string

"png"

jpeg, png, webp

Output image format. Allowed values: \`jpeg\`, \`png\`, \`webp\`.

sync\_mode

No

boolean

—

—

If \`true\`, returns base64-encoded data URI in \`output.media\_url\` instead of a public URL. If \`false\` or omitted, returns a public URL.

enable\_safety\_checker

No

boolean

true

—

Toggle the NSFW content safety checker. Set to \`false\` to disable filtering.

keep\_original\_aspect

No

boolean

—

—

When exactly one reference image is provided, preserve its original aspect ratio in the output. If omitted, output is resized to match \`image\_size\`.

## Example Request

```
{
  "prompt": "A cinematic product photo of a ceramic mug on a marble counter, soft window light, shallow depth of field",
  "reference_image_urls": [
    "https://example.com/model_tests/hidream/woman.png"
  ],
  "image_size": {
    "width": 2048,
    "height": 2048
  },
  "num_inference_steps": 28,
  "num_images": 1,
  "output_format": "png",
  "enable_safety_checker": true
}
```

## Response

```
{
  "request_id": "hidream-o1-image-dev-edit_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "QUEUED",
  "polling_url": "https://gateway.pixazo.ai/v2/requests/status/hidream-o1-image-dev-edit_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}
```

## Request Headers

Header

Value

Content-Type

application/json

Cache-Control

no-cache

Ocp-Apim-Subscription-Key

YOUR\_API\_KEY

## Response Handling

Common status codes.

Code

Meaning

202

Accepted — Request queued

400

Bad Request

401

Unauthorized

402

Insufficient Balance

403

Forbidden

429

Too Many Requests

500

Internal Server Error

## Error Responses

Queue system errors and model validation errors.

### Queue System Errors

```
// 402 — Insufficient balance
{
  "error": "Insufficient Balance",
  "message": "Your wallet does not have enough balance."
}
```

```
// 400 — Model not found
{
  "error": "Model not found",
  "message": "Model 'hidream-o1-image-dev-edit' not found or is disabled"
}
```

### Error via Status/Webhook

```
{
  "request_id": "hidream-o1-image-dev-edit_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "ERROR",
  "model_id": "hidream-o1-image-dev-edit",
  "error": "Description of the error",
  "output": null
}
```

## Retrieving Results

Poll the universal status endpoint to check progress and retrieve results.

### Endpoint

```
GET https://gateway.pixazo.ai/v2/requests/status/{request_id}
Ocp-Apim-Subscription-Key: YOUR_API_KEY
```

## cURL Example

```
curl -H "Ocp-Apim-Subscription-Key: YOUR_API_KEY" \
  "https://gateway.pixazo.ai/v2/requests/status/hidream-o1-image-dev-edit_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
```

## Response (Completed)

```
{
  "request_id": "hidream-o1-image-dev-edit_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "COMPLETED",
  "model_id": "hidream-o1-image-dev-edit",
  "error": null,
  "output": { "media_url": ["https://pub-582b7213209642b9b995c96c95a30381.r2.dev/v1/hidream-o1-image-dev-edit_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/output.png"], "media_type": "image/png" },
  "created_at": "2026-03-31T10:00:00.000Z",
  "updated_at": "2026-03-31T10:00:15.000Z",
  "completed_at": "2026-03-31T10:00:15.000Z"
}
```

## Response Fields

Field

Type

Description

request\_id

string

Unique request identifier

status

string

QUEUED, PROCESSING, COMPLETED, FAILED, or ERROR

model\_id

string

Model that processed the request

error

string|null

Error message if failed

output.media\_url

array

URLs to generated media (R2 CDN)

output.media\_type

string

MIME type of the output

created\_at

string

When request was created

completed\_at

string

When request completed

polling\_url

string

Status URL (initial response only)

## Status Values

Status

Description

QUEUED

Request accepted, waiting to be processed

PROCESSING

Being processed by the model

COMPLETED

Done — output contains the result

FAILED

Failed — check error field

ERROR

System error — not charged

## Status Flow

```
QUEUED → PROCESSING → COMPLETED
                    → FAILED
                    → ERROR
```

## Typical Workflow

1.  **Send a generate request** to the API endpoint
2.  **Save the `request_id`** from the response
3.  **Poll** every 5-10 seconds: `GET /v2/requests/status/{request_id}`
4.  **When `status` is `"COMPLETED"`**, download from `output.media_url`

**Tip:** Use `X-Webhook-URL` header to get a callback instead of polling.