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.

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