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
The Ideogram 4.6 API generates up to 8 images from a text prompt, with strong on-image text rendering, four quality levels, custom sizes up to 4096 pixels per side, transparent backgrounds, and seeds.
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"
}
}- After submission, a
task_idwill be returned. If you provided acallback_url, when the task status becomesfinishedorfailed, a POST request will be sent to thecallback_url. - Regardless of whether
callback_urlis provided, you can retrieve the response result through the unified Query Task Status endpoint.
Ideogram 4.6 API models
- ideogram-v4.6 — Text-to-image generation with quality, size, background, and seed controls
- ideogram-v4.6-edit — Image editing with masks and reference images. See Ideogram V4.6 Edit
Ideogram 4.6 API features
- Text in images: Put the exact words in the prompt, for example a title or a sign, and the model renders them on the image.
- Four quality levels:
very_lowfor fast drafts, thenlow,medium(default), andhigh. - Sizes up to 4K:
auto, six aspect-ratio presets, or a customWIDTHxHEIGHTfrom 256 to 4096 pixels per side. - Transparent backgrounds: Set
backgroundtotransparentto get an image with an alpha channel, ready for stickers, icons, and logos. - Batches and seeds: Generate up to 8 images per request, and set
seedto repeat a result.
Required parameters
prompt(string): Description of the image, 1–10,000 characters. Must contain non-whitespace text. Put any exact on-image text in quotes.
Optional parameters
size(string):auto,1:1,1:1 HD,4:3,3:4,16:9,9:16, or a customWIDTHxHEIGHT. Default isauto. See Size.quality(string):very_low,low,medium, orhigh. Default ismedium.very_lowis limited to outputs of at most 4,194,304 pixels (2048×2048 in area).n(integer): Number of images,1to8. Default is1.background(string):transparentoropaque.transparentreturns an image with an alpha channel;opaqueforces a solid background. Omit it to let the model decide.seed(integer): Random seed,0to2147483647. Omit it to pick one automatically.callback_url(string): Optional webhook URL for task completion notification. Send it at the top level of the request, not insideinput.
input. Any other field is rejected with an unsupported fields error.
Size
size | Output |
|---|---|
auto (default) | The model picks a size of about 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 | Exactly as given |
x, for example 2048x1152. Both sides must be from 256 to 4096 pixels and multiples of 32, and the aspect ratio must be within 1:6 and 6:1. Sizes that the Ideogram 4.5 API accepted but are not multiples of 32, such as 1296x3168, are rejected.
Output
When the task isfinished, files contains one entry per generated image, each with file_url and file_type: image. With background set to transparent, the images have an alpha channel.
Ideogram 4.6 API examples
Send each Ideogram 4.6 API request below toPOST /api/generate/submit with your API key in the Authorization header.
Text To Image
{
"model": "ideogram-v4.6",
"callback_url": "https://your-domain.com/callback",
"input": {
"prompt": "A colorful storefront with a neon sign reading \"HELLO\""
}
}
auto, medium, one image).
Poster At 4K Size
{
"model": "ideogram-v4.6",
"input": {
"prompt": "A minimalist poster titled \"SUMMER JAZZ NIGHTS\", bold typography",
"size": "2048x3072",
"quality": "high",
"n": 2
}
}
2048x3072 is 6,291,456 pixels, which is above 4,194,304 pixels, so very_low is not available at this size.
Transparent Sticker
{
"model": "ideogram-v4.6",
"input": {
"prompt": "A flat sticker of a smiling coffee cup",
"size": "1:1 HD",
"quality": "low",
"background": "transparent",
"seed": 42
}
}
Notes
very_lowwith a custom size above 4,194,304 pixels is rejected with the message “very_low quality supports sizes up to 2048x2048 pixels in area (4,194,304 pixels)”.nmust be an integer. Strings and booleans are rejected.- Prompt expansion is always on for the Ideogram 4.6 API, as it is for Ideogram 4.5.
- Generated image files are accessible for 3 days after creation. Download and store them promptly.
- The response returns a
task_id. Query the task status to get the generated images.
Authorizations
All API endpoints require Bearer Token authentication.
Create an API key: sign in to PoYo, open Dashboard → API Key at poyo.ai/dashboard/api-key, and click to create a key.
Add it to the request header:
Authorization: Bearer YOUR_API_KEY
Body
application/json
Response
Task submitted successfully
Business status code. 200 means success; any other value means the request failed. Always check this field: some validation errors return HTTP 200 with code: 400 in the body.
200: Success400: Invalid request parameters401: Missing or invalid API key402: Insufficient credits403: Permission denied404: Resource not found408: Request timeout429: Rate limit exceeded500: Internal server error502: Upstream service error503: Service unavailable
See Error Codes for details.
Available options:
200, 400, 401, 402, 403, 404, 408, 429, 500, 502, 503 Example:
200