---
type: AI Model
id: image-convert-api
title: Image Converter API
provider: Pixazo
description: "Convert an image between HEIC, WebP, PNG, JPG, BMP, TIFF, AVIF and GIF in any direction. EXIF orientation is APPLIED before metadata is stripped, so phone photos come back upright instead of sideways — the whole of \"my iPhone photo won’t upload anywhere\". Transparency is flattened onto WHITE, not black, when the target format has no alpha channel."
resource: https://www.pixazo.ai/models/image-convert-api
docs_url: https://www.pixazo.ai/models/image-convert-api
latest_version: v1
tags:
  - image-converter
  - pixazo
variants:
  - id: media-convert-image-v1
    name: Image Converter 1.0
    version: 1.0
    capabilities:
      - Convert Image
timestamp: 2026-08-16T15:44:59.489Z
---

# Image Converter API

> Provider: **Pixazo**
> Source: https://www.pixazo.ai/models/image-convert-api

Convert an image between HEIC, WebP, PNG, JPG, BMP, TIFF, AVIF and GIF in any direction. EXIF orientation is APPLIED before metadata is stripped, so phone photos come back upright instead of sideways — the whole of "my iPhone photo won’t upload anywhere". Transparency is flattened onto WHITE, not black, when the target format has no alpha channel.

## Image Converter 1.0

### Convert Image

## Base URL

```
https://gateway.pixazo.ai/media-tools/v1/image-convert
```

## Authentication

All requests require an API key passed via header.

**Pricing:** Billed at **$0.002 per image** — a flat rate per call. A 12-megapixel photo and a 200-pixel thumbnail cost exactly the same.

**Retries:** this is an asynchronous job on shared encoding capacity, so a request can occasionally come back `processing_failed` or take much longer than usual. These are transient and succeed on a retry, and a failed job is **never charged** — the wallet hold is released. If you chain these tools, retry a failed step rather than failing the whole pipeline.

Header

Type

Required

Description

Ocp-Apim-Subscription-Key

string

Yes

Your API subscription key

## Image Converter generate request

## Request Code

HTTP Python JavaScript cURL

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

{
  "image_url": "https://api-assets.pixazo.ai/media-api-test/t.png",
    "to_format": "webp",
    "quality": 80
}
```

```
import requests

url = "https://gateway.pixazo.ai/media-tools/v1/image-convert"
headers = {
    "Content-Type": "application/json",
    "Cache-Control": "no-cache",
    "Ocp-Apim-Subscription-Key": "YOUR_API_KEY"
}
data = {
    "image_url": "https://api-assets.pixazo.ai/media-api-test/t.png",
    "to_format": "webp",
    "quality": 80
}

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

```
const url = "https://gateway.pixazo.ai/media-tools/v1/image-convert";
const headers = {
  "Content-Type": "application/json",
  "Cache-Control": "no-cache",
  "Ocp-Apim-Subscription-Key": "YOUR_API_KEY"
};
const data = {
  "image_url": "https://api-assets.pixazo.ai/media-api-test/t.png",
    "to_format": "webp",
    "quality": 80
};

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/media-tools/v1/image-convert" \
  -H "Content-Type: application/json" \
  -H "Cache-Control: no-cache" \
  -H "Ocp-Apim-Subscription-Key: YOUR_API_KEY" \
  --data-raw '{
    "image_url": "https://api-assets.pixazo.ai/media-api-test/t.png",
    "to_format": "webp",
    "quality": 80
  }'
```

## Output

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

[Try Now](https://api.pixazo.ai/api-details#api=media-tools&operation=image-convert)

## 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 - Image Converter generate request

Parameter

Required

Type

Default

Allowed values / range

Description

image\_url

Yes

string

—

HTTP(S) URL to an image

The image to convert. HEIC, WebP, PNG, JPG, BMP, TIFF, AVIF and GIF are all accepted as input.

to\_format

Yes

string

—

`jpg`, `jpeg`, `png`, `webp`, `gif`, `bmp`, `tiff`, `avif`, `heic`

Target format. Required — there is no default, and any other value is rejected before you are charged.

quality

No

number

`92`

1 – 100

Encoder quality. Ignored by formats that are always lossless, such as PNG and BMP.

keep\_metadata

No

boolean

`false`

`true`, `false`

Keep EXIF, including GPS coordinates. Off by default, so location data is stripped unless you ask for it.

**EXIF orientation:** the Orientation tag is applied before metadata is stripped — the reverse order deletes the rotation instead of applying it, which is why a portrait phone shot so often arrives sideways elsewhere. **Known limitation:** for some sources the pixels are not rotated and the Orientation tag is still normalised to 1, so an orientation-aware viewer can render the result sideways. If orientation matters to you, check the returned dimensions rather than relying on the tag. A fix is in progress.

Transparency is flattened onto **white** when the target format has no alpha channel (JPG, BMP). A black flatten is what turns a transparent logo into a dark rectangle. If the source holds several frames and the target format holds one, you get frame 0.

## Example Request

```
{
  "image_url": "https://api-assets.pixazo.ai/media-api-test/t.png",
    "to_format": "webp",
    "quality": 80
}
```

## Response

```
{
  "request_id": "media-convert-image_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "QUEUED",
  "polling_url": "https://gateway.pixazo.ai/v2/requests/status/media-convert-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 'media-convert-image' not found or is disabled"
}
```

### Error via Status/Webhook

```
{
  "request_id": "media-convert-image_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "ERROR",
  "model_id": "media-convert-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/media-convert-image_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
```

## Response (Completed)

```
{
  "request_id": "media-convert-image_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "COMPLETED",
  "model_id": "media-convert-image",
  "error": null,
  "output": {
    "media_url": [
      "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/v1/media-convert-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.