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

> 用 Ideogram 官方格式、OpenAI 兼容接口或统一任务接口调用 Ideogram 4.5、4.0、P-Image，以及去背景、去物体。

已兼容 Ideogram 官方 API（v2）：把地址 `https://api.ideogram.ai` 换成 `https://api.ephone.ai/ideogram`，`Api-Key` 请求头填本站的 API Key，按[官方文档](https://developer.ideogram.ai/v2/ideogram-api/api-overview)写的程序就能直接用。也可以用 OpenAI 兼容的图片接口或统一任务接口调用。

## 可用模型

| 模型 | 用途 | 官方接口 | OpenAI 兼容接口 |
| - | - | - | - |
| `ideogram-4-5/generate` | 文生图；上传最多 5 张图按提示词修改；可出透明背景 | `POST /v2/image/generate/ideogram-4-5` | `generations`、`edits` |
| `ideogram-4-5/precise-edit` | 精确改图：只改你说的部分，输出与原图同尺寸 | `POST /v2/image/precise-edit/ideogram-4-5` | `edits` |
| `ideogram-4-5/replace-background` | 把背景换成参考图里的场景（只能异步） | `POST /v2/image/replace-background/ideogram-4-5` | `edits` |
| `ideogram-4/generate` | 文生图，Ideogram 首个开放权重模型 | `POST /v2/image/generate/ideogram-4` | `generations` |
| `ideogram-4/remix` | 按提示词改造一张图 | `POST /v2/image/remix/ideogram-4` | `edits` |
| `ideogram-4/describe` | 看图写出 4.0 的结构化提示词 | `POST /v2/image/describe/ideogram-4` | 不支持 |
| `ideogram-4-transparent/generate` | 透明底 PNG，1K 到 8K | `POST /v2/image/generate/ideogram-4-transparent` | `generations` |
| `p-image-ideogram/generate` | 快速、低价出图 | `POST /v2/image/generate/p-image-ideogram` | `generations` |
| `ideogram-1/remove-background` | 去背景，返回透明底 PNG | `POST /v2/image/remove-background/ideogram-1` | `edits` |
| `ideogram-1/remove-object` | 按遮罩去掉物体（只能异步） | `POST /v2/image/remove-object/ideogram-1` | `edits` |

每个模型的完整参数、价格和更多示例见模型详情页（模型广场搜索 Ideogram）。

## 用官方格式调用

地址是 `https://api.ephone.ai/ideogram` 加官方路径，请求体和返回与官方一致。不带文件时发 JSON；上传图片时用 `multipart/form-data`。

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

API = "https://api.ephone.ai/ideogram"
HEADERS = {"Api-Key": ""}  # 替换为你在本站点的 API Key

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

返回示例：

```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
    }
  ]
}
```

精确改图：上传要改的图，写清只改什么，没改到的像素原样保留。

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

API = "https://api.ephone.ai/ideogram"
HEADERS = {"Api-Key": ""}  # 替换为你在本站点的 API Key
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>` 鉴权。

## 同步、异步与查询

* **默认当场返回结果**，与官方一致。网关最多等 10 分钟；超过 10 分钟还没出结果时，返回里只有 `generation_id`、没有 `data`，接着用查询接口查即可，任务不会丢。
* 传 `async: true` 或 `webhook_url` 时立即返回 `generation_id`，之后用 `GET https://api.ephone.ai/ideogram/v2/generations/{generation_id}` 查询：`status` 为 `pending` 时继续等，`completed` 时结果在 `data`，`failed` 时原因在 `failure_reason`。
* 换背景、去物体与官方一样只能异步；看图写描述没有异步，当场返回。

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

API = "https://api.ephone.ai/ideogram"
HEADERS = {"Api-Key": ""}  # 替换为你在本站点的 API Key

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` 是本站的任务号，只能在本站查询。

## 回调

传了 `webhook_url` 时，任务结束后网关向这个地址 `POST` 一次 JSON，内容与查询接口的返回相同。和官方回调的区别：

* 由本站发出，不带官方的 `X-Ideogram-Webhook-*` 请求头和签名。
* 只推送一次，不重试；地址必须是公网的 http(s) 地址。

建议在回调地址里带一段只有你知道的随机参数，收到回调后再用查询接口核对一次；没收到时用查询接口取结果。

## 用 OpenAI SDK 调用

`ideogram-4-5/generate`、`ideogram-4/generate`、`ideogram-4-transparent/generate`、`p-image-ideogram/generate` 支持 `POST /v1/images/generations`；改图、去背景、去物体、换背景支持 `POST /v1/images/edits`。网关等出图完成后直接返回结果；`response_format` 传 `b64_json` 时，个别图下载失败或过大会改给 `url`。

```python 文生图 theme={null} theme={null}
from openai import OpenAI

client = OpenAI(
    base_url="https://api.ephone.ai/v1",
    api_key="",  # 替换为你在本站点的 API Key
)

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 去背景 theme={null} theme={null}
import requests
from openai import OpenAI

client = OpenAI(
    base_url="https://api.ephone.ai/v1",
    api_key="",  # 替换为你在本站点的 API Key
)

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)
```

参数换算：

| OpenAI 参数 | 换成 Ideogram 的 |
| - | - |
| `n` | `num_images` |
| `quality` | 4.5 与 P-Image 原样作为 `quality`（`standard` → `medium`、`hd` → `high`）；4.0 系列换成 `rendering_speed`（`low` → `turbo`、`medium` → `default`、`high` → `quality`） |
| `size` | 4.5 文生图换成最接近的 1K / 2K 预设尺寸（如 `1536x1024` → `1248x832`；改图时原样，带遮罩时不生效）；4.0 换成最接近的 `resolution`；透明底换成最接近的 `aspect_ratio`，并按总像素选输出档位；P-Image 换成 `custom_width` / `custom_height`（传了 `resolution` 或 `aspect_ratio` 时不生效） |
| `image` | 各接口的图片字段，多张按顺序放（如换背景：第一张原图，第二张场景参考） |
| `mask` | OpenAI 写法（透明区域是要改的部分）自动换成 Ideogram 的黑白遮罩；不带透明像素的黑白图按 Ideogram 的写法原样使用 |

其他 Ideogram 参数（`magic_prompt`、`seed`、`rendering_speed`、`output_resolution` 等）平铺在请求体里，用 OpenAI SDK 时放进 `extra_body`。不需要提示词的模型（去背景、去物体、换背景）`prompt` 填什么都不影响结果。

## 用统一任务接口调用

`model` 填模型名，`input` 里用 Ideogram 的参数名；图片字段填公网 URL 或 Base64。用法见 [异步任务](https://docs.rixapi.com/docs/cn/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"}
  }'
```

## 只报价

在官方格式的地址后加 `?dry_run=true`，请求体照常写：网关按本站价格报价，不生成、不扣费。返回结构与官方一致：

```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` 是这一单的总价（美元 × 10⁶）。看图写描述不支持只报价：带 `?dry_run=true` 会返回 400，不执行也不扣费（官方会照常执行并扣费）。

## 计费

* 按实际交付的张数计费，每张的价格见模型详情页；提交时按 `num_images` 预扣，出结果后按交付张数结算。
* 没通过安全检查的图（`is_image_safe` 为 `false`、`url` 为空）不收费；参数错误、内容审核不通过的请求不扣费。

## 与官方的不同

* 结果地址：本站开了结果转存时是长期地址；没开时是官方的临时链接，24 小时后失效，请及时下载。
* 不支持按素材 ID 引用（`image_asset_identifier` 等）、官方账号里的合集与自训练模型，图片请直接上传。
* 去背景、换背景的结果一律不公开。
* 出的图全部没通过安全检查时：当场返回的请求回 422（官方回 200、`url` 为空），异步任务的状态是 `failed`；都不扣费。
* 查询结果不返回 `usage_cost_usd_micros`。

## 错误

出错时返回 `{"error": "原因"}`：

| HTTP 状态码 | 含义 |
| - | - |
| 400 | 参数不对，`error` 里是官方给的具体原因 |
| 401 | API Key 无效 |
| 403 | 余额不足 |
| 404 | 地址不存在，或查询的任务不存在 |
| 415 | 只收 JSON 的接口收到了表单请求 |
| 422 | 提示词、图片或生成结果没通过内容审核 |
| 429 | 请求太快，稍后重试 |
| 500 / 502 / 503 / 504 | 服务暂时不可用或超时，稍后重试 |

## 相关链接

> [card] [Ideogram API 文档](https://developer.ideogram.ai/v2/ideogram-api/api-overview)
>
> 官方的接口说明与参数

> [card] [异步任务](https://docs.rixapi.com/docs/cn/guides/task.md)
>
> 统一任务接口的提交、查询与回调


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