Ideogram

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 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.

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"])

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:

{
  "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.

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)

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.

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.

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)

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.

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:

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}'

{"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 urls) 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

Ideogram API docs

Official endpoints and parameters

Task API

Submitting, querying and callbacks on the unified task API

Getting Started

Models & Services

Usage Guide

Available models

Official format

Sync, async and queries

Callbacks

OpenAI SDK

Unified task API

Price quotes

Billing

Differences from the official API

Errors

Ideogram API docs

Task API

​Available models

​Official format

​Sync, async and queries

​Callbacks

​OpenAI SDK

​Unified task API

​Price quotes

​Billing

​Differences from the official API

​Errors

​Related links

Ideogram API docs

Task API

Available models

Official format

Sync, async and queries

Callbacks

OpenAI SDK

Unified task API

Price quotes

Billing

Differences from the official API

Errors

Related links