Ideogram 4.5 API, Ideogram v4 API, Ideogram RMBG API: Pricing, Documentation

Authentication

All requests require an API key passed via header.

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.

Example: enable Webhook

curl -X POST 'https://gateway.pixazo.ai/ideogram-v4-5/v1/text-to-image' \
  -H 'Content-Type: application/json' \
  -H 'Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY' \
  -H 'X-Webhook-URL: https://your-server.com/webhook' \
  --data-raw '{"prompt": "A vintage travel poster of Kyoto in autumn, bold hand-lettered title reading \"KYOTO\" across the top", "image_size": "portrait_4_3", "quality": "medium", "num_images": 1}'

Callback Payload (success)

{
  "request_id": "ideogram-v4-5_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "COMPLETED",
  "model_id": "ideogram-v4-5",
  "error": null,
  "output": {
    "media_url": [
      "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/v1/{request_id}/output.png"
    ],
    "media_type": "image/png"
  },
  "created_at": "2026-10-02T10:04:54.387Z",
  "completed_at": "2026-10-02 10:05:21"
}

Failure callback shape

{
  "request_id": "ideogram-v4-5_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "ERROR",
  "model_id": "ideogram-v4-5",
  "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 every poll while the request is processing (status PROCESSING), plus the final COMPLETED/ERROR callback.
• Callbacks are idempotent on request_id — de-duplicate on it.
• Respond 200 within a few seconds; the Webhook endpoint must be HTTPS.

Request Parameters

Good to know

• sync_mode is not supported — a request with sync_mode: true is rejected. Finished images are always delivered as URLs through the status endpoint.
• num_images is the only way to ask for several images. n, count, batch_size, number_of_images are rejected.
• Omit optional fields you do not use — do not send them as null.

Image Sizes

Pass image_size as one of the named presets, or as an object such as {"width": 1440, "height": 2560}. An object must match one of the 36 supported sizes below exactly. The size does not change the amount billed.

Supported exact sizes

Request Headers

Response Handling

Most parameter problems are caught when you submit and returned as a 400, before any hold is placed on your balance. Problems that need an image to be fetched or the model to run are reported through the status endpoint as status: "ERROR", with a message in error saying what to fix. Failed requests are not billed — the hold is released in full.

Retrieving Results

Poll the status endpoint with the request_id from the submit response until status is COMPLETED or ERROR, then download the images from output.media_url — one URL per generated image. Treat any status other than QUEUED, PROCESSING or COMPLETED as a failure.

Endpoint

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

cURL example

curl 'https://gateway.pixazo.ai/v2/requests/status/ideogram-v4-5_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx' \
  -H 'Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY'

Completed response

{
  "request_id": "ideogram-v4-5_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "COMPLETED",
  "model_id": "ideogram-v4-5",
  "error": null,
  "output": {
    "media_url": [
      "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/v1/{request_id}/output.png"
    ],
    "media_type": "image/png"
  },
  "created_at": "2026-10-02T10:04:54.387Z",
  "completed_at": "2026-10-02 10:05:21"
}

Response Fields

Status Values & Flow

QUEUED → PROCESSING → COMPLETED (success) or ERROR (failure).

Typical workflow

1. Send the request to POST https://gateway.pixazo.ai/ideogram-v4-5/v1/text-to-image.
2. Save the request_id from the 202 response.
3. Poll GET /v2/requests/status/{request_id} every 5–10 seconds, or use a Webhook instead.
4. When status is COMPLETED, download the images from output.media_url.

How billing is measured

Billing is measured per generated image: the number of images you ask for (num_images, 1 by default) at the rate for the quality tier you choose — medium when you leave it out. The image size does not change the amount. The amount is placed as a hold when the request is submitted and released in full if the request fails.

The current rate is shown in the pricing panel on this page.

Authentication

All requests require an API key passed via header.

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.

Example: enable Webhook

curl -X POST 'https://gateway.pixazo.ai/ideogram-v4-5-edit/v1/edit-image' \
  -H 'Content-Type: application/json' \
  -H 'Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY' \
  -H 'X-Webhook-URL: https://your-server.com/webhook' \
  --data-raw '{"prompt": "Replace the background with a sunlit beach at golden hour and keep the subject unchanged", "image_url": "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/Image.jpeg", "edit_precision": "regular", "quality": "medium"}'

Callback Payload (success)

{
  "request_id": "ideogram-v4-5-edit_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "COMPLETED",
  "model_id": "ideogram-v4-5-edit",
  "error": null,
  "output": {
    "media_url": [
      "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/v1/{request_id}/output.png"
    ],
    "media_type": "image/png"
  },
  "created_at": "2026-10-02T10:04:54.387Z",
  "completed_at": "2026-10-02 10:05:21"
}

Failure callback shape

{
  "request_id": "ideogram-v4-5-edit_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "ERROR",
  "model_id": "ideogram-v4-5-edit",
  "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 every poll while the request is processing (status PROCESSING), plus the final COMPLETED/ERROR callback.
• Callbacks are idempotent on request_id — de-duplicate on it.
• Respond 200 within a few seconds; the Webhook endpoint must be HTTPS.

Request Parameters

Good to know

• Image URLs must be https and publicly reachable — JPEG, PNG or WEBP.
• sync_mode is not supported — a request with sync_mode: true is rejected. Finished images are always delivered as URLs through the status endpoint.
• num_images is the only way to ask for several images. n, count, batch_size, number_of_images are rejected.
• Omit optional fields you do not use — do not send them as null.

Masks and Reference Images

• Only image_url is edited. Reference images guide the result — a style, an object, a character — and are never edited themselves.
• A mask limits the edit to part of the image: black marks the area to edit, white the area to keep. Grey values are rounded to the nearer of the two. The mask must have the same width and height as the source image and contain both black and white areas.
• Up to 4 reference images, or up to 3 when you send a mask (the mask takes one of the slots).
• edit_precision currently accepts only "regular" (the default): the edit generates a new image guided by the source. Precise Edit ("high") is not yet available on this endpoint.
• The output keeps the source image's size by default (image_size: "auto", downscaled if the source is very large). Named presets and custom sizes are accepted only for unmasked edits.

Example: masked edit with a reference image

{
  "prompt": "Replace the masked area with a neon sign that reads \"OPEN LATE\"",
  "image_url": "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/Image.jpeg",
  "mask_url": "https://your-cdn.example.com/mask.png",
  "reference_image_urls": [
    "https://your-cdn.example.com/neon-style.jpg"
  ]
}

Request Headers

Response Handling

Most parameter problems are caught when you submit and returned as a 400, before any hold is placed on your balance. Problems that need an image to be fetched or the model to run are reported through the status endpoint as status: "ERROR", with a message in error saying what to fix. Failed requests are not billed — the hold is released in full.

Retrieving Results

Poll the status endpoint with the request_id from the submit response until status is COMPLETED or ERROR, then download the images from output.media_url — one URL per generated image. Treat any status other than QUEUED, PROCESSING or COMPLETED as a failure.

Endpoint

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

cURL example

curl 'https://gateway.pixazo.ai/v2/requests/status/ideogram-v4-5-edit_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx' \
  -H 'Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY'

Completed response

{
  "request_id": "ideogram-v4-5-edit_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "COMPLETED",
  "model_id": "ideogram-v4-5-edit",
  "error": null,
  "output": {
    "media_url": [
      "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/v1/{request_id}/output.png"
    ],
    "media_type": "image/png"
  },
  "created_at": "2026-10-02T10:04:54.387Z",
  "completed_at": "2026-10-02 10:05:21"
}

Response Fields

Status Values & Flow

QUEUED → PROCESSING → COMPLETED (success) or ERROR (failure).

Typical workflow

1. Send the request to POST https://gateway.pixazo.ai/ideogram-v4-5-edit/v1/edit-image.
2. Save the request_id from the 202 response.
3. Poll GET /v2/requests/status/{request_id} every 5–10 seconds, or use a Webhook instead.
4. When status is COMPLETED, download the images from output.media_url.

How billing is measured

Billing is measured per generated image: the number of images you ask for (num_images, 1 by default) at the rate for the quality tier you choose — medium when you leave it out. The image size does not change the amount. The amount is placed as a hold when the request is submitted and released in full if the request fails.

The current rate is shown in the pricing panel on this page.

Authentication

All requests require an API key passed via header.

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 - Ideogram V4 generate request

Request Headers

Response Handling

Common status codes.

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 'ideogram-v4' not found or is disabled"
}

Error via Status/Webhook

{
  "request_id": "ideogram-v4_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "ERROR",
  "model_id": "ideogram-v4",
  "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 -H "Ocp-Apim-Subscription-Key: YOUR_API_KEY" \
  "https://gateway.pixazo.ai/v2/requests/status/ideogram-v4_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

{
  "request_id": "ideogram-v4_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "COMPLETED",
  "model_id": "ideogram-v4",
  "error": null,
  "output": {
    "media_url": ["https://pub-582b7213209642b9b995c96c95a30381.r2.dev/v1/ideogram-v4_019dxxxx/output.jpeg"],
    "media_type": "image/jpeg"
  },
  "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

Status Values

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.

Authentication

All requests require an API key passed via header.

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 - Ideogram V4 Image to Image generate request

Content Item Types & Limits

Request Headers

Response Handling

Common status codes.

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 'ideogram-v4-image-to-image' not found or is disabled"
}

Error via Status/Webhook

{
  "request_id": "ideogram-v4-image-to-image_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "ERROR",
  "model_id": "ideogram-v4-image-to-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 -H "Ocp-Apim-Subscription-Key: YOUR_API_KEY" \
  "https://gateway.pixazo.ai/v2/requests/status/ideogram-v4-image-to-image_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

{
  "request_id": "ideogram-v4-image-to-image_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "COMPLETED",
  "model_id": "ideogram-v4-image-to-image",
  "error": null,
  "output": {
    "media_url": ["https://pub-582b7213209642b9b995c96c95a30381.r2.dev/v1/ideogram-v4-image-to-image_019dxxxx/output.jpeg"],
    "media_type": "image/jpeg"
  },
  "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

Status Values

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.

Authentication

All requests require an API key passed via header.

Request Parameters - Ideogram Remove Background generate request

Content Item Types & Limits

Response

{
  "request_id": "ideogram-remove-background_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "QUEUED",
  "polling_url": "https://gateway.pixazo.ai/v2/requests/status/ideogram-remove-background_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}

Response Fields - Ideogram Remove Background generate request

Request Headers

Response Handling

Common status codes for Ideogram Remove Background generate request.

Error Responses

{
  "error": "Invalid image_url",
  "message": "The provided image_url is malformed or unreachable."
}

{
  "error": "Unauthorized",
  "message": "Missing or invalid Ocp-Apim-Subscription-Key header."
}

Status Workflow

Check status of your request using the polling_url returned in the response.

Status Values

Status Flow

Submitted
    ↓
  QUEUED
    ↓
PROCESSING
    ↓
COMPLETED or FAILED or ERROR

Typical Workflow

1. Submit request to /ideogram-remove-background-request
2. Receive response with request_id and polling_url
3. Make GET requests to polling_url every 2–3 seconds
4. When status is COMPLETED, extract output from the response
5. Handle FAILED or ERROR states as appropriate

Request Parameters - Ideogram Remove Background check status

Response

{
  "request_id": "ideogram-remove-background_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "COMPLETED",
  "model_id": "ideogram-remove-background",
  "error": null,
  "output": {
    "media_url": ["https://pub-582b7213209642b9b995c96c95a30381.r2.dev/v1/ideogram-remove-background_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 - Ideogram Remove Background check status

Request Headers

Response Handling

Common status codes for Ideogram Remove Background check status.

Notes & Tips

• Pricing is $0.01 per request.
• Use sync_mode: true if you need the output as a data URI directly in the submission response (not recommended for production).
• Wait 2–3 seconds between polling requests for optimal performance.
• Implement exponential backoff for retrying failed or system error responses.
• Image must be under 10MB and in JPEG, PNG, or WebP format.
• The output is always a transparent PNG, suitable for compositing.
• Responses from the polling endpoint are not cached — each poll counts toward your usage limits.
• Use the polling URL returned in the initial response — do not construct it manually.