Ideogram

已兼容 Ideogram 官方 API（v2）：把地址 https://api.ideogram.ai 换成 https://api.ephone.ai/ideogram，Api-Key 请求头填本站的 API Key，按官方文档写的程序就能直接用。也可以用 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。

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

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

返回示例：

{
  "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
    }
  ]
}

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

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)

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。
换背景、去物体与官方一样只能异步；看图写描述没有异步，当场返回。

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。

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)

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。用法见异步任务。

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，请求体照常写：网关按本站价格报价，不生成、不扣费。返回结构与官方一致：

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 是这一单的总价（美元 × 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	服务暂时不可用或超时，稍后重试

Ideogram API 文档

官方的接口说明与参数

异步任务

统一任务接口的提交、查询与回调

开始使用

模型与服务

使用指南

可用模型

用官方格式调用

同步、异步与查询

回调

用 OpenAI SDK 调用

用统一任务接口调用

只报价

计费

与官方的不同

错误

相关链接

Ideogram API 文档

异步任务

​可用模型

​用官方格式调用

​同步、异步与查询

​回调

​用 OpenAI SDK 调用

​用统一任务接口调用

​只报价

​计费

​与官方的不同

​错误

​相关链接

Ideogram API 文档

异步任务

可用模型

用官方格式调用

同步、异步与查询

回调

用 OpenAI SDK 调用

用统一任务接口调用

只报价

计费

与官方的不同

错误

相关链接