image-describe

Describe with Ideogram 4.0

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.

post/v2/image/describe/ideogram-4

Request body

imagestring 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_bboxboolean

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_descriptionsboolean

Whether to include a free-form style description on the returned json_prompt. Defaults to false.

include_tagsboolean

Whether to include the captioner's free-form tags on the returned json_prompt. Defaults to false.

Example request

{
  "image_asset_identifier": {
    "asset_type": "RESPONSE",
    "asset_id": "7uS_VESkRI6O3-sVgHQp_A"
  }
}

Response

Structured prompt generated successfully.

description_idstring required

URL-safe base64 ID of the description that was created.

createdstring date-time required

The time the request was created.

Example response

{
  "description_id": "description_id",
  "created": "2000-01-23T04:56:07+00:00",
  "json_prompt": {
    "high_level_description": "high_level_description",
    "style_description": {
      "photo": "photo",
      "art_style": "art_style",
      "medium": "medium",
      "aesthetics": "aesthetics",
      "lighting": "lighting",
      "color_palette": [
        "#FFD700",
        "#FFD700"
      ]
    },
    "compositional_deconstruction": {
      "background": "background",
      "elements": [
        {
          "bbox": [
            0,
            0,
            1000,
            1000
          ],
          "type": "obj",
          "desc": "desc",
          "color_palette": [
            "#FFD700",
            "#FFD700"
          ]
        },
        {
          "bbox": [
            0,
            0,
            1000,
            1000
          ],
          "type": "obj",
          "desc": "desc",
          "color_palette": [
            "#FFD700",
            "#FFD700"
          ]
        }
      ]
    },
    "tags": [
      "tags",
      "tags"
    ]
  }
}

Changes

Changed in 2 of the 33 revisions of this API.5

Sep 27, 2026987f73fc82de4See the full diff
- ○
  added the optional property to the response with the status
  response-optional-property-added
- ○
  added the optional property to the response with the status
  response-optional-property-added
- ○
  added the optional property to the response with the status
  response-optional-property-added
- ○
  added the optional property to the response with the status
  response-optional-property-added
Sep 18, 2026cb077a6ff5801See the full diff
- ○
  endpoint added
  endpoint-added

Full history