# Ideogram 4.5

> Generate images, posters and typography with Ideogram 4.5, or precisely edit a source image with masks and reference images. Compare quality-based pricing for generation and editing on PoYo.

## Overview

- Submit: `https://api.poyo.ai/api/generate/submit`
- Status: `https://api.poyo.ai/api/generate/status/{task_id}`
- Page: https://poyo.ai/models/ideogram-4-5
- Model page ID: `ideogram-4-5`
- API model IDs: `ideogram-v4.5`, `ideogram-v4.5-edit`
- Category: Image
- Auth: `Authorization: Bearer $POYO_API_KEY`
- Create a key at https://poyo.ai/dashboard/api-key

This model uses PoYo's unified async API. POST the JSON body below, then poll status with the returned `task_id` or receive a webhook on `callback_url`. Failed tasks are not charged.

## Pricing

- Text to image · low: 6 credits ($0.030) per image
- Text to image · medium: 12 credits ($0.060) per image
- Text to image · high: 44 credits ($0.220) per image
- Image editing · very low: 1.6 credits ($0.008) per image
- Image editing · low: 6 credits ($0.030) per image
- Image editing · medium: 12 credits ($0.060) per image
- Image editing · high: 44 credits ($0.220) per image

For more details, see https://poyo.ai/models/ideogram-4-5.

## API Information

The request envelope is always `{ model, input, callback_url? }`. Input fields below are nested under `input`.

### Request envelope

- `model` (`ModelEnum`, required):
  Use ideogram-v4.5 for text-to-image generation or ideogram-v4.5-edit for image editing.
  - Options: `"ideogram-v4.5"`, `"ideogram-v4.5-edit"`
- `callback_url` (`string`, optional):
  Optional completion or failure callback URL.

### Input Schema

The API accepts the following `input` parameters:

- `prompt` (`string`, required):
  Required for both ideogram-v4.5 and ideogram-v4.5-edit. Generation or editing prompt, 1–10,000 characters with non-whitespace content.
  - Length: 1 to 10000 characters
- `image_urls` (`list`, optional):
  Required only for ideogram-v4.5-edit; not supported by ideogram-v4.5. Exactly one primary source image, supplied as a public HTTP(S) image URL or image data URI.
  - Array of string
  - Length: 1 to 1
- `reference_image_urls` (`list`, optional):
  Optional, ideogram-v4.5-edit only. Up to four reference images without mask_url, or at most three with mask_url. Supply public HTTP(S) image URLs or image data URIs.
  - Array of string
  - Length: 0 to 4
- `mask_url` (`string`, optional):
  Optional, ideogram-v4.5-edit only. Public HTTP(S) image URL or image data URI. Must match the primary image dimensions and contain both black (edit) and white (preserve) areas; image-content requirements are checked during processing. Requires size=auto or omitted size.
- `n` (`integer`, optional):
  Number of output images for both models. Integer from 1 to 8; defaults to 1.
  - Default: `1`
  - Range: `1` to `8`
- `quality` (`QualityEnum`, optional):
  Output quality; defaults to medium for both models. ideogram-v4.5 accepts low, medium, and high. ideogram-v4.5-edit also accepts very_low.
  - Default: `"medium"`
  - Options: `"very_low"`, `"low"`, `"medium"`, `"high"`
- `size` (`string`, optional):
  ideogram-v4.5 defaults to 1:1 HD and accepts 1:1, 1:1 HD, 4:3, 3:4, 16:9, 9:16, or these exact sizes: 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 defaults to auto, which preserves the source size. A mask or edit_precision=high requires auto or omitted size. Explicit ratio presets or custom WIDTHxHEIGHT sizes require an unmasked regular edit. Custom edit dimensions must each be at least 256 and divisible by 32, total at most 4,194,304 pixels, and aspect ratio at most 6:1.
- `edit_precision` (`EditPrecisionEnum`, optional):
  Optional, ideogram-v4.5-edit only. Defaults to regular for image editing. high enables high-precision editing with unchanged-pixel restoration and requires size=auto or omitted size.
  - Options: `"regular"`, `"high"`

Required Parameters Example:

```json
{
  "model": "ideogram-v4.5",
  "input": {
    "prompt": "A ceramic robot with a clean silhouette."
  }
}
```

Full Example:

```json
{
  "model": "ideogram-v4.5",
  "input": {
    "prompt": "A ceramic robot with a clean silhouette.",
    "n": 1,
    "quality": "medium"
  }
}
```

Edit one primary image:

```json
{
  "model": "ideogram-v4.5-edit",
  "input": {
    "prompt": "Replace the background with a blue studio.",
    "image_urls": [
      "https://example.com/source.png"
    ]
  }
}
```

High-precision edit with a mask and reference:

```json
{
  "model": "ideogram-v4.5-edit",
  "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"
  }
}
```

### Output Schema

Submit returns a `task_id`. Poll `GET /api/generate/status/{task_id}` until `status` is `finished` or `failed`. Completed media is in `data.files`.

Response fields:

- `code` (`integer`, required):
  - Examples: `200`
- `data` (`object`, required):

Example Response:

```json
{
  "code": 200,
  "data": {
    "task_id": "task_example",
    "status": "finished",
    "files": [
      {
        "file_url": "https://storage.poyo.ai/models/ideogram-4-5/examples/ideogram-4-5-default-output-1-fc013428fbe75c6f.png",
        "file_type": "image"
      }
    ]
  }
}
```

## Usage Examples

### cURL

```bash
curl --request POST \
  --url https://api.poyo.ai/api/generate/submit \
  --header "Authorization: Bearer $POYO_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{"model":"ideogram-v4.5","input":{"prompt":"A ceramic robot with a clean silhouette."}}'
```

### Python

```python
import json
import os
import time
import requests

API = "https://api.poyo.ai"
headers = {
    "Authorization": f"Bearer {os.environ['POYO_API_KEY']}",
    "Content-Type": "application/json",
}
payload = json.loads("{\n  \"model\": \"ideogram-v4.5\",\n  \"input\": {\n    \"prompt\": \"A ceramic robot with a clean silhouette.\"\n  }\n}")

submit = requests.post(f"{API}/api/generate/submit", headers=headers, json=payload)
submit.raise_for_status()
task_id = submit.json()["data"]["task_id"]

while True:
    status = requests.get(f"{API}/api/generate/status/{task_id}", headers=headers)
    status.raise_for_status()
    data = status.json()["data"]
    if data["status"] in ("finished", "failed"):
        print(data)
        break
    time.sleep(2)
```

### JavaScript

```javascript
const headers = {
  Authorization: `Bearer ${process.env.POYO_API_KEY}`,
  "Content-Type": "application/json",
};

const submit = await fetch("https://api.poyo.ai/api/generate/submit", {
  method: "POST",
  headers,
  body: JSON.stringify({
  "model": "ideogram-v4.5",
  "input": {
    "prompt": "A ceramic robot with a clean silhouette."
  }
}),
});

const submitted = await submit.json();
const taskId = submitted.data.task_id;

while (true) {
  const statusResponse = await fetch(`https://api.poyo.ai/api/generate/status/${taskId}`, { headers });
  const status = await statusResponse.json();
  if (["finished", "failed"].includes(status.data.status)) {
    console.log(status.data);
    break;
  }
  await new Promise((resolve) => setTimeout(resolve, 2000));
}
```

## Additional Resources

### Documentation

- [Model Playground](https://poyo.ai/models/ideogram-4-5)
- [API Documentation](https://docs.poyo.ai/api-manual/image-series/ideogram-v4-5)
- [API Documentation (Markdown)](https://docs.poyo.ai/api-manual/image-series/ideogram-v4-5.md)
- [Task status](https://docs.poyo.ai/api-manual/task-management/query-task-status)
- [Webhooks](https://docs.poyo.ai/api-manual/task-management/webhooks)

### Other agent-readable surfaces

- [Platform overview](https://poyo.ai/llms.txt)
- [Documentation index](https://docs.poyo.ai/llms.txt)
- [Full documentation text](https://docs.poyo.ai/llms-full.txt)
- Any other model: `https://poyo.ai/models/<model-id>/llms.txt`