Share via

prebuilt-layout/read returns 0 figures for DOCX with images (Azure Document Intelligence).

Noor Ul Amin 0 Reputation points
2026-03-16T14:58:40.27+00:00

Hi,

I’m using Azure Document Intelligence (Python SDK) with the prebuilt-layout model to analyze a .docx document that contains many embedded images (screenshots). I’m trying to use the figures output, but it’s always empty.

Here is a simplified version of my code
from azure.ai.documentintelligence import DocumentIntelligenceClient

from azure.core.credentials import AzureKeyCredential

client = DocumentIntelligenceClient(

endpoint=AZURE_DOC_INTELLIGENCE_ENDPOINT,

credential=AzureKeyCredential(AZURE_DOC_INTELLIGENCE_KEY),

)

with open("knowledge-base.docx", "rb") as fh:

poller = client.begin_analyze_document(

model_id="prebuilt-layout",

body=fh

)

result = poller.result()

print(

"paragraphs:", len(result.paragraphs or []),

"tables:", len(result.tables or []),

"pages:", len(result.pages or []),

"figures:", len(result.figures or []),

)

For my DOCX, I consistently get something like:

  • paragraphs: 1797
  • tables: 19
  • pages: 1
  • figures: 0

Even though the document clearly contains many images on diff pages. One more thing: I always get 1 page, even though there are 88 pages.

My question:

  1. Is there any feature flag or configuration I need to pass (e.g. via the features parameter of begin_analyze_document) to enable figures extraction?
    • I’ve checked DocumentAnalysisFeature in the SDK (OCR_HIGH_RESOLUTION, LANGUAGES, BARCODES, FORMULAS, KEY_VALUE_PAIRS, STYLE_FONT, QUERY_FIELDS) but there is nothing related to figures.

Environment details:

  • SDK: azure-ai-documentintelligence==1.02 (Python) – version: 3.13.5
  • File type: .docx

Any guidance on whether figures is expected to work for DOCX, and what configuration or file-type constraints apply, would be very helpful.

Foundry Tools
Foundry Tools

Formerly known as Azure AI Services or Azure Cognitive Services is a unified collection of prebuilt AI capabilities within the Microsoft Foundry platform

0 comments

2 answers

Sort by: Most helpful
Most helpful Newest Oldest
  1. SAI JAGADEESH KUDIPUDI 2,625 Reputation points Microsoft External Staff Moderator
    2026-04-28T17:26:04.64+00:00

    Hi Noor Ul Amin,
    it looks like you’ve hit a couple of current service limitations rather than a missing SDK flag.

    1. No “figures” feature flag • The DocumentAnalysisFeature enum in the SDK doesn’t include a flag for figures because figure extraction is implicit and, as of today, it’s only functional on image/PDF inputs. • Embedded images in Office files (DOCX, PPTX, XLSX) aren’t yet surfaced as result.figures by the prebuilt-layout model.
    2. One-page DOCX behavior • Under the hood the service converts non-PDF inputs to a single “page” before running layout analysis, so you’ll always see pages: 1 for a DOCX. • If you need true page boundaries and embedded-image extraction, convert your DOCX to PDF first (or export each page as an image/PDF) and then call prebuilt-layout. You should then get correct page counts and non‐empty result.figures.

    Workarounds

    • Convert DOCX → PDF (or image) outside the service, then call prebuilt-layout on that PDF/image.

    • Pull images directly from DOCX via a library like python-docx if you only want the raw pictures.

    There’s no hidden “enable figures” switch in the SDK or portal today—this is a known gap in the GA layout model. We’re tracking figure support for Office docs in upcoming releases.

    Hope that clarifies things!

    Microsoft Reference Links:

    • Layout model overview & supported file types

    https://learn.microsoft.com/azure/ai-services/document-intelligence/prebuilt/layout?view=doc-intel-4.0.0#development-options

    • Supported document elements (including Figures)

    https://learn.microsoft.com/azure/ai-services/content-understanding/document/elements?wt.mc_id=knowledgesearch_inproduct_azure-cxp-community-insider#document-elements

    • Analysis features by model (no Figures column for prebuilt-layout)

    https://learn.microsoft.com/azure/ai-services/document-intelligence/overview?view=doc-intel-4.0.0&wt.mc_id=knowledgesearch_inproduct_azure-cxp-community-insider#analysis-features

    • Service limits & input requirements

    https://learn.microsoft.com/azure/ai-services/document-intelligence/service-limits

    https://learn.microsoft.com/azure/ai-services/document-intelligence/prebuilt/layout?view=doc-intel-4.0.0#input-requirements

  2. Q&A Assist
    2026-03-16T14:59:00.0466667+00:00
    AI generated content. This question contains an answer created with AI from Q&A Assist. Learn more

    figures extraction is controlled by the model and the output parameter, not by the features flags. The available DocumentAnalysisFeature values (such as KEY_VALUE_PAIRS, STYLE_FONT, etc.) do not include anything related to figures, so there is no feature flag to turn figures on or off.

    For the prebuilt-layout model in v4.0, figures are supported and exposed via the figures collection in the analyze result. When output=figures is specified in the initial analyze operation, the service also generates cropped images for each detected figure, which can then be retrieved via /analyzeResults/{resultId}/figures/{figureId}. The FigureId follows the {pageNumber}.{figureIndex} convention, and each figure object contains boundingRegions, spans, elements, and an optional caption.

    However, the context only documents figures behavior and output shape; it does not state that DOCX is a supported input type for figure detection, nor does it describe any configuration or feature flag that would make figures appear for DOCX specifically. The same applies to the page-count behavior you are seeing: the documentation describes how pages, tables, and figures are represented, but does not provide any guidance or guarantees for DOCX pagination.

    From the available documentation, the only configuration related to figures is:

    • Use the prebuilt-layout model.
    • Specify output=figures in the analyze request if cropped figure images are needed.

    There is no documented feature flag to enable figures, and no documented DOCX-specific support or constraint for figure extraction or page counting.

    References:

Your answer

Answers can be marked as 'Accepted' by the question author and 'Recommended' by moderators, which helps users know the answer solved the author's problem.