跳转到主要内容
POST
  1. 提交后会返回 task_id。如果提供了 callback_url,当任务状态变为 finished 或 failed 时,系统会向 callback_url 发送 POST 请求。
  2. 无论是否提供 callback_url,都可以通过统一的查询任务状态接口获取结果。
Ideogram 4.6 API 将 Ideogram 最新的图像模型接入 PoYo。它适合制作海报、Logo、包装、社交媒体图片,以及任何需要图上文字准确无误的图像。Ideogram 4.6 API 接收一段提示词,返回 1 到 8 张图像,可选四档质量、宽高比预设或每边最高 4096 像素的精确尺寸,并支持透明背景。如需修改已有图像,请使用 Ideogram 4.6 Edit API。

Ideogram 4.6 API 模型

  • ideogram-v4.6 — 文生图,支持质量、尺寸、背景和随机种子控制
  • ideogram-v4.6-edit — 图像编辑,支持蒙版和参考图。参见 Ideogram V4.6 Edit

Ideogram 4.6 API 功能

  • 图上文字:在提示词中写出要显示的原文,例如标题或招牌文字,模型会把它渲染到图像上。
  • 四档质量:very_low 适合快速出草图,另有 low、medium(默认)和 high。
  • 最高 4K 尺寸:可选 auto、六种宽高比预设,或每边 256 到 4096 像素的自定义 WIDTHxHEIGHT。
  • 透明背景:将 background 设为 transparent,即可得到带 alpha 通道的图像,适合贴纸、图标和 Logo。
  • 批量与种子:每次请求最多生成 8 张图像,设置 seed 可复现结果。

必填参数

  • prompt (string):描述图像的提示词,1–10,000 个字符,必须包含非空白文本。需要原样出现在图上的文字,请用引号括起来。

可选参数

  • size (string):auto、1:1、1:1 HD、4:3、3:4、16:9、9:16 或自定义 WIDTHxHEIGHT。默认为 auto。参见尺寸。
  • quality (string):very_low、low、medium 或 high。默认为 medium。very_low 只适用于不超过 4,194,304 像素(面积 2048×2048)的输出。
  • n (integer):图像数量,1 到 8。默认为 1。
  • background (string):transparent 或 opaque。transparent 返回带 alpha 通道的图像;opaque 强制使用实色背景。不传则由模型决定。
  • seed (integer):随机种子,0 到 2147483647。不传则自动选取。
  • callback_url (string):可选的 Webhook URL,用于任务完成通知。放在请求顶层,不要放进 input。
Ideogram 4.6 API 的 input 只接受以上字段。传入其他字段会返回 unsupported fields 错误。

尺寸

自定义尺寸使用小写 x,例如 2048x1152。宽和高都必须在 256 到 4096 像素之间且为 32 的倍数,宽高比须在 1:6 到 6:1 之间。Ideogram 4.5 API 接受、但不是 32 倍数的尺寸(例如 1296x3168)会被拒绝。

输出

任务状态为 finished 时,files 中每张生成的图像对应一项,包含 file_url 和 file_type: image。background 设为 transparent 时,图像带 alpha 通道。

Ideogram 4.6 API 示例

将下面的 Ideogram 4.6 API 请求发送到 POST /api/generate/submit,并在 Authorization 请求头中携带 API Key。

文生图

该请求使用默认设置(auto、medium、一张图)。

4K 尺寸海报

2048x3072 为 6,291,456 像素,超过 4,194,304 像素,因此该尺寸不能使用 very_low。

透明背景贴纸

注意事项

  • very_low 与超过 4,194,304 像素的自定义尺寸同时使用时会被拒绝,错误信息为 “very_low quality supports sizes up to 2048x2048 pixels in area (4,194,304 pixels)”。
  • n 必须为整数,字符串和布尔值会被拒绝。
  • 与 Ideogram 4.5 相同,Ideogram 4.6 API 始终开启提示词扩展。
  • 生成的图像文件在创建后 3 天内可访问,请及时下载保存。
  • 响应返回 task_id,请通过查询任务状态获取生成的图像。

授权

Authorization
string
header
必填

所有 API 接口都需要 Bearer Token 认证。

创建 API Key:登录 PoYo,进入 仪表盘 → API 密钥(poyo.ai/zh/dashboard/api-key),点击创建 Key。

在请求头中添加:

请求体

application/json
model
enum<string>
必填

Ideogram 4.6 文生图模型标识。

可用选项:
ideogram-v4.6
input
object
必填

根据提示词生成 1-8 张图像。

callback_url
string<uri>

可选的 Webhook URL,任务完成或失败时通知。

响应

任务提交成功

code
enum<integer>
必填

业务状态码。200 表示成功,其他值都表示请求失败。请务必检查这个字段:部分参数校验错误会以 HTTP 200 返回,响应体里的 code 为 400。

  • 200:成功
  • 400:请求参数无效
  • 401:API Key 缺失或无效
  • 402:积分不足
  • 403:没有权限
  • 404:资源不存在
  • 408:请求超时
  • 429:请求频率超限
  • 500:服务器内部错误
  • 502:上游服务错误
  • 503:服务暂不可用

详见错误码。

可用选项:
200,
400,
401,
402,
403,
404,
408,
429,
500,
502,
503
示例:

200

data
object
必填