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

# Connect a Custom OpenAI-Compatible Endpoint

> Connect Elephas to any OpenAI-compatible API with a custom base URL, model name and key. Setup steps, the connection test, and the mistakes that break it.

If your AI service isn't in Elephas's provider list but offers an OpenAI-compatible chat API, connect it as a custom endpoint. You type the base URL, the model name and your API key, then run a connection test. This is meant for technical users. If your provider is listed, [use your own API key](/docs/ai-options/use-your-own-api-key) instead.

<Info>
  Custom endpoints are part of the own API key option. They work with an Elephas trial or a Personal or Professional plan, in your Personal workspace, and not in Team workspaces.
</Info>

## Before you start

You need three things from your provider:

* **The base URL**, the address up to and including `/v1`, for example `https://api.example.com/v1`.
* **The exact model name** your provider uses.
* **An API key** for that service.

The model must support tool calling (function calling) over the OpenAI chat completions API. Elephas uses it to search and read your documents step by step.

## Steps

<Steps>
  <Step title="Open the custom endpoint settings">
    Open **Settings › AI** (⌘, on Mac, Ctrl+, on Windows). Under **How Elephas answers**, click **My own AI account**, then **Connect another provider…**, and choose **Custom endpoint…** at the bottom of the list.
  </Step>

  <Step title="Enter the base URL and model">
    In **Base URL**, type the address up to `/v1`. Elephas adds `/chat/completions` itself, and removes it if you paste it. In **Model**, type the model name exactly as your provider writes it. Click **Save Endpoint**.
  </Step>

  <Step title="Save your key">
    Paste the key into **API Key** and click **Save Key**. Settings then shows **An API key is saved in your system keychain.** Click **Done**.
  </Step>

  <Step title="Test the connection">
    Click **Test Connection**. Elephas sends a short test that checks the model can call tools. It never includes your documents. When it passes, Settings says **Agent tools verified for this endpoint and model.** and gives a date by which Elephas will ask you to test again.
  </Step>

  <Step title="Ask a question">
    Ask works through your endpoint once the test has passed.
  </Step>
</Steps>

The steps are the same on Mac and Windows.

## How it works

* **Your request goes straight to the address you typed.** Elephas's servers are not involved. Your key is kept in Keychain on Mac or Credential Manager on Windows, and never synced.
* **Personal information protection still applies.** With **Protect personal information when using cloud AI** on, Elephas hides many common personal details before sending. See [Personal information protection](/docs/privacy-and-security/personal-information-protection) and [What data is sent to AI](/docs/privacy-and-security/what-data-is-sent-to-ai).
* **Leaving both fields empty uses OpenRouter.** With no base URL and no model, Elephas uses OpenRouter's address and a default model. For any other address, the model name is required.
* **No model list.** Elephas doesn't fetch models for a custom endpoint. You type the name.
* **The test expires.** A passed test is valid for a limited time. When it is due, Ask asks you to test again.
* **Your plan still matters.** Like any own key, a custom endpoint needs an Elephas trial or plan, checked online with a device ID only.

### Common pitfalls

| Problem | Fix |
| - | - |
| The base URL ends in `/chat/completions` | Elephas removes it, but check that what is left ends in `/v1` or your provider's equivalent. |
| The base URL is missing `/v1` | Most OpenAI-compatible APIs expect it. Use the address from your provider's documentation. |
| The model name has a typo or the wrong prefix | Copy it from your provider. Some use `vendor/model` names, for example on OpenRouter. |
| **This endpoint or model did not complete a tool call. Agentic Ask needs a model with tool calling.** | Choose a model that supports tool calling, or check that your provider enables it. |
| **Save an API key and a model before testing the connection.** | Fill in the model and save a key first. A key is required even if your service doesn't check it. |

## Troubleshooting

<AccordionGroup>
  <Accordion title="The connection test could not finish">
    The message shows a code in brackets. Check the key and the base URL, then click **Test Connection** again. If your provider limits requests or is out of credit, Elephas says so. See [API key errors](/docs/troubleshooting/api-key-errors).
  </Accordion>

  <Accordion title="Ask says Agent tools are not verified for this endpoint and model yet">
    You changed the endpoint or model, or the last test expired. Run **Test Connection** again.
  </Accordion>

  <Accordion title="Ask says Elephas could not reach the AI provider">
    The address can't be reached from your computer. Check the base URL, your network and any VPN your provider requires.
  </Accordion>
</AccordionGroup>

## Related articles

<CardGroup cols={2}>
  <Card title="Use your own API key" href="/docs/ai-options/use-your-own-api-key" />

  <Card title="API key errors" href="/docs/troubleshooting/api-key-errors" />

  <Card title="Choose how Elephas answers" href="/docs/ai-options/choose-how-elephas-answers" />

  <Card title="Run Local AI" href="/docs/ai-options/run-local-ai" />
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.