generate_text

Generate text synchronously with a single call - returns a GenerateTextResult with rich metadata.

Overview

generate_text is a high-level helper for synchronous text generation that returns a GenerateTextResult with rich metadata including usage statistics, finish reasons, and tool calls.

Basic usage

generate_text.py

from ai_sdk import generate_text, openai

model = openai("gpt-4.1-mini")
res = generate_text(model=model, prompt="Say hi to the world in one sentence")
print(res.text) # "Hello, world – great to see you!"
print(res.usage) # TokenUsage(prompt_tokens=4, completion_tokens=9, ...)

Parameters

Name	Type	Required	Description
model	LanguageModel	✓	Provider instance created via e.g. openai() or anthropic()
prompt	str	one of prompt/messages	User prompt (plain string).
system	str	–	System instruction prepended to the conversation.
messages	List[AnyMessage]	–	Fine-grained message array providing full control over roles & multimodal parts. Overrides prompt.
tools	List[Tool]	–	Enable iterative tool-calling (see further below).
max_steps	int	8	Safeguard to abort endless tool loops.
on_step	Callable[[OnStepFinishResult], None]	–	Callback executed after every model ↔ tool round-trip.
**kwargs	provider-specific	–	Forwarded verbatim to the underlying SDK – e.g. temperature=0.2.

Return value

GenerateTextResult exposes rich metadata:

print(res.finish_reason)   # "stop", "length", "tool" …
print(res.tool_calls)      # populated when tool-calling is active
print(res.provider_metadata)

Examples

Basic text generation

from ai_sdk import generate_text, openai

model = openai("gpt-4.1-mini")
res = generate_text(
    model=model,
    prompt="Write a haiku about programming"
)
print(res.text)

With system instruction

from ai_sdk import generate_text, openai

model = openai("gpt-4.1-mini")
res = generate_text(
    model=model,
    system="You are a helpful coding assistant. Always provide clear, concise explanations.",
    prompt="Explain what recursion is in simple terms"
)
print(res.text)

With custom parameters

from ai_sdk import generate_text, openai

model = openai("gpt-4.1-mini")
res = generate_text(
    model=model,
    prompt="Write a creative story",
    temperature=0.8,
    max_tokens=500
)
print(res.text)

Tool-calling

See the dedicated Tool page for a complete walkthrough.

from ai_sdk import tool, generate_text, openai

add = tool(
    name="add",
    description="Add two integers.",
    parameters={
        "type": "object",
        "properties": {"a": {"type": "integer"}, "b": {"type": "integer"}},
        "required": ["a", "b"],
    },
    execute=lambda a, b: a + b,
)

model = openai("gpt-4.1-mini")
res = generate_text(
    model=model,
    prompt="What is 21 + 21?",
    tools=[add],
)
print(res.text)  # "The result is 42."

---

generate_text is provider-agnostic. Swap openai() for anthropic() or any other future implementation – no code changes required.