curl --request POST \
--url https://api.poyo.ai/api/generate/submit \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"model": "ideogram-v4.5",
"input": {
"prompt": "A ceramic robot with a clean silhouette."
}
}
'{
"code": 200,
"data": {
"task_id": "task-unified-1757165031-uyujaw3d",
"status": "not_started",
"created_time": "2026-10-13T10:30:00+08:00"
}
}{
"code": 400,
"error": {
"message": "Invalid request parameters",
"type": "invalid_request_error"
}
}{
"code": 400,
"error": {
"message": "Invalid request parameters",
"type": "invalid_request_error"
}
}Ideogram
Ideogram V4.5
Ideogram 4.5 API 根据提示词生成图像，或编辑一张主图。编辑时最多可添加四张参考图，设置蒙版时最多三张；高精度模式会保留未编辑区域的像素。
POST
/
api
/
generate
/
submit
curl --request POST \
--url https://api.poyo.ai/api/generate/submit \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"model": "ideogram-v4.5",
"input": {
"prompt": "A ceramic robot with a clean silhouette."
}
}
'{
"code": 200,
"data": {
"task_id": "task-unified-1757165031-uyujaw3d",
"status": "not_started",
"created_time": "2026-10-13T10:30:00+08:00"
}
}{
"code": 400,
"error": {
"message": "Invalid request parameters",
"type": "invalid_request_error"
}
}{
"code": 400,
"error": {
"message": "Invalid request parameters",
"type": "invalid_request_error"
}
}- 提交后会返回
task_id。如果提供了callback_url，当任务状态变为finished或failed时，系统会向callback_url发送 POST 请求。 - 无论是否提供
callback_url，都可以通过统一的查询任务状态接口获取结果。
模型
- ideogram-v4.5 - 文生图，支持质量和尺寸控制
- ideogram-v4.5-edit - 编辑恰好一张主图，可选参考图、蒙版和精度控制
必填参数
- model：
ideogram-v4.5或ideogram-v4.5-edit - input.prompt：两个模型均必填。使用
1-10000个字符，且须包含非空白文本 - input.image_urls：
ideogram-v4.5-edit必填。恰好一张主图。ideogram-v4.5不支持
可选参数
- n：输出图像数量。取值为
1到8的整数。默认为1 - quality：输出质量。默认为
medium。ideogram-v4.5接受low、medium和high。ideogram-v4.5-edit还接受very_low - size：输出尺寸。参见下方的尺寸规则
- reference_image_urls：仅限编辑。不使用蒙版时最多四张参考图，设置
mask_url时最多三张 - mask_url：仅限编辑。必须与主图尺寸一致，且同时包含黑色编辑区域和白色保留区域。图像内容要求在处理过程中检查。需要
size=auto或省略size - edit_precision：仅限编辑。
regular或high。默认为regular。high会还原未改动的像素，需要size=auto或省略size - callback_url：可选的 Webhook URL，用于任务完成通知
尺寸
ideogram-v4.5 默认为 1:1 HD。它接受宽高比 1:1、1:1 HD、4:3、3:4、16:9 和 9:16，或以下任一精确尺寸：
1024x1024, 1024x3072, 1120x896, 1152x2944, 1152x864, 1248x3328, 1248x832, 1280x3072, 1280x720, 1280x800, 1296x3168, 1440x2560, 1440x2880, 1440x720, 1600x2560, 1664x2496, 1728x2304, 1792x2240, 2048x2048, 2240x1792, 2304x1728, 2496x1664, 2560x1440, 2560x1600, 2880x1440, 2944x1152, 3072x1024, 3072x1280, 3168x1296, 3328x1248, 720x1280, 720x1440, 800x1280, 832x1248, 864x1152, 896x1120.
ideogram-v4.5-edit 默认为 auto，保留源图尺寸。
- 使用蒙版或
edit_precision=high时，需要auto或省略尺寸。 - 比例预设和自定义
WIDTHxHEIGHT尺寸仅适用于无蒙版的常规编辑。 - 自定义编辑尺寸的每个维度至少为
256且能被32整除，总像素数不超过4,194,304，宽高比不超过6:1。
示例
生成图像
{
"model": "ideogram-v4.5",
"callback_url": "https://your-domain.com/callback",
"input": {
"prompt": "A ceramic robot with a clean silhouette."
}
}
编辑图像
{
"model": "ideogram-v4.5-edit",
"callback_url": "https://your-domain.com/callback",
"input": {
"prompt": "Replace the background with a blue studio.",
"image_urls": [
"https://example.com/source.png"
]
}
}
高精度蒙版编辑
{
"model": "ideogram-v4.5-edit",
"callback_url": "https://your-domain.com/callback",
"input": {
"prompt": "Replace the black mask area with flowers.",
"image_urls": [
"https://example.com/source.png"
],
"mask_url": "https://example.com/mask.png",
"reference_image_urls": [
"https://example.com/flowers.png"
],
"edit_precision": "high"
}
}
注意事项
ideogram-v4.5-edit要求image_urls中恰好有一张主图。- 通过标准的任务状态 API 查询状态。
- 成功响应返回
files，其中生成的图像为file_type: image。
授权
所有 API 接口都需要 Bearer Token 认证。
创建 API Key：登录 PoYo，进入 仪表盘 → API 密钥（poyo.ai/zh/dashboard/api-key），点击创建 Key。
在请求头中添加：
Authorization: Bearer YOUR_API_KEY
请求体
application/json
响应
任务已受理；请查询任务获取最终文件。
Show child attributes
Show child attributes