Configure apps to produce concise or detailed captions for single or multiple images

Captioning looks like a prompting problem and is mostly a schema problem. The length and depth of a caption are properties you configure — in a field's description, in how many fields you define, and in whether one analyzer runs across a whole set — and configuring them is what makes captions consistent across ten thousand images rather than merely good on one.

Why This Matters

Consistency is the hard part. A prompt produces a good caption; an analyzer produces the same kind of caption every time, because it "consistently applies these settings to all incoming data".

Concise and detailed are different fields, not different prompts. Defining both in one schema gets both in one pass, at one cost, from one reading of the image.

Multiple images are a single request shape. The API accepts multiple inputs — "inputs":[{"url": "..."}] — so batching is native rather than something you build.

Prerequisites

• The analyzer model: content extraction, fieldSchema, field methods.
• That generate produces free-form values and classify picks from an enum.
• Prompt techniques: specify output structure, prime the output, give the model an out.
• Confidence scores and grounding.

Learning Objectives

By the end of this lesson you will be able to:

1. Express concise and detailed captions as schema fields.
2. Write field descriptions that control length and focus.
3. Process multiple images in one request and keep output consistent.
4. Choose between prebuilt and custom analyzers for captioning.
5. Control cost and review effort with confidence scores.

Building Blocks

The prebuilt path. prebuilt-imageSearch produces image descriptions and summaries with no schema work — the fastest route to usable captions, and the right default when the caption need is generic.

The custom path. A fieldSchema where "each entry defines a field's name, type, and description", and each field carries a method:

Multiple inputs. A single request accepts several: "inputs":[{"url": "..."}].

Asynchronous processing. Analysis returns 202 Accepted with an Operation-Location header to poll — though "for interactive scenarios that need an immediate response from Read or Layout" there are synchronous operations.

Output. Markdown for search and retrieval scenarios, or structured JSON matching the schema.

Verification. Confidence scores from 0 to 1 per field, and grounding to the region a value came from.

Deep Dive

Length and depth belong in the field description

The instinct is to write one captioning prompt and tune it. The analyzer model asks for something better: name each output you want as a field, and put the specification in that field's description.

That description is where "concise" becomes operational. "One sentence, under 15 words, naming the main subject and action. No preamble." is a specification; "a short caption" is a hope. The same applies at the other end — "two to four sentences covering subject, setting, notable objects, and visible text" tells the model what detail means for your use case, which is not a universal fact.

Three properties make this better than prompt tuning.

Both variants come from one pass. A schema with shortCaption and detailedCaption yields both from a single reading of the image, rather than two calls that may disagree about what the image contains.

The specification is versioned with the analyzer. Changing what "concise" means is a schema change applied uniformly, not an edit scattered across call sites.

Structure is guaranteed. The response carries your field names, so downstream code binds to a contract.

Concise against detailed, and what each is for

The two lengths serve different consumers, and knowing which is which prevents a common design error.

Concise captions go where space is scarce and scanning is the behaviour: list views, thumbnails, search result rows, and — as the next objective covers — alt text. The discipline is a hard limit and a rule about what to name first, because a caption truncated mid-clause is worse than a shorter one written to fit.

Detailed descriptions go where the image cannot be seen or must be searched: RAG ingestion, media asset management, and long-form accessibility. Here the risk inverts — the model will happily produce a paragraph of confident detail about things that are ambiguous in the image.

Two controls address that. Say what to omit — speculation about identity, emotion, intent, or anything not visible. And give the model an out, so "the label text is not legible" is an available answer rather than a guessed string.

Where an image is mostly text, remember the documented exception: image analyzers "are not optimized for scenarios where analysis is based primarily on extracted text", and a document field extraction schema is the better instrument.

Many images at once

Two mechanisms make batch captioning practical.

Multiple inputs per request. The API accepts "inputs":[{"url": "..."}] with several entries, so a set is submitted together rather than one call per image.

One analyzer across the set. This is the more important of the two. Because the analyzer "consistently applies these settings to all incoming data", every image in a catalogue is captioned against the same specification — the same length, the same vocabulary, the same things named first. That consistency is what makes captions usable as a dataset rather than as ten thousand individual outputs.

The operational shape is asynchronous: a 202 Accepted with an Operation-Location header to poll. A captioning job over a large library is a queue-and-poll workflow, not a request-response one — though synchronous operations exist for interactive Read and Layout scenarios.

Cost, review, and confidence

Captioning a large library is a volume problem, and three levers control what it costs.

Field count. Every field is output the model generates. Defining six variants "in case they are useful" multiplies cost across the whole library. Define what will be consumed.

Detail level. A four-sentence description costs several times a fifteen-word caption. Where both are wanted, that is the argument for having both fields rather than defaulting everything to long.

Confidence-based routing. Scores from 0 to 1 per field are what enable "straight-through processing… minimizing manual review". Publish high-confidence captions automatically and queue low-confidence ones for a human, rather than reviewing everything or nothing.

The classification field earns its place here too: a classify field with an enum produces a clean facet for filtering and grouping, and being drawn from a closed vocabulary it is far more reliable to consume than a free-text category the model invents.

Worked Examples

Example 1 — short and long, disagreeing. A catalogue pipeline calls the service once for a thumbnail caption and again for a detail-page description; the two sometimes name different products.

Two calls are two independent readings. Define both as fields in one schema — shortCaption and detailedCaption, both generate — so a single pass produces consistent output at lower cost. Add a classify field with an enum for the product category.

Example 2 — "short" captions that are not short. Captions specified as "a brief caption" come back as two or three sentences and break the layout.

The field description is the specification. Replace it with a measurable one — "one sentence, under 15 words, naming the main subject and action, no preamble" — rather than tuning a prompt. Since the analyzer applies settings uniformly, the fix lands across the whole library at once.

Example 3 — captioning a large archive. A media team must caption 50,000 stills consistently and cannot review them all.

A custom analyzer so every image is captioned to the same specification; multiple inputs per request; the asynchronous 202 / Operation-Location poll loop; and confidence scores from 0 to 1 to auto-publish high-confidence captions while queueing the rest — the documented route to minimising manual review.

Visual Explanations

One schema, several outputs:

The batch shape:

Common Mistakes

Using extract for a caption. It is documents only; captions are generated.

Writing "a brief caption" as the description. Specify a measurable limit.

Generating short and long captions in separate calls. Two readings, possible disagreement.

Tuning prompts per call site instead of changing the schema.

Free-text categories where an enum would do. classify gives a clean facet.

Defining fields nobody consumes. Every field costs output tokens across the library.

Reviewing everything or nothing. Route on confidence scores.

Captioning text-heavy images with an image analyzer. Use a document schema.

Practice Exercises

1. Which method produces a caption, and which produces a category? Why is one method excluded?
2. Rewrite "a brief caption" as a usable field description.
3. Why define short and long captions in one schema rather than two calls?
4. Describe the request and response shape for captioning many images.
5. How do confidence scores change the review workload?

Summary & Concept Map

Captioning is configured, not prompted. Start with prebuilt-imageSearch for generic descriptions and summaries; move to a custom analyzer when the caption must meet a specification. Express each caption as a field whose description is the specification — word limits, what to name first, what to omit, and an out for illegible detail — using generate, since extract is documents only, and adding a classify field with an enum for clean categorical facets. Define short and long in one schema so a single reading produces both consistently at lower cost. For volume, submit multiple inputs per request, poll the 202 / Operation-Location loop, and route on confidence scores from 0 to 1 so review effort lands only where it is needed. And for text-primary images, switch to a document schema.

Sources and freshness

Written against current Microsoft Learn documentation for the AI-103 skills measured (16 April 2026), reviewed 2026-08-20. Microsoft Learn controls every changing product contract — availability, preview status, quotas, limits, regional support, naming, and retirement dates all move independently of this lesson. Where a scenario turns on a specific number or a GA/preview boundary, confirm it against the product's own page before relying on it.