← Blog

Claude Prefill: Control Output with the Assistant Turn

October 26, 2026

Learn how Claude's assistant-turn prefill works in the API, when to use it over instructions or tool_choice, and which models support it.

Claude prefill places text in the assistant turn of your API request so Claude continues from that starting point. It reliably anchors output format — open with {" and Claude stays in JSON — without relying on instruction-following alone. The Anthropic API supports this via the content field on an assistant-role message at the end of your messages array.

Plinth Prep is an independent study resource, not affiliated with, endorsed by, or sponsored by Anthropic. Technical details here are based on published Anthropic documentation; verify against current API docs for your model.

What Is Claude Prefill and How Does It Work in the API?

Every call to the Claude Messages API sends a messages array — a sequence of turns alternating between user and assistant roles. Normally the array ends on a user turn, and Claude generates the next assistant turn from scratch.

Prefilling changes that. You add one final entry with "role": "assistant" and set its content to whatever opening text you want Claude to continue from. Claude then completes that response rather than starting a new one. The effect is mechanical: generation picks up exactly where your text ended.

This gives you a control point that operates below the instruction layer. Instead of telling Claude "respond only with valid JSON," you hand it the first character of valid JSON and it completes the structure.

How Do You Add a Prefill to an API Request? (Code Walkthrough)

The only structural change is appending the prefill message to the end of messages. Here is a minimal Python example using Claude Haiku 4.5 — a model that currently supports the technique:

import anthropic

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-haiku-4-5",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": "List three programming languages as a JSON array."
        },
        {
            "role": "assistant",
            "content": '["'  # Prefill: Claude continues inside the array
        }
    ]
)

# response.content[0].text contains only what Claude generated AFTER the prefill
# Concatenate to reconstruct the full output:
full_output = '["' + response.content[0].text
# full_output → '["Python", "JavaScript", "Go"]'

