> ## Documentation Index
> Fetch the complete documentation index at: https://praison.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# OpenAI-Compatible Endpoints

> Point PraisonAI at any /v1 host with base_url + api_key — no provider prefix needed

Point PraisonAI at any OpenAI-compatible `/v1` host by setting `base_url` and `api_key` on the `Agent` — bare catalog model ids are fine, no `provider/` prefix required.

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
    subgraph "OpenAI-Compatible Routing"
        A[📝 Agent<br/>llm='deepseek-v4-flash'<br/>base_url='https://api.pzero.studio/v1'] --> R[🔌 Auto-prefix<br/>openai/deepseek-v4-flash]
        R --> H[🌐 /v1/chat/completions<br/>on your host]
        H --> O[✅ Response]
    end

    classDef input fill:#6366F1,stroke:#7C90A0,color:#fff
    classDef process fill:#F59E0B,stroke:#7C90A0,color:#fff
    classDef host fill:#189AB4,stroke:#7C90A0,color:#fff
    classDef output fill:#10B981,stroke:#7C90A0,color:#fff

    class A input
    class R process
    class H host
    class O output
```

## Quick Start

<Steps>
  <Step title="Simplest form">
    Pass `base_url` and `api_key` at the top level with a bare model id.

    ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    from praisonaiagents import Agent

    agent = Agent(
        name="assistant",
        instructions="You are a helpful assistant",
        llm="deepseek-v4-flash",
        base_url="https://api.pzero.studio/v1",
        api_key="your-key-or-empty-if-public",
    )
    agent.start("Explain what an OpenAI-compatible endpoint is in one paragraph.")
    ```
  </Step>

  <Step title="Environment-variable variant">
    Set the host once with environment variables, then keep the code clean.

    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    export OPENAI_API_BASE=https://api.pzero.studio/v1
    export OPENAI_API_KEY=your-key
    ```

    ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    from praisonaiagents import Agent

    agent = Agent(
        name="assistant",
        instructions="You are a helpful assistant",
        llm="deepseek-v4-flash",
    )
    agent.start("Hi")
    ```
  </Step>

  <Step title="Dict form (equivalent)">
    The dict form does the same thing when you prefer to bundle connection settings inside `llm`.

    ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    from praisonaiagents import Agent

    agent = Agent(
        name="assistant",
        instructions="You are a helpful assistant",
        llm={
            "model": "deepseek-v4-flash",
            "api_base": "https://api.pzero.studio/v1",
            "api_key": "",
        },
    )
    agent.start("Hello")
    ```
  </Step>
</Steps>

***

## How It Works

PraisonAI routes a bare model id plus a `base_url` through the OpenAI-compatible client.

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
sequenceDiagram
    participant User
    participant Agent
    participant Router as PraisonAI LLM
    participant Host as Your /v1 host

    User->>Agent: agent.start("...")
    Agent->>Router: model='deepseek-v4-flash', base_url set
    Note over Router: Bare model + base_url →<br/>route as openai/deepseek-v4-flash
    Router->>Host: POST /v1/chat/completions
    Host-->>Router: choices[0].message
    Router-->>Agent: text
    Agent-->>User: response
```

| Situation                                                   | What happens                               |
| ----------------------------------------------------------- | ------------------------------------------ |
| Bare model + `base_url` set                                 | Routed as `openai/<model>` to `<base_url>` |
| Prefixed model (e.g. `anthropic/…`, `ollama/…`, `openai/…`) | Passed through unchanged                   |
| Bare model with no `base_url` and no `OPENAI_API_BASE`      | Uses OpenAI default (`api.openai.com/v1`)  |

***

## Configuration Options

Set these top-level `Agent` parameters for any OpenAI-compatible host.

| Option     | Type            | Default  | Description                                                                               |
| ---------- | --------------- | -------- | ----------------------------------------------------------------------------------------- |
| `llm`      | `str` \| `dict` | required | Catalog model id (e.g. `"deepseek-v4-flash"`) or a full dict `{model, api_base, api_key}` |
| `base_url` | `str`           | `None`   | OpenAI-compatible `/v1` root, e.g. `https://api.pzero.studio/v1`                          |
| `api_key`  | `str`           | `None`   | API key for the host (may be empty for public catalogs)                                   |

<Card title="Agent SDK Reference" icon="code" href="/docs/api/praisonaiagents/agent/agent">
  Full parameter surface for the Agent class.
</Card>

***

## Common Patterns

Every host uses the same 5-line pattern — only `base_url` and the catalog id change.

