Rendering prompts

client.prompts.render(slug, **options) resolves a prompt for the client’s project_id and env in a single request. Set format — on the client or per call — to get a result shaped for that provider; omit it to get the neutral result. It is the primary runtime method.

client = create_client(env="production", format="openai")

prompt = client.prompts.render("welcome-message", variables={"name": "Ada"})

The keyword options are format, label, subject, variables, fallback, and on_unknown_role: label picks the label to resolve for this call (defaulting to the client’s env — env is a label value), format overrides the client default, subject (a stable id) pins a weighted release to a variant, and fallback is served on a transient network or 5xx failure. The return shape is fixed by the call’s format, not by the network outcome. Authored developer blocks render as-is; the SDK maps them per provider (OpenAI keeps developer, Anthropic folds them into system). on_unknown_role ("drop" default, "warn", or "error") sets how a message with an unrecognized role is handled during provider conversion — see Unknown roles.

Shaped result

With a format, render returns a dict you can spread straight into a provider request. format="openai" returns {"messages", "config", "metadata"}; format="anthropic" returns {"system", "messages", "config", "metadata"} — the authored system and developer instructions are folded into a top-level system string, which Anthropic takes as a separate request field. When the prompt authors tools, the result also carries provider-shaped tools and tool_choice.

Key	Holds
`system`	Anthropic only. The folded system/developer instruction text, passed as Anthropic’s top-level `system`. Omit it and you drop the authored instructions.
`messages`	The rendered messages, shaped for the provider.
`config`	Model parameters from the resolved version — `model`, `temperature`, `max_tokens`, and any other stored keys — passed through verbatim, so the dict spreads straight into `create()`.
`tools` / `tool_choice`	Provider-shaped tool definitions and directive, present only when the prompt authors tools. Spread them into the request so a tool-using prompt isn’t sent without its tools.
`metadata`	Provenance: `prompt_id`, `version`, `version_id`, `release_id`, `label` (the single label the prompt resolved through), `slug`, and `variant_name` when a weighted release served a variant.

Spread the result into the request, and pass the whole result to turn().headers(prompt) for the provenance headers:

# OpenAI — tools/tool_choice are present only when the prompt authors tools
res = openai.chat.completions.create(
    **prompt["config"],
    messages=prompt["messages"],
    **({"tools": prompt["tools"]} if "tools" in prompt else {}),
    **({"tool_choice": prompt["tool_choice"]} if "tool_choice" in prompt else {}),
    extra_headers=client.turn().headers(prompt),
)

# Anthropic — pass the folded system alongside the messages
res = anthropic.messages.create(
    **prompt["config"],
    system=prompt["system"],
    messages=prompt["messages"],
    extra_headers=client.turn().headers(prompt),
)

Neutral result and converters

Omit format (on both the client and the call) to get the neutral RenderedPrompt dataclass: messages, tools, tool_choice, prompt_id, version, version_id, release_id, variant_name, content_hash, label, slug, and block_render_record. The version’s model config is exposed as model_config_ — the trailing underscore avoids Pydantic’s reserved model_config attribute. This is the path for a provider the shaper does not cover (Vercel AI, LangChain) or for driving one prompt through more than one provider. The to11ai_sdk.gateway module converts a neutral result into a provider’s request shape:

Helper	Purpose
`to_openai_messages` / `to_anthropic_messages`	Convert the neutral `messages` to the provider’s message list. Both accept an `on_unknown_role` argument — see Unknown roles.
`to_anthropic_system`	Fold the `system`/`developer` turns into Anthropic’s top-level `system` string (they are omitted from `to_anthropic_messages`). Pair the two for an Anthropic call.
`to_openai_tools` / `to_anthropic_tools`	Convert `tools` to the provider’s tool schema.
`to_openai_tool_choice` / `to_anthropic_tool_choice`	Convert `tool_choice` to the provider’s directive.
`gateway_auth_headers`	The `x-to11-*` headers that authenticate a gateway call.
`gateway_prompt_headers`	Prompt provenance headers for a rendered prompt.

gateway_auth_headers and gateway_prompt_headers are also importable from the main to11ai_sdk entry. With a format, render applies the message conversion for you, so most apps never call the converters directly.

from to11ai_sdk.gateway import to_openai_messages, to_openai_tools

rendered = client.prompts.render("weather-concierge", variables={"city": "NYC"})
res = openai.chat.completions.create(
    model="gpt-4o",
    messages=to_openai_messages(rendered.messages),
    tools=to_openai_tools(rendered.tools) if rendered.tools else None,
    extra_headers=client.turn().headers(rendered),
)

Unknown roles

The message converters recognize system, user, assistant, developer, and tool. A message whose role is anything else is handled by the on_unknown_role policy — set it per call, on create_client, or on the converter directly:

Mode	Behavior
`"drop"` (default)	The message is omitted silently.
`"warn"`	The message is omitted and a warning on the `to11ai_sdk` logger names the role and index.
`"error"`	Conversion raises `UnknownRoleError` (carrying `code="unknown_role"`, `role`, and `index`).

# Fail loudly when a hand-built message array has an unrecognized role
messages = to_openai_messages(history, on_unknown_role="error")

A prompt rendered by to11 only ever carries known roles, so on render() this matters mainly when you convert your own message arrays (assembled conversation history, messages from another source). on_unknown_role="error" on render() is a way to assert that invariant explicitly.

SDKs

Gateway

Rendering prompts

Shaped result

Neutral result and converters

Unknown roles

​Shaped result

​Neutral result and converters

​Unknown roles

Shaped result

Neutral result and converters

Unknown roles