---
title: "Describe with Ideogram 4.0"
method: POST
path: "/v2/image/describe/ideogram-4"
tags: ["image-describe"]
---

# Describe with Ideogram 4.0

`POST /v2/image/describe/ideogram-4`

Describe an image using Ideogram's 4.0-generation image captioner (a
fine-tune of the Qwen3-VL vision-language model) and return a
structured `V4JsonPrompt`. The
returned `json_prompt` is a working JSON prompt that can be passed
directly as `json_prompt` to the `/v1/ideogram-v4/generate` family of
endpoints.

Supply the source either as an `image_asset_identifier` reference (an
image already stored with Ideogram) or as raw `image` bytes (multipart
requests only). Provide exactly one of the two forms; supplying both,
or neither, is rejected with a 400.

Supported image formats include JPEG, PNG, and WebP.

## Request body

- DescribeImageIdeogramV4Request — Supply the source image either as an `image_asset_identifier` reference or (multipart requests only) as raw `image` bytes. Provide exactly one of the two forms; supplying both, or neither, is rejected with a 400.
  - `image_asset_identifier` AssetIdentifier — An identifier for an ideogram asset.
    - `asset_type` 'ASSET' | 'CANVAS_ASSET' | 'LAYERED_ASSET' | 'RESPONSE' | 'UPLOAD', required
    - `asset_id` string, required
  - `image` string, binary — The image to describe (max size 10MB), as raw bytes; only JPEG, PNG, and WebP formats are supported. Multipart requests only. Provide exactly one of `image_asset_identifier` or `image`.
  - `include_bbox` boolean — Whether to include bounding boxes on the subjects and texts of the returned `json_prompt`. Defaults to true so the prompt preserves the spatial layout of the described image.
  - `include_style_descriptions` boolean — Whether to include a free-form style description on the returned `json_prompt`. Defaults to false.
  - `include_tags` boolean — Whether to include the captioner's free-form tags on the returned `json_prompt`. Defaults to false.

## Response `200`

Structured prompt generated successfully.

- DescribeImageIdeogramV4Response — Response returned by `POST /v2/image/describe/ideogram-4`. The `json_prompt` field is a structured `V4JsonPrompt` that can be passed back as `json_prompt` to the `/v1/ideogram-v4/generate` family of endpoints.
  - `description_id` string, required — URL-safe base64 ID of the description that was created.
  - `created` string, date-time, required — The time the request was created.
  - `json_prompt` V4JsonPrompt, required — Structured prompt for Ideogram 4.0 generation. When `json_prompt` is supplied, magic-prompt is disabled and the diffusion model consumes the JSON contract directly. Mutually exclusive with `text_prompt` and the legacy `prompt` field.
    - `high_level_description` string, required — One- or two-sentence overall description of the desired image.
    - `style_description` V4StyleDescription — Optional style description supplied alongside a V4 JSON prompt.
      - `aesthetics` string — Aesthetic notes (mood, vibe, references).
      - `art_style` string — Optional art-style hint (e.g., illustration, oil painting).
      - `lighting` string — Lighting description.
      - `medium` string — Medium description (e.g., photograph, digital art).
      - `photo` string — Optional photographic style notes (e.g., lens, film stock).
      - `color_palette` string[] — Optional list of hex color strings (e.g. "#FFD700") that bias the Ideogram 4.0 output toward this palette. Applied as a soft color bias, not an exact per-pixel lock.
    - `compositional_deconstruction` V4CompositionalDeconstruction, required — The compositional breakdown of a V4 prompt — background plus an ordered list of elements.
      - `background` string, required — Description of the background of the scene.
      - `elements` V4PromptElement[], required — Ordered list of elements (objects and text) composing the scene.
        - union — A single element in the V4 prompt's compositional deconstruction. Discriminated by the `type` field.
          - object — A non-text element (object, character, background detail) in the V4 prompt layout.
            - `type` 'obj', required — Discriminator. Must be `obj`.
            - `bbox` integer[] — Bounding box for an element, expressed as four integers in `[0, 1000]` with `[y_min, x_min, y_max, x_max]` semantics (row-first). Values are normalized so the canvas is `1000 x 1000` regardless of the final resolution.
            - `desc` string, required — Description of the object element.
            - `color_palette` string[] — Optional list of hex color strings (e.g. "#FFD700") that bias the Ideogram 4.0 output toward this palette. Applied as a soft color bias, not an exact per-pixel lock.
          - object — A text element to render in the V4 prompt layout.
            - `type` 'text', required — Discriminator. Must be `text`.
            - `bbox` integer[] — Bounding box for an element, expressed as four integers in `[0, 1000]` with `[y_min, x_min, y_max, x_max]` semantics (row-first). Values are normalized so the canvas is `1000 x 1000` regardless of the final resolution.
            - `text` string, required — The literal text to render in the image.
            - `desc` string, required — Description of the text element (style, role, placement notes).
            - `color_palette` string[] — Optional list of hex color strings (e.g. "#FFD700") that bias the Ideogram 4.0 output toward this palette. Applied as a soft color bias, not an exact per-pixel lock.
    - `tags` string[] — Round-trip metadata surfaced by the describe endpoint when `strip_tags=false`. Ignored by the v4 sampler on generate input.

## Other responses

- `400` — Invalid input provided.
- `401` — Unauthorized.
- `402` — Insufficient credits or quota.
- `404` — The referenced source asset was not found.
- `422` — Image failed the safety check.
- `429` — Too many requests.
- `500` — Internal server error.
- `503` — The endpoint is temporarily unavailable.

## Changes

- **2026-09-18** `cb077a6ff580` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/ideogram/apis/ideogram-openapi-3-0/changes/v2/image/describe/ideogram-4/post.md)

---

[API](https://skmtc.dev/ideogram/apis/ideogram-openapi-3-0.md) · [All operations](https://skmtc.dev/ideogram/apis/ideogram-openapi-3-0/llms.txt) · [OpenAPI document](https://skmtc.dev/ideogram/apis/ideogram-openapi-3-0/revisions/cb077a6ff580?raw)