curl --request POST \
--url https://api.poyo.ai/api/generate/submit \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"model": "ideogram-v4.6",
"callback_url": "https://your-domain.com/callback",
"input": {
"prompt": "A colorful storefront with a neon sign reading \"HELLO\""
}
}
'{
"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.6
Ideogram 4.6 API 根据文本提示词一次生成最多 8 张图像,图上文字渲染准确,提供四档质量、每边最高 4096 像素的自定义尺寸、透明背景和随机种子。
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.6",
"callback_url": "https://your-domain.com/callback",
"input": {
"prompt": "A colorful storefront with a neon sign reading \"HELLO\""
}
}
'{
"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 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。
input 只接受以上字段。传入其他字段会返回 unsupported fields 错误。
尺寸
size | 输出 |
|---|---|
auto(默认) | 由模型选择约 2K 的尺寸 |
1:1 | 512×512 |
1:1 HD | 1024×1024 |
4:3 | 1024×768 |
3:4 | 768×1024 |
16:9 | 1024×576 |
9:16 | 576×1024 |
WIDTHxHEIGHT | 按填写的宽高输出 |
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。
文生图
{
"model": "ideogram-v4.6",
"callback_url": "https://your-domain.com/callback",
"input": {
"prompt": "A colorful storefront with a neon sign reading \"HELLO\""
}
}
auto、medium、一张图)。
4K 尺寸海报
{
"model": "ideogram-v4.6",
"input": {
"prompt": "A minimalist poster titled \"SUMMER JAZZ NIGHTS\", bold typography",
"size": "2048x3072",
"quality": "high",
"n": 2
}
}
2048x3072 为 6,291,456 像素,超过 4,194,304 像素,因此该尺寸不能使用 very_low。
透明背景贴纸
{
"model": "ideogram-v4.6",
"input": {
"prompt": "A flat sticker of a smiling coffee cup",
"size": "1:1 HD",
"quality": "low",
"background": "transparent",
"seed": 42
}
}
注意事项
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,请通过查询任务状态获取生成的图像。
授权
所有 API 接口都需要 Bearer Token 认证。
创建 API Key:登录 PoYo,进入 仪表盘 → API 密钥(poyo.ai/zh/dashboard/api-key),点击创建 Key。
在请求头中添加:
Authorization: Bearer YOUR_API_KEY
请求体
application/json
响应
任务提交成功
业务状态码。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