> ## Documentation Index
> Fetch the complete documentation index at: https://docs.poyo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

> [!TIP]
>
> 1. After submission, a `task_id` will be returned. If you provided a `callback_url`, when the task status becomes `finished` or `failed`, a POST request will be sent to the `callback_url`.
> 2. Regardless of whether `callback_url` is provided, you can retrieve the response result through the unified [Query Task Status](https://docs.poyo.ai/api-manual/task-management/status.md) endpoint.

The Ideogram 4.6 API brings Ideogram's latest image model to PoYo. Use it for posters, logos, packaging, social graphics, and any image where the words on the picture need to be right. The Ideogram 4.6 API takes a prompt and returns 1 to 8 images, with a choice of four quality levels, aspect-ratio presets or exact sizes up to 4096 pixels per side, and an optional transparent background. To change an existing image, use the [Ideogram 4.6 Edit API](https://docs.poyo.ai/api-manual/image-series/ideogram-v4-6-edit.md).

## 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](https://docs.poyo.ai/api-manual/image-series/ideogram-v4-6-edit.md)

## 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_low` for fast drafts, then `low`, `medium` (default), and `high`.
* **Sizes up to 4K**: `auto`, six aspect-ratio presets, or a custom `WIDTHxHEIGHT` from 256 to 4096 pixels per side.
* **Transparent backgrounds**: Set `background` to `transparent` to 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 `seed` to 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 custom `WIDTHxHEIGHT`. Default is `auto`. See [Size](#size).
* `quality` (string): `very_low`, `low`, `medium`, or `high`. Default is `medium`. `very_low` is limited to outputs of at most 4,194,304 pixels (2048×2048 in area).
* `n` (integer): Number of images, `1` to `8`. Default is `1`.
* `background` (string): `transparent` or `opaque`. `transparent` returns an image with an alpha channel; `opaque` forces a solid background. Omit it to let the model decide.
* `seed` (integer): Random seed, `0` to `2147483647`. 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 inside `input`.

The Ideogram 4.6 API accepts only these fields in `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 |

Custom sizes use a lowercase `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 is `finished`, `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 to `POST /api/generate/submit` with your API key in the `Authorization` header.

### Text To Image

```json theme={"dark"}
{
  "model": "ideogram-v4.6",
  "callback_url": "https://your-domain.com/callback",
  "input": {
    "prompt": "A colorful storefront with a neon sign reading \"HELLO\""
  }
}
```

This request uses the defaults (`auto`, `medium`, one image).

### Poster At 4K Size

```json theme={"dark"}
{
  "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

```json theme={"dark"}
{
  "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_low` with 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)".
* `n` must 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.


## OpenAPI

````yaml api-manual/image-series/ideogram-v4-6.json POST /api/generate/submit
openapi: 3.1.0
info:
  title: PoYo AI - Ideogram V4.6 API
  description: >-
    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.
  version: 1.0.0
servers:
  - url: https://api.poyo.ai
security:
  - BearerAuth: []
paths:
  /api/generate/submit:
    post:
      tags:
        - Ideogram V4.6
      summary: Submit Ideogram V4.6 Task
      description: >-
        Ideogram 4.6 API text-to-image generation with four quality levels,
        sizes up to 4096 pixels per side, transparent backgrounds, and seeds.
      operationId: submit_ideogram_v4_6
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SubmitRequest'
            examples:
              text-to-image:
                summary: Text To Image
                value:
                  model: ideogram-v4.6
                  callback_url: https://your-domain.com/callback
                  input:
                    prompt: A colorful storefront with a neon sign reading "HELLO"
              poster-4k:
                summary: Poster At 4K Size
                value:
                  model: ideogram-v4.6
                  input:
                    prompt: >-
                      A minimalist poster titled "SUMMER JAZZ NIGHTS", bold
                      typography
                    size: 2048x3072
                    quality: high
                    'n': 2
              transparent-sticker:
                summary: Transparent Sticker
                value:
                  model: ideogram-v4.6
                  input:
                    prompt: A flat sticker of a smiling coffee cup
                    size: 1:1 HD
                    quality: low
                    background: transparent
                    seed: 42
      responses:
        '200':
          description: Task submitted successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubmitResponse'
        '400':
          description: Invalid request parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized - Invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    SubmitRequest:
      type: object
      required:
        - model
        - input
      additionalProperties: false
      properties:
        model:
          type: string
          enum:
            - ideogram-v4.6
          description: Ideogram 4.6 text-to-image model identifier.
        callback_url:
          type: string
          format: uri
          description: Optional webhook URL for task completion or failure.
        input:
          type: object
          additionalProperties: false
          required:
            - prompt
          description: Generate 1-8 images from a prompt.
          properties:
            prompt:
              type: string
              minLength: 1
              maxLength: 10000
              pattern: \S
              description: >-
                Required. Description of the image, 1-10,000 characters. Must
                contain non-whitespace text. Put exact on-image text in quotes.
            size:
              type: string
              default: auto
              pattern: ^(auto|1:1|1:1 HD|4:3|3:4|16:9|9:16|[0-9]+x[0-9]+)$
              examples:
                - auto
                - 1:1 HD
                - '16:9'
                - 2048x2048
              description: >-
                auto (default; the model picks about 2K), 1:1 (512x512), 1:1 HD
                (1024x1024), 4:3, 3:4, 16:9, 9:16, or a custom WIDTHxHEIGHT with
                a lowercase x. Custom sides must be 256-4096 pixels and
                multiples of 32, with an aspect ratio within 1:6 and 6:1. Custom
                sizes above 4,194,304 pixels do not support very_low.
            quality:
              type: string
              enum:
                - very_low
                - low
                - medium
                - high
              default: medium
              description: >-
                Output quality. Defaults to medium. very_low is only available
                for outputs up to 4,194,304 pixels (2048x2048 in area).
            'n':
              type: integer
              minimum: 1
              maximum: 8
              default: 1
              description: Number of output images, 1-8. Defaults to 1. Must be an integer.
            background:
              type: string
              enum:
                - transparent
                - opaque
              description: >-
                Optional. transparent returns an image with an alpha channel;
                opaque forces a solid background. Omit for the model default.
            seed:
              type: integer
              minimum: 0
              maximum: 2147483647
              description: >-
                Optional random seed, 0-2147483647. Omit to pick one
                automatically.
    SubmitResponse:
      type: object
      required:
        - code
        - data
      properties:
        code:
          type: integer
          example: 200
          enum:
            - 200
            - 400
            - 401
            - 402
            - 403
            - 404
            - 408
            - 429
            - 500
            - 502
            - 503
          description: >-
            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`: Success

            - `400`: Invalid request parameters

            - `401`: Missing or invalid API key

            - `402`: Insufficient credits

            - `403`: Permission denied

            - `404`: Resource not found

            - `408`: Request timeout

            - `429`: Rate limit exceeded

            - `500`: Internal server error

            - `502`: Upstream service error

            - `503`: Service unavailable


            See [Error Codes](/api-manual/error-codes) for details.
        data:
          type: object
          required:
            - task_id
            - status
            - created_time
          properties:
            task_id:
              type: string
              example: task-unified-1757165031-uyujaw3d
            status:
              type: string
              enum:
                - not_started
                - running
                - finished
                - failed
              example: not_started
              description: >-
                Task status. Always `not_started` right after submission. Use
                [Query Task Status](/api-manual/task-management/status) or
                `callback_url` to get later states.


                - `not_started`: Queued, waiting to be processed

                - `running`: Being generated

                - `finished`: Completed; results are in `files` or `output`

                - `failed`: Failed; details are in `error_message`
            created_time:
              type: string
              format: date-time
              example: '2026-10-13T10:30:00+08:00'
    ErrorResponse:
      type: object
      required:
        - code
        - error
      properties:
        code:
          type: integer
          example: 400
          enum:
            - 200
            - 400
            - 401
            - 402
            - 403
            - 404
            - 408
            - 429
            - 500
            - 502
            - 503
          description: >-
            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`: Success

            - `400`: Invalid request parameters

            - `401`: Missing or invalid API key

            - `402`: Insufficient credits

            - `403`: Permission denied

            - `404`: Resource not found

            - `408`: Request timeout

            - `429`: Rate limit exceeded

            - `500`: Internal server error

            - `502`: Upstream service error

            - `503`: Service unavailable


            See [Error Codes](/api-manual/error-codes) for details.
        error:
          type: object
          required:
            - message
            - type
          properties:
            message:
              type: string
              example: Invalid request parameters
            type:
              type: string
              example: invalid_request_error
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: >-
        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](https://poyo.ai/dashboard/api-key), and
        click to create a key.


        Add it to the request header:


        ```

        Authorization: Bearer YOUR_API_KEY

        ```

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.