Describe with Ideogram 4.0 | Ideogram

{
  "description_id": "description_id",
  "created": "2024-01-15T09:30:00Z",
  "json_prompt": {
    "high_level_description": "high_level_description",
    "compositional_deconstruction": {
      "background": "background",
      "elements": [
        {
          "type": "obj",
          "desc": "desc",
          "bbox": [
            0,
            0,
            1000,
            1000
          ],
          "color_palette": [
            "#FFD700",
            "#FFD700"
          ]
        },
        {
          "type": "obj",
          "desc": "desc",
          "bbox": [
            0,
            0,
            1000,
            1000
          ],
          "color_palette": [
            "#FFD700",
            "#FFD700"
          ]
        }
      ]
    },
    "style_description": {
      "aesthetics": "aesthetics",
      "art_style": "art_style",
      "lighting": "lighting",
      "medium": "medium",
      "photo": "photo",
      "color_palette": [
        "#FFD700",
        "#FFD700"
      ]
    }
  }
}

Describe an image as a structured V4JsonPrompt with Ideogram’s 4.0 image captioner (a fine-tune of the Qwen3-VL vision-language model). Upload the image as image using multipart/form-data; the json_prompt is returned directly and can be passed to the /v1/ideogram-v4/generate endpoints.

Authentication

Api-Keystring

API key for access control. Use in the header with the name "Api-Key"

Request

A request to describe one image. Send it as multipart/form-data with the image to describe.

imagefileRequired

The image to describe (max 10MB). JPEG, PNG, and WebP are supported. Multipart requests only.

include_bboxbooleanOptionalDefaults to true

Whether to include bounding boxes for the subjects and text in the returned json_prompt. Defaults to true, so the prompt preserves the layout of the described image.

include_style_descriptionsbooleanOptionalDefaults to false

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

include_tagsbooleanOptionalDefaults to false

Whether to include free-form tags in the returned json_prompt. Defaults to false.

Response

Structured prompt generated successfully.

description_idstring

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

createddatetime

The time the request was created.

json_promptobject

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.

Errors

400

Bad Request Error

401

Unauthorized Error

402

Payment Required Error

404

Not Found Error

422

Unprocessable Entity Error

429

Too Many Requests Error

500

Internal Server Error

503

Service Unavailable Error