Describe with Ideogram 4.0 | Ideogram

curl -X POST https://api.ideogram.ai/v1/ideogram-v4/describe \
  -H "Api-Key: <apiKey>" \
  -H "Content-Type: multipart/form-data" \
  -F image_file=@<file1>

{
  "json_prompt": {
    "high_level_description": "high_level_description",
    "compositional_deconstruction": {
      "background": "background",
      "elements": [
        {
          "type": "obj",
          "bbox": [
            0,
            0,
            1000,
            1000
          ],
          "desc": "desc"
        },
        {
          "type": "obj",
          "bbox": [
            0,
            0,
            1000,
            1000
          ],
          "desc": "desc"
        }
      ]
    },
    "style_description": {
      "aesthetics": "aesthetics",
      "lighting": "lighting",
      "medium": "medium",
      "art_style": "art_style",
      "photo": "photo"
    }
  }
}

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.

curl -X POST https://api.ideogram.ai/v1/ideogram-v4/describe \
  -H "Api-Key: <apiKey>" \
  -H "Content-Type: multipart/form-data" \
  -F image_file=@<file1>

{
  "json_prompt": {
    "high_level_description": "high_level_description",
    "compositional_deconstruction": {
      "background": "background",
      "elements": [
        {
          "type": "obj",
          "bbox": [
            0,
            0,
            1000,
            1000
          ],
          "desc": "desc"
        },
        {
          "type": "obj",
          "bbox": [
            0,
            0,
            1000,
            1000
          ],
          "desc": "desc"
        }
      ]
    },
    "style_description": {
      "aesthetics": "aesthetics",
      "lighting": "lighting",
      "medium": "medium",
      "art_style": "art_style",
      "photo": "photo"
    }
  }
}

Supported image formats include JPEG, PNG, and WebP.

Authentication

Api-Keystring

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

Request

This endpoint expects a multipart form containing a file.

image_filefileRequired

An image binary (max size 10MB); only JPEG, WebP and PNG formats are supported at this time.

include_bboxbooleanOptionalDefaults to true

When true (default), the response preserves bounding boxes on each element so the prompt can be pasted into /v1/ideogram-v4/generate as json_prompt and reproduce the source layout. Set to false to drop bounding boxes and let the sampler place elements freely.

Response

Structured V4 prompt generated successfully.

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

422

Unprocessable Entity Error

429

Too Many Requests Error

503

Service Unavailable Error

$	curl -X POST https://api.ideogram.ai/v1/ideogram-v4/describe \
>	-H "Api-Key: <apiKey>" \
>	-H "Content-Type: multipart/form-data" \
>	-F image_file=@<file1>

1	{
2	"json_prompt": {
3	"high_level_description": "high_level_description",
4	"compositional_deconstruction": {
5	"background": "background",
6	"elements": [
7	{
8	"type": "obj",
9	"bbox": [
10	0,
11	0,
12	1000,
13	1000
14	],
15	"desc": "desc"
16	},
17	{
18	"type": "obj",
19	"bbox": [
20	0,
21	0,
22	1000,
23	1000
24	],
25	"desc": "desc"
26	}
27	]
28	},
29	"style_description": {
30	"aesthetics": "aesthetics",
31	"lighting": "lighting",
32	"medium": "medium",
33	"art_style": "art_style",
34	"photo": "photo"
35	}
36	}
37	}