Three mechanics to keep in mind:

  • The prefill string does not appear in response.content[0].text — only Claude's continuation does. You must concatenate them yourself.
  • The prefill can be any length; a single character like { works as well as a longer opening phrase.
  • The messages array must still alternate roles correctly elsewhere. Only the final assistant turn acts as the prefill.

Prefill for JSON: Forcing Structured Output Without tool_choice

The most common use is anchoring JSON. Starting the assistant turn with {" commits Claude to continuing inside a JSON object; [{" commits it to a JSON array of objects:

response = client.messages.create(
    model="claude-haiku-4-5",
    max_tokens=512,
    messages=[
        {
            "role": "user",
            "content": "Extract the name and email from: 'Contact Alice at alice@example.com'"
        },
        {
            "role": "assistant",
            "content": '{"name": "'  # Forces Claude into the first key-value pair
        }
    ]
)

# Claude continues: Alice", "email": "alice@example.com"}
# Reconstructed: {"name": "Alice", "email": "alice@example.com"}
full_output = '{"name": "' + response.content[0].text

Compare this with tool_choice: forcing a specific tool requires Claude to emit a tool_use block, which you parse and loop back on. Prefill skips the tool mechanism entirely — you get structured text directly in the response, with no extra round-trip. For lightweight extraction that doesn't need tool semantics, prefill is lower overhead.

That said, output_config.format with a json_schema is now the recommended route for guaranteed JSON on current production models, because it handles cases where prefill is either unavailable or could produce malformed output.

When Should You Use Prefill vs. Prompt Instructions vs. tool_choice?

  • Prefill: when you need to mechanically anchor the first few characters of output (start of a JSON object, an XML tag, a specific phrase) and the model supports it. Best for stateless extraction on older or Haiku-tier models.
  • Prompt instructions: when the format rule is complex — specific field ordering, conditional structure, constrained prose — and a one-character anchor won't cover it. More flexible, relies on instruction-following, works on all models.
  • tool_choice: when you need schema validation, strict typing, or want the output routed through a tool-call loop for downstream processing.
  • output_config.format: the first choice for guaranteed JSON schema conformance on current Opus and Sonnet models, where prefill is not available.

What Are the Limits and Risks of the Prefill Technique?

The most significant limit is model support. Per published Anthropic documentation, last-assistant-turn prefills return a 400 error on:

  • Claude Opus 4.6, Opus 4.7, Opus 4.8
  • Claude Sonnet 4.6

The technique is available on Claude Haiku 4.5 and legacy models (Opus 4.5, Sonnet 4.5, and the Claude 3.x series). One important nuance: placing an assistant message earlier in the conversation — for few-shot examples — remains valid on all models. The 400 restriction applies only to the final, open-ended prefill at the end of the messages array. Always verify the current restrictions in Anthropic's migration documentation before deploying.

Beyond model compatibility, watch for:

  • Truncation at max_tokens. If Claude fills the token budget before closing a JSON structure, you get a truncated object. Parse defensively and set a generous max_tokens.
  • Missing the prefill in response handling. Because response.content[0].text starts after the prefill, code that reads only that field silently loses the opening characters.
  • Malformed JSON. Prefill anchors the opening but doesn't validate the close. Always run a JSON parser on the full concatenated string, not on the response text alone.

For models where prefill is unavailable, Anthropic's migration paths are: output_config.format for JSON/schema output; system prompt instructions for suppressing preambles; tool_choice with an enum field for classification tasks.

Does Prefilling Interact with Prompt Caching?

Claude renders the prompt in the order tools → system → messages. Because the prefill lives at the end of messages, it is the last content in the rendered sequence.

Prompt caching is a prefix match: any byte change at position N invalidates everything after N. Adding a stable prefill — the same text on every request — does not break caching for earlier content. The tools, system prompt, and prior conversation turns are all earlier in the render order and remain cacheable.

If the prefill changes per request — different partial JSON keys for different extractions — that change only invalidates the messages cache tier at the point of the prefill. It does not invalidate a cached system prompt, because the system prompt sits earlier in the render order.

One edge case worth knowing: each cache_control breakpoint can look back at most 20 content blocks to find a prior cache entry. In agentic loops with many tool_use/tool_result pairs, a prefill appended at the very end may sit outside this window. In typical request patterns, this is not a concern.

CCA-F Exam: What You Need to Know About Prefilling

The Claude Certified Architect — Foundations exam covers output control mechanisms across the Claude API. Exam domain weights and passing criteria may change between cohorts; treat the following as a study guide and verify against official Anthropic materials.

Key points that may be tested:

  • Prefill is implemented by appending {"role": "assistant", "content": "..."} as the last entry in messages — there is no separate API parameter for it.
  • The response text begins after the prefill; you must concatenate to reconstruct the full output.
  • On Opus 4.6, Opus 4.7, Opus 4.8, and Sonnet 4.6, prefill returns a 400 error. Know the alternatives: output_config.format for JSON, system prompt instructions for format guidance, tool_choice for schema-validated structured output.
  • The prompt render order is tools → system → messages. A change to the prefill only invalidates the messages cache tier — not the tools or system tiers.
  • Assistant messages placed earlier in the conversation for few-shot purposes are unaffected by the 400 restriction — only the final open-ended prefill is restricted on newer models.

This post explains how the prefill technique works and where it fits among the API's output-control options. If you are preparing for the Claude Certified Architect — Foundations exam, the real test is applying those distinctions under exam conditions: recognizing when a question calls for prefill versus output_config.format versus tool_choice, and knowing why one fails on a given model. Plinth Prep is an independent study resource (not affiliated with Anthropic) whose practice questions on output-control mechanisms are designed to close exactly that gap. Visit plinthprep.com to try the exam-prep questions.

Frequently asked questions

What is Claude prefill in the API?
Claude prefill places text in the <code>assistant</code> role at the end of your <code>messages</code> array so Claude continues the response from that exact starting point. Opening with <code>{“</code> anchors JSON output; opening with a sentence fragment shapes tone. The technique works without relying on instruction-following alone.
Which Claude models support the assistant-turn prefill technique?
Per published Anthropic materials, prefill returns a 400 error on Claude Opus 4.6, Opus 4.7, Opus 4.8, and Sonnet 4.6. The technique remains available on Claude Haiku 4.5 and legacy models such as Opus 4.5 and Sonnet 4.5. Verify current restrictions in Anthropic’s migration documentation before deploying.
How does Claude prefill differ from system prompt instructions for controlling output format?
System prompt instructions ask Claude to follow a format and rely on instruction-following; prefill physically starts the response in that format. Prefill is more reliable for simple anchoring — starting JSON with <code>{“</code> — but does not work on Opus 4.6 and newer Sonnet models, where <code>output_config.format</code> is the recommended alternative.
Does Claude prefill interact with prompt caching?
Yes. The prefill lives at the end of the <code>messages</code> array, the last tier in Claude’s render order (tools → system → messages). A stable prefill — the same text every request — does not invalidate cached system prompts or tools. Changing the prefill only affects the cache at that position and after.
What should I use instead of prefill on Opus 4.6 and newer Claude models?
On Opus 4.6, Opus 4.7, Opus 4.8, and Sonnet 4.6, prefill returns a 400 error. Use <code>output_config.format</code> with a <code>json_schema</code> for guaranteed JSON output; use system prompt instructions to suppress preambles; use <code>tool_choice</code> with an enum field for classification. These alternatives work across all current models.

Share this post

Plinth Prep is an independent study resource and is not affiliated with, endorsed by, or sponsored by Anthropic. Practice material is written by Plinth Prep and does not reproduce real exam content.