<Tabs>
  <Tab title="P0 / pzero.studio">
    ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    from praisonaiagents import Agent

    agent = Agent(
        name="assistant",
        llm="deepseek-v4-flash",
        base_url="https://api.pzero.studio/v1",
        api_key="",
    )
    agent.start("Hello")
    ```
  </Tab>

  <Tab title="DeepInfra">
    ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    from praisonaiagents import Agent

    agent = Agent(
        name="assistant",
        llm="meta-llama/Meta-Llama-3-8B-Instruct",
        base_url="https://api.deepinfra.com/v1/openai",
        api_key="your-deepinfra-key",
    )
    agent.start("Hello")
    ```
  </Tab>

  <Tab title="Fireworks">
    ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    from praisonaiagents import Agent

    agent = Agent(
        name="assistant",
        llm="accounts/fireworks/models/llama-v3-8b-instruct",
        base_url="https://api.fireworks.ai/inference/v1",
        api_key="your-fireworks-key",
    )
    agent.start("Hello")
    ```
  </Tab>

  <Tab title="Together AI">
    ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    from praisonaiagents import Agent

    agent = Agent(
        name="assistant",
        llm="meta-llama/Llama-3-8b-chat-hf",
        base_url="https://api.together.xyz/v1",
        api_key="your-together-key",
    )
    agent.start("Hello")
    ```
  </Tab>

  <Tab title="vLLM">
    ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    from praisonaiagents import Agent

    agent = Agent(
        name="assistant",
        llm="meta-llama/Meta-Llama-3-8B-Instruct",
        base_url="http://localhost:8000/v1",
        api_key="not-needed",
    )
    agent.start("Hello")
    ```
  </Tab>

  <Tab title="LM Studio">
    ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    from praisonaiagents import Agent

    agent = Agent(
        name="assistant",
        llm="local-model",
        base_url="http://localhost:1234/v1",
        api_key="not-needed",
    )
    agent.start("Hello")
    ```
  </Tab>

  <Tab title="Company gateway">
    ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    from praisonaiagents import Agent

    agent = Agent(
        name="assistant",
        llm="your-catalog-id",
        base_url="https://gateway.company.internal/v1",
        api_key="your-key",
    )
    agent.start("Hello")
    ```
  </Tab>
</Tabs>

***

## Choosing Which Style to Use

Pick the routing style that matches what you connect to.

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph TB
    Q{What are you connecting to?} -->|Named provider<br/>OpenAI, Anthropic, Gemini| Named[Use provider prefix<br/>e.g. anthropic/claude-sonnet-4-5]
    Q -->|Any OpenAI-compatible /v1 host| Compat[Use base_url + bare model]
    Q -->|Self-hosted LiteLLM Proxy<br/>as a gateway| Proxy[Use litellm-proxy/model<br/>with LITELLM_PROXY_* env]
    Q -->|Custom Python provider class| Reg[Register in Custom Provider Registry]

    classDef q fill:#6366F1,stroke:#7C90A0,color:#fff
    classDef opt fill:#189AB4,stroke:#7C90A0,color:#fff

    class Q q
    class Named,Compat,Proxy,Reg opt
```

***

## Best Practices

<AccordionGroup>
  <Accordion title="Use base_url at the top level for one-off hosts">
    The top-level `base_url` is cleaner than the dict form for single-agent scripts. Reach for the dict form only when you want connection settings bundled inside `llm`.
  </Accordion>

  <Accordion title="Use env vars when the host is fixed">
    Set `OPENAI_API_BASE` and `OPENAI_API_KEY` when the host stays the same across runs. This keeps code portable across environments.
  </Accordion>

  <Accordion title="Keep embeddings on their own provider">
    Most OpenAI-compatible chat hosts don't serve embeddings. Configure embeddings separately — see the [Embeddings](/docs/capabilities/embeddings) docs.
  </Accordion>

  <Accordion title="Don't add openai/ yourself">
    PraisonAI adds the `openai/` prefix internally when `base_url` is set. Adding it manually is harmless but unnecessary.
  </Accordion>

  <Accordion title="Don't mix base_url with Anthropic, Gemini, or Ollama models">
    Those keep their native adapters. Use `base_url` only for OpenAI-compatible Chat Completions hosts.
  </Accordion>
</AccordionGroup>

***

## Related

<CardGroup cols={2}>
  <Card title="OpenAI" icon="robot" href="/docs/models/openai">
    First-party OpenAI models.
  </Card>

  <Card title="LiteLLM Proxy" icon="server" href="/docs/models/litellm-proxy">
    Route through a self-hosted LiteLLM proxy gateway.
  </Card>

  <Card title="Ollama" icon="microchip" href="/docs/models/ollama">
    Local Ollama models.
  </Card>

  <Card title="Custom Provider" icon="wrench" href="/docs/models/custom-provider">
    Register a fully custom Python provider.
  </Card>
</CardGroup>