> ## Documentation Index
> Fetch the complete documentation index at: https://thethirdpenco-feat-tool-lifecycle-events.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Generating Text

> Generate text completions from AI models

The `generate_text` function is the primary way to generate text using ai-query. It supports simple prompts, multi-turn conversations, tool calling, and automatic execution loops.

## Basic Usage

```python theme={null}
import asyncio
from ai_query import generate_text
from ai_query.providers import openai

async def main():
    result = await generate_text(
        model=openai("gpt-4o"),
        prompt="What is the capital of France?"
    )
    print(result.text)  # "The capital of France is Paris."

asyncio.run(main())
```

## Parameters

| Parameter          | Type                                                | Description                                                                           |
| ------------------ | --------------------------------------------------- | ------------------------------------------------------------------------------------- |
| `model`            | `LanguageModel`                                     | The AI model to use (from `openai()`, `anthropic()`, or `google()`)                   |
| `prompt`           | `str`                                               | The user prompt (simple string)                                                       |
| `messages`         | [`list[Message]`](/reference/types/message)         | Full conversation history (alternative to `prompt`)                                   |
| `system`           | `str`                                               | System prompt to set context                                                          |
| `tools`            | [`dict[str, Tool]`](/reference/types/tool)          | Tools the AI can call                                                                 |
| `stop_when`        | [`StopCondition`](/reference/types/stop-conditions) | Stop condition for tool loops (e.g., `step_count_is(5)` or `has_tool_call("finish")`) |
| `on_step_start`    | `Callable`                                          | Callback when a step starts                                                           |
| `on_step_finish`   | `Callable`                                          | Callback when a step finishes                                                         |
| `reasoning`        | `ReasoningConfig`                                   | Normalized reasoning-depth controls like `effort` and `budget`                        |
| `provider_options` | `dict`                                              | Provider-specific options                                                             |

## Using Messages

For multi-turn conversations, use the `messages` parameter:

```python theme={null}
from ai_query import generate_text
from ai_query.providers import anthropic

result = await generate_text(
    model=anthropic("claude-sonnet-4-20250514"),
    messages=[
        {"role": "user", "content": "My name is Alice."},
        {"role": "assistant", "content": "Hello Alice! Nice to meet you."},
        {"role": "user", "content": "What's my name?"},
    ]
)
print(result.text)  # "Your name is Alice."
```

## System Prompts

Set the AI's behavior with a system prompt:

```python theme={null}
result = await generate_text(
    model=openai("gpt-4o"),
    system="You are a helpful pirate. Always respond in pirate speak.",
    prompt="How do I write a Python function?"
)
```

## Response Object

The `generate_text` function returns a [`GenerateTextResult`](/reference/types/results):

```python theme={null}
result = await generate_text(
    model=openai("gpt-4o"),
    prompt="Hello!"
)

# The generated text
print(result.text)

# Token usage
print(result.usage.prompt_tokens)
print(result.usage.completion_tokens)
print(result.usage.total_tokens)

# Tool calls made (if any)
print(result.tool_calls)

# Results from tool execution (if any)
print(result.tool_results)

# All steps in multi-turn execution
print(result.steps)
```

## Provider Options

Pass provider-specific options:

```python theme={null}
result = await generate_text(
    model=openai("gpt-4o"),
    prompt="Write a creative story.",
    provider_options={
        "openai": {
            "temperature": 0.9,
            "max_tokens": 500
        }
    }
)
```

## Reasoning

Use the top-level `reasoning` parameter for normalized reasoning-depth controls:

```python theme={null}
result = await generate_text(
    model=openai("gpt-5.4"),
    prompt="Solve this carefully.",
    reasoning={"effort": "high"},
    max_tokens=500,
)
```

Current first-pass support:

* OpenAI and OpenAI-compatible providers: `effort`
* Google: `budget`
* Anthropic: model-aware `effort` and `budget`

If you need provider-specific thinking visibility or raw provider configuration, continue using `provider_options`.

If you want provider thinking output during streaming, see [`Thinking`](/core/thinking). `generate_text()` controls reasoning depth, but thinking output itself is exposed through `stream_text(..., on_reasoning_event=...)`.

## Error Handling

```python theme={null}
try:
    result = await generate_text(
        model=openai("gpt-4o"),
        prompt="Hello!"
    )
except Exception as e:
    print(f"Error: {e}")
```

## Next Steps

<CardGroup cols={2}>
  <Card title="Streaming" icon="bolt" href="/core/streaming">
    Stream responses in real-time
  </Card>

  <Card title="Tools" icon="wrench" href="/core/tools">
    Add tool calling capabilities
  </Card>
</CardGroup>