> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/BerriAI/litellm/llms.txt
> Use this file to discover all available pages before exploring further.

# completion()

> Complete API reference for the completion() function

## Overview

Perform chat completions using any of LiteLLM's 100+ supported LLM providers. Returns responses in OpenAI format.

## Function Signature

```python theme={null}
def completion(
    model: str,
    messages: List = [],
    # Optional OpenAI params
    timeout: Optional[Union[float, str, httpx.Timeout]] = None,
    temperature: Optional[float] = None,
    top_p: Optional[float] = None,
    n: Optional[int] = None,
    stream: Optional[bool] = None,
    stream_options: Optional[dict] = None,
    stop = None,
    max_completion_tokens: Optional[int] = None,
    max_tokens: Optional[int] = None,
    modalities: Optional[List[ChatCompletionModality]] = None,
    prediction: Optional[ChatCompletionPredictionContentParam] = None,
    audio: Optional[ChatCompletionAudioParam] = None,
    presence_penalty: Optional[float] = None,
    frequency_penalty: Optional[float] = None,
    logit_bias: Optional[dict] = None,
    user: Optional[str] = None,
    # OpenAI v1.0+ params
    reasoning_effort: Optional[Literal["none", "minimal", "low", "medium", "high", "xhigh", "default"]] = None,
    verbosity: Optional[Literal["low", "medium", "high"]] = None,
    response_format: Optional[Union[dict, Type[BaseModel]]] = None,
    seed: Optional[int] = None,
    tools: Optional[List] = None,
    tool_choice: Optional[Union[str, dict]] = None,
    logprobs: Optional[bool] = None,
    top_logprobs: Optional[int] = None,
    parallel_tool_calls: Optional[bool] = None,
    web_search_options: Optional[OpenAIWebSearchOptions] = None,
    deployment_id = None,
    extra_headers: Optional[dict] = None,
    safety_identifier: Optional[str] = None,
    service_tier: Optional[str] = None,
    # Deprecated params
    functions: Optional[List] = None,
    function_call: Optional[str] = None,
    # API configuration
    base_url: Optional[str] = None,
    api_version: Optional[str] = None,
    api_key: Optional[str] = None,
    model_list: Optional[list] = None,
    # LiteLLM specific
    thinking: Optional[AnthropicThinkingParam] = None,
    **kwargs
) -> Union[ModelResponse, CustomStreamWrapper]
```

## Parameters

### Required Parameters

<ParamField path="model" type="string" required>
  The model to use for completion. See [supported models](https://docs.litellm.ai/docs/providers/) for the full list.

  Examples: `gpt-4`, `claude-3-5-sonnet-20241022`, `gemini-pro`, `bedrock/anthropic.claude-v2`
</ParamField>

<ParamField path="messages" type="List[dict]" required>
  List of message objects representing the conversation context.

  Each message should have:

  * `role`: "system", "user", "assistant", or "tool"
  * `content`: The message content (string or array for multimodal)

  ```python theme={null}
  messages = [
      {"role": "system", "content": "You are a helpful assistant."},
      {"role": "user", "content": "What is 2+2?"}
  ]
  ```
</ParamField>

### Generation Parameters

<ParamField path="temperature" type="float" default="1.0">
  Controls randomness in the output. Higher values (e.g., 1.0) make output more random, lower values (e.g., 0.2) make it more deterministic.

  Range: 0.0 to 2.0
</ParamField>

<ParamField path="top_p" type="float" default="1.0">
  Nucleus sampling parameter. The model considers tokens with top\_p probability mass.

  Range: 0.0 to 1.0
</ParamField>

<ParamField path="max_tokens" type="int">
  Maximum number of tokens to generate in the completion.
</ParamField>

<ParamField path="max_completion_tokens" type="int">
  Upper bound for the number of tokens that can be generated for a completion, including visible output tokens and reasoning tokens.
</ParamField>

<ParamField path="n" type="int" default="1">
  Number of chat completion choices to generate for each input message.
</ParamField>

<ParamField path="stop" type="Union[str, List[str]]">
  Up to 4 sequences where the API will stop generating further tokens.
</ParamField>

<ParamField path="presence_penalty" type="float" default="0.0">
  Penalizes new tokens based on their existence in the text so far.

  Range: -2.0 to 2.0
</ParamField>

<ParamField path="frequency_penalty" type="float" default="0.0">
  Penalizes new tokens based on their frequency in the text so far.

  Range: -2.0 to 2.0
</ParamField>

<ParamField path="logit_bias" type="dict">
  Modify the probability of specific tokens appearing in the completion.

  Maps token IDs to bias values from -100 to 100.
</ParamField>

### Streaming

<ParamField path="stream" type="bool" default="false">
  If true, returns a streaming response.

  ```python theme={null}
  response = litellm.completion(
      model="gpt-4",
      messages=[{"role": "user", "content": "Count to 10"}],
      stream=True
  )

  for chunk in response:
      print(chunk.choices[0].delta.content or "", end="")
  ```
</ParamField>

<ParamField path="stream_options" type="dict">
  Options for streaming response. Only use when `stream=True`.

  ```python theme={null}
  stream_options={"include_usage": True}
  ```
</ParamField>

### Function Calling & Tools

<ParamField path="tools" type="List[dict]">
  List of tools the model can call. Use OpenAI tool format.

  ```python theme={null}
  tools = [{
      "type": "function",
      "function": {
          "name": "get_weather",
          "description": "Get the current weather",
          "parameters": {
              "type": "object",
              "properties": {
                  "location": {"type": "string"}
              },
              "required": ["location"]
          }
      }
  }]
  ```
</ParamField>

<ParamField path="tool_choice" type="Union[str, dict]">
  Controls which tool is called. Options:

  * `"none"`: Don't call any tool
  * `"auto"`: Let the model decide
  * `{"type": "function", "function": {"name": "tool_name"}}`: Force specific tool
</ParamField>

<ParamField path="parallel_tool_calls" type="bool" default="true">
  Whether to enable parallel function calling.
</ParamField>

### Response Format

<ParamField path="response_format" type="Union[dict, Type[BaseModel]]">
  Specify the format of the response.

  For JSON mode:

  ```python theme={null}
  response_format={"type": "json_object"}
  ```

  For structured outputs with Pydantic:

  ```python theme={null}
  from pydantic import BaseModel

  class Response(BaseModel):
      answer: str
      confidence: float

  response = litellm.completion(
      model="gpt-4",
      messages=[...],
      response_format=Response
  )
  ```
</ParamField>

### Advanced Parameters

<ParamField path="reasoning_effort" type="Literal">
  Control reasoning effort for reasoning models (e.g., o1, o3).

  Options: `"none"`, `"minimal"`, `"low"`, `"medium"`, `"high"`, `"xhigh"`, `"default"`
</ParamField>

<ParamField path="modalities" type="List[str]">
  Output types you want the model to generate.

  Example: `["text", "audio"]`
</ParamField>

<ParamField path="audio" type="dict">
  Parameters for audio output. Required when audio is requested with modalities.
</ParamField>

<ParamField path="prediction" type="dict">
  Configuration for Predicted Output, which can improve response times when large parts of the response are known ahead of time.
</ParamField>

<ParamField path="logprobs" type="bool" default="false">
  Whether to return log probabilities of output tokens.
</ParamField>

<ParamField path="top_logprobs" type="int">
  Number of most likely tokens to return at each position (0-5). Requires `logprobs=True`.
</ParamField>

<ParamField path="seed" type="int">
  Seed for deterministic sampling. Supported by some providers.
</ParamField>

<ParamField path="user" type="string">
  Unique identifier for your end-user, for abuse monitoring.
</ParamField>

### API Configuration

<ParamField path="api_key" type="string">
  API key for the provider. If not provided, uses environment variables.
</ParamField>

<ParamField path="base_url" type="string">
  Base URL for the API endpoint.
</ParamField>

<ParamField path="api_version" type="string">
  API version to use (provider-specific).
</ParamField>

<ParamField path="timeout" type="Union[float, httpx.Timeout]" default="600">
  Request timeout in seconds.
</ParamField>

<ParamField path="extra_headers" type="dict">
  Additional headers to include in the request.
</ParamField>

### LiteLLM Specific

<ParamField path="custom_llm_provider" type="string">
  Override the provider detection. Use for non-standard providers.

  Example: `custom_llm_provider="bedrock"`
</ParamField>

<ParamField path="mock_response" type="string">
  Return a mock response for testing/debugging.
</ParamField>

<ParamField path="max_retries" type="int" default="0">
  Number of retry attempts on failure.
</ParamField>

<ParamField path="fallbacks" type="List[str]">
  List of fallback models to try if the primary fails.

  ```python theme={null}
  fallbacks=["gpt-3.5-turbo", "claude-2"]
  ```
</ParamField>

<ParamField path="metadata" type="dict">
  Additional metadata to tag the completion call.
</ParamField>

<ParamField path="thinking" type="dict">
  Anthropic thinking parameter for extended thinking mode.

  ```python theme={null}
  thinking={
      "type": "enabled",
      "budget_tokens": 1000
  }
  ```
</ParamField>

## Response

### ModelResponse

<ResponseField name="id" type="string">
  Unique identifier for the completion.
</ResponseField>

<ResponseField name="choices" type="List[Choice]">
  List of completion choices.

  <Expandable title="Choice object">
    <ResponseField name="index" type="int">
      Choice index.
    </ResponseField>

    <ResponseField name="message" type="Message">
      The generated message.

      <Expandable title="Message object">
        <ResponseField name="role" type="string">
          Role of the message ("assistant").
        </ResponseField>

        <ResponseField name="content" type="string">
          The message content.
        </ResponseField>

        <ResponseField name="tool_calls" type="List[ToolCall]" optional>
          Tool calls made by the model.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="finish_reason" type="string">
      Reason for completion: "stop", "length", "tool\_calls", "content\_filter"
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="created" type="int">
  Unix timestamp of when the completion was created.
</ResponseField>

<ResponseField name="model" type="string">
  Model used for completion.
</ResponseField>

<ResponseField name="usage" type="Usage">
  Token usage information.

  <Expandable title="Usage object">
    <ResponseField name="prompt_tokens" type="int">
      Number of tokens in the prompt.
    </ResponseField>

    <ResponseField name="completion_tokens" type="int">
      Number of tokens in the completion.
    </ResponseField>

    <ResponseField name="total_tokens" type="int">
      Total tokens used.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="_response_ms" type="float">
  Response time in milliseconds (LiteLLM specific).
</ResponseField>

## Usage Examples

### Basic Completion

```python theme={null}
import litellm

response = litellm.completion(
    model="gpt-4",
    messages=[{"role": "user", "content": "Hello, how are you?"}]
)

print(response.choices[0].message.content)
```

### Streaming

```python theme={null}
import litellm

response = litellm.completion(
    model="gpt-4",
    messages=[{"role": "user", "content": "Write a story"}],
    stream=True
)

for chunk in response:
    if chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="")
```

### Async Completion

```python theme={null}
import litellm
import asyncio

async def main():
    response = await litellm.acompletion(
        model="gpt-4",
        messages=[{"role": "user", "content": "Hello!"}]
    )
    print(response.choices[0].message.content)

asyncio.run(main())
```

### Function Calling

```python theme={null}
import litellm

tools = [{
    "type": "function",
    "function": {
        "name": "get_current_weather",
        "description": "Get the current weather in a location",
        "parameters": {
            "type": "object",
            "properties": {
                "location": {
                    "type": "string",
                    "description": "City and state, e.g. San Francisco, CA"
                },
                "unit": {
                    "type": "string",
                    "enum": ["celsius", "fahrenheit"]
                }
            },
            "required": ["location"]
        }
    }
}]

response = litellm.completion(
    model="gpt-4",
    messages=[{"role": "user", "content": "What's the weather in Boston?"}],
    tools=tools
)

if response.choices[0].message.tool_calls:
    print(response.choices[0].message.tool_calls[0].function.name)
```

### Multiple Providers

```python theme={null}
import litellm

# OpenAI
response = litellm.completion(
    model="gpt-4",
    messages=[{"role": "user", "content": "Hi"}]
)

# Anthropic
response = litellm.completion(
    model="claude-3-5-sonnet-20241022",
    messages=[{"role": "user", "content": "Hi"}]
)

# AWS Bedrock
response = litellm.completion(
    model="bedrock/anthropic.claude-v2",
    messages=[{"role": "user", "content": "Hi"}]
)

# Azure OpenAI
response = litellm.completion(
    model="azure/gpt-4",
    messages=[{"role": "user", "content": "Hi"}],
    api_key="your-azure-key",
    api_base="https://your-endpoint.openai.azure.com/",
    api_version="2024-02-01"
)
```

## Error Handling

```python theme={null}
import litellm
from litellm import AuthenticationError, RateLimitError, Timeout

try:
    response = litellm.completion(
        model="gpt-4",
        messages=[{"role": "user", "content": "Hello"}]
    )
except AuthenticationError as e:
    print(f"Authentication failed: {e}")
except RateLimitError as e:
    print(f"Rate limit exceeded: {e}")
except Timeout as e:
    print(f"Request timed out: {e}")
except Exception as e:
    print(f"An error occurred: {e}")
```

## Related

* [acompletion()](/api/completion) - Async version
* [Router.completion()](/api/router) - Load balanced completions
* [Embedding API](/api/embedding)
* [Supported Providers](https://docs.litellm.ai/docs/providers/)