---
title: "Describe with Ideogram 4.0"
method: POST
path: "/v1/ideogram-v4/describe"
tags: ["vision"]
---

# Describe with Ideogram 4.0

`POST /v1/ideogram-v4/describe`

Describe an image with Ideogram 4.0 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.

Supported image formats include JPEG, PNG, and WebP.

## Headers

- `Api-Key` string, required

## Response `200`

Structured V4 prompt generated successfully.

- DescribeResponseV4 — The response for an Ideogram 4.0 describe request. 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.
  - `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.
          - V4ObjPromptElement — 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.
          - V4TextPromptElement — 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.

## Other responses

- `400` — Invalid input provided.
- `422` — Image failed the safety check.
- `429` — Too many requests.
- `503` — Took too long to finish.

---

[API](https://skmtc.net/ideogram/apis/api-reference.md) · [All operations](https://skmtc.net/ideogram/apis/api-reference/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/ideogram/api-reference/versions/f6a8c81158c0/schema)