> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rixapi.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Ideogram

> Call Ideogram 4.5, 4.0, P-Image, background removal and object removal in Ideogram's official format, through the OpenAI-compatible endpoints, or through the unified task API.

The official Ideogram API (v2) is supported as is: replace `https://api.ideogram.ai` with `https://api.ephone.ai/ideogram` and put your API key from this site in the `Api-Key` header, and code written against the [official docs](https://developer.ideogram.ai/v2/ideogram-api/api-overview) works unchanged. The OpenAI-compatible image endpoints and the unified task API work too.

## Available models

| Model | What it does | Official endpoint | OpenAI-compatible |
| - | - | - | - |
| `ideogram-4-5/generate` | Text to image; edit up to 5 uploaded images with a prompt; transparent backgrounds | `POST /v2/image/generate/ideogram-4-5` | `generations`, `edits` |
| `ideogram-4-5/precise-edit` | Precise edits that change only what you describe and keep the image's size | `POST /v2/image/precise-edit/ideogram-4-5` | `edits` |
| `ideogram-4-5/replace-background` | Rebuilds the background as the setting in a reference image (async only) | `POST /v2/image/replace-background/ideogram-4-5` | `edits` |
| `ideogram-4/generate` | Text to image with Ideogram's first open-weight model | `POST /v2/image/generate/ideogram-4` | `generations` |
| `ideogram-4/remix` | Transforms an image with a prompt | `POST /v2/image/remix/ideogram-4` | `edits` |
| `ideogram-4/describe` | Describes an image as an Ideogram 4.0 structured prompt | `POST /v2/image/describe/ideogram-4` | Not supported |
| `ideogram-4-transparent/generate` | Transparent PNGs from 1K to 8K | `POST /v2/image/generate/ideogram-4-transparent` | `generations` |
| `p-image-ideogram/generate` | Fast, low-cost generation | `POST /v2/image/generate/p-image-ideogram` | `generations` |
| `ideogram-1/remove-background` | Removes the background and returns a transparent PNG | `POST /v2/image/remove-background/ideogram-1` | `edits` |
| `ideogram-1/remove-object` | Removes a masked object (async only) | `POST /v2/image/remove-object/ideogram-1` | `edits` |

Every model's parameters, prices and further examples are on its model detail page (search for Ideogram in the model marketplace).

## Official format

Use `https://api.ephone.ai/ideogram` followed by the official path; the body and response match the official API. Send JSON without files and `multipart/form-data` when uploading images.

```python Python theme={null} theme={null}
import requests

API = "https://api.ephone.ai/ideogram"
HEADERS = {"Api-Key": ""}  # replace with your API key from this site

resp = requests.post(
    f"{API}/v2/image/generate/ideogram-4-5",
    headers=HEADERS,
    json={
        "prompt": "A minimalist poster for a coffee shop with the headline \"OPEN DAILY\" in bold coral letters",
        "quality": "low",
    },
)
resp.raise_for_status()
image = resp.json()["data"][0]
with open("poster.png", "wb") as f:
    f.write(requests.get(image["url"]).content)
print(image["resolution"])
```

```bash cURL theme={null} theme={null}
curl https://api.ephone.ai/ideogram/v2/image/generate/ideogram-4-5 \
  -H "Api-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A minimalist poster for a coffee shop with the headline \"OPEN DAILY\" in bold coral letters",
    "quality": "low"
  }'
```

Response:

```json theme={null} theme={null}
{
  "generation_kind": "sampling",
  "generation_id": "uK3mZ0bW7qR2xY9vT1nA5c",
  "seed": 691874457,
  "data": [
    {
      "url": "https://...",
      "prompt": "{\"high_level_description\": \"A minimalist poster for a coffee shop ...\", ...}",
      "resolution": "1664x2496",
      "is_image_safe": true,
      "seed": 691874457
    }
  ]
}
```

Precise edit: upload the image and say what to change; pixels the edit does not touch are kept exactly.

```python Python theme={null} theme={null}
import requests

API = "https://api.ephone.ai/ideogram"
HEADERS = {"Api-Key": ""}  # replace with your API key from this site
photo = requests.get("https://p2-kling.klingai.com/kcdn/cdn-kcdn112452/chrome-plugin-upload/2026-10-13/1791892087071.f32f7a727b1832bf.png").content

resp = requests.post(
    f"{API}/v2/image/precise-edit/ideogram-4-5",
    headers=HEADERS,
    data={
        "prompt": "Change the handbag on the table to deep green leather. Keep everything else exactly the same.",
        "quality": "very_low",
    },
    files={"image": ("cafe.png", photo, "image/png")},
)
resp.raise_for_status()
with open("edited.png", "wb") as f:
    f.write(requests.get(resp.json()["data"][0]["url"]).content)
```

```bash cURL theme={null} theme={null}
curl -o cafe.png "https://p2-kling.klingai.com/kcdn/cdn-kcdn112452/chrome-plugin-upload/2026-10-13/1791892087071.f32f7a727b1832bf.png"
curl https://api.ephone.ai/ideogram/v2/image/precise-edit/ideogram-4-5 \
  -H "Api-Key: $API_KEY" \
  -F image=@cafe.png \
  -F prompt="Change the handbag on the table to deep green leather. Keep everything else exactly the same." \
  -F quality=very_low
```

`Authorization: Bearer <API key>` also works.

## Sync, async and queries

* **Results come back in the response by default**, as with the official API. The gateway waits up to 10 minutes; if the images are not ready by then, the response carries only `generation_id` without `data`; keep querying and the task is not lost.
* With `async: true` or a `webhook_url`, the response returns a `generation_id` right away; query `GET https://api.ephone.ai/ideogram/v2/generations/{generation_id}`: keep waiting while `status` is `pending`; on `completed` the result is in `data`; on `failed` the reason is in `failure_reason`.
* Replace background and remove object are async only, as with the official API; describe has no async mode and answers right away.

```python Python theme={null} theme={null}
import time
import requests

API = "https://api.ephone.ai/ideogram"
HEADERS = {"Api-Key": ""}  # replace with your API key from this site

resp = requests.post(
    f"{API}/v2/image/generate/p-image-ideogram",
    headers=HEADERS,
    json={"prompt": "A cozy reading nook by a rainy window", "quality": "very_low", "async": True},
)
resp.raise_for_status()
generation_id = resp.json()["generation_id"]

while True:
    result = requests.get(f"{API}/v2/generations/{generation_id}", headers=HEADERS).json()
    if result["status"] != "pending":
        break
    time.sleep(3)

if result["status"] == "failed":
    raise SystemExit(result.get("failure_reason"))
print(result["data"][0]["url"])
```

`generation_id` is this site's task ID and can only be queried here.

## Callbacks

With a `webhook_url`, the gateway sends one JSON `POST` to it when the task ends, with the same body as the query endpoint. Unlike the official webhooks:

* The callback comes from this site, without the official `X-Ideogram-Webhook-*` headers or signature.
* It is sent once without retries, and the URL must be a public http(s) address.

Put a random secret in the callback URL, re-check the result with the query endpoint when a callback arrives, and fall back to querying if none arrives.

## OpenAI SDK

`ideogram-4-5/generate`, `ideogram-4/generate`, `ideogram-4-transparent/generate` and `p-image-ideogram/generate` work with `POST /v1/images/generations`; editing, background removal, object removal and background replacement work with `POST /v1/images/edits`. The gateway returns once the images are ready; with `response_format: b64_json`, an image that cannot be downloaded or is too large comes back as a `url`.

```python Text to image theme={null} theme={null}
from openai import OpenAI

client = OpenAI(
    base_url="https://api.ephone.ai/v1",
    api_key="",  # replace with your API key from this site
)

result = client.images.generate(
    model="p-image-ideogram/generate",
    prompt="A cozy reading nook by a rainy window, warm lamp light",
    quality="very_low",
    size="1280x720",
)
print(result.data[0].url)
```

```python Remove background theme={null} theme={null}
import requests
from openai import OpenAI

client = OpenAI(
    base_url="https://api.ephone.ai/v1",
    api_key="",  # replace with your API key from this site
)

photo = requests.get("https://p2-kling.klingai.com/kcdn/cdn-kcdn112452/chrome-plugin-upload/2026-10-13/1791892087071.f32f7a727b1832bf.png").content
result = client.images.edit(
    model="ideogram-1/remove-background",
    image=("cafe.png", photo, "image/png"),
    prompt="Remove the background",
)
print(result.data[0].url)
```

How parameters map:

| OpenAI parameter | Becomes in Ideogram |
| - | - |
| `n` | `num_images` |
| `quality` | `quality` for 4.5 and P-Image (`standard` → `medium`, `hd` → `high`); `rendering_speed` for the 4.0 family (`low` → `turbo`, `medium` → `default`, `high` → `quality`) |
| `size` | The closest 1K/2K preset for 4.5 text to image (`1536x1024` → `1248x832`, for example; passed as is for edits and ignored with a mask); the closest `resolution` for 4.0; the closest `aspect_ratio` plus an output tier by total pixels for transparent; `custom_width` / `custom_height` for P-Image (ignored when `resolution` or `aspect_ratio` is given) |
| `image` | The endpoint's image fields, in order (for background replacement: the source first, then the setting) |
| `mask` | An OpenAI-style mask (transparent areas are edited) is converted to Ideogram's black-and-white mask; one without transparent pixels is used as is in Ideogram's convention |

Other Ideogram parameters (`magic_prompt`, `seed`, `rendering_speed`, `output_resolution`, …) go at the top level of the body, in `extra_body` with the OpenAI SDK. Models without a prompt (background removal, object removal, background replacement) ignore whatever `prompt` you send.

## Unified task API

Set `model` to the model name and use Ideogram's parameter names in `input`; image fields take public URLs or Base64. See [Task API](https://docs.rixapi.com/docs/en/guides/task.md).

```bash cURL theme={null} theme={null}
curl https://api.ephone.ai/v1/task/submit \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "p-image-ideogram/generate",
    "input": {"prompt": "A cozy reading nook by a rainy window", "quality": "very_low"}
  }'
```

## Price quotes

Add `?dry_run=true` to an official-format URL and send the same body: the gateway quotes this site's price without generating or billing. The response matches the official one:

```bash cURL theme={null} theme={null}
curl "https://api.ephone.ai/ideogram/v2/image/generate/ideogram-4-5?dry_run=true" \
  -H "Api-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "A red ball", "quality": "medium", "num_images": 3}'
```

```json theme={null} theme={null}
{"object": "price_quote", "billing_identifier": "ideogram-4-5/generate", "quantity": 3, "usd_micros": 180000, "credit_millis": 18000, "qualifier": "exact"}
```

`usd_micros` is the total for the request (USD × 10⁶). Describe does not support price quotes: `?dry_run=true` returns 400 and nothing is run or billed (Ideogram itself would run and bill it).

## Billing

* Billed per image actually delivered, at the per-image price on the model detail page; `num_images` is reserved on submission and settled by the images delivered.
* Images that fail the safety checks (`is_image_safe: false`, empty `url`) are not billed, nor are requests rejected for invalid parameters or content moderation.

## Differences from the official API

* Result URLs are long-lived re-hosted copies when this site re-hosts results; otherwise they are the official temporary links, which expire after 24 hours, so download them promptly.
* Asset references (`image_asset_identifier` and similar), collections and custom models stored in an Ideogram account are not supported; upload the images instead.
* Background removal and replacement results are always private.
* When every image fails the safety checks, a request answered in place returns 422 (Ideogram returns 200 with empty `url`s) and an async task ends as `failed`; neither is billed.
* Query results do not include `usage_cost_usd_micros`.

## Errors

Errors return `{"error": "reason"}`:

| HTTP status | Meaning |
| - | - |
| 400 | Invalid parameters; `error` carries the official reason |
| 401 | Invalid API key |
| 403 | Insufficient balance |
| 404 | Unknown path, or the queried task does not exist |
| 415 | A form request was sent to an endpoint that only accepts JSON |
| 422 | The prompt, an image or the results did not pass content moderation |
| 429 | Too many requests; retry later |
| 500 / 502 / 503 / 504 | Temporarily unavailable or timed out; retry later |

## Related links

> [card] [Ideogram API docs](https://developer.ideogram.ai/v2/ideogram-api/api-overview)
>
> Official endpoints and parameters

> [card] [Task API](https://docs.rixapi.com/docs/en/guides/task.md)
>
> Submitting, querying and callbacks on the unified task API


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.