# Agent Integrations
Source: https://docs.lithosai.com/agent-integrations

Connect popular coding agents to LithosAI.

LithosAI exposes the OpenAI Chat Completions API. Agents that support this protocol
connect directly; Codex and Claude Code use a local compatibility adapter.
Choose your agent below for setup instructions.

| Agent | Client protocol | Integration path |
| - | - | - |
| [Cline](/agent-integrations/cline) | Chat Completions | Direct |
| [DeepSeek Harness](/agent-integrations/deepseek-harness) | Chat Completions | Direct |
| [Hermes Agent](/agent-integrations/hermes-agent) | Chat Completions | Direct |
| [Codex](/agent-integrations/codex) | Responses API | LiteLLM compatibility adapter |
| [Kilo Code](/agent-integrations/kilo-code) | Chat Completions | Direct |
| [Claude Code](/agent-integrations/claude-code) | Anthropic Messages API | LiteLLM compatibility adapter |
| [omp](/agent-integrations/omp) | Chat Completions | Direct |
| [OpenClaw](/agent-integrations/openclaw) | Chat Completions | Direct |
| [OpenCode](/agent-integrations/opencode) | Chat Completions | Direct |
| [OpenHands](/agent-integrations/openhands) | Chat Completions | Direct |
| [Pi](/agent-integrations/pi) | Chat Completions | Direct |
| [VS Code (built-in chat)](/agent-integrations/vscode) | Chat Completions | Direct |

## Choose a model and reasoning effort

Choose the exact model ID from [Models](https://console.lithosai.cloud/models).
Speed tiers have distinct IDs, such as `moonshotai/Kimi-K3-fast` or
`moonshotai/Kimi-K3-ultra`. To use another model, choose its full ID, such as
`deepseek-ai/DeepSeek-V4.1-Flash-fast`. Reasoning effort is a separate setting.

| Agent | Choose a model | Change effort |
| - | - | - |
| OpenCode | `/models` | `/variants` |
| Pi | `/model` | `/settings` |
| Hermes | `/model` | `/reasoning` |
| Kilo CLI | `/models` | `/variants` |
| Cline CLI | `/model` | Start or resume with `--thinking low` or `--thinking high` |
| omp | `/switch` | Shift+Tab |
| OpenClaw local TUI | `/models` | `/think` |
| DeepSeek Harness Web UI and desktop app | Model menu, then **Model** | Model menu, then **Effort** |
| VS Code | Model picker in the Chat view | **Thinking Effort** in the model picker |

Each guide includes the provider configuration and model and effort controls.

## Before you begin

Install the agent you want to use, create a key on the [API Keys](https://console.lithosai.cloud/keys)
page, and confirm the model ID on the [Models](https://console.lithosai.cloud/models) page.
Follow your agent’s guide to save the key in its settings, secret file, or runtime
environment. You can keep using your existing editor, CLI, or Gateway.

<Note>
  LithosAI validates tool schemas strictly. An agent that loads an MCP server whose tool
  parameters are not a JSON Schema object is rejected with `invalid 'parameters' schema`.
  Disable that server or correct its schema.
</Note>

## Common issues

These apply to every agent guide.

### Limitations

* The minimal configuration enables text and tool calls. Turn on image input, reasoning, or
  other capability flags only when the selected LithosAI model supports them.
* Set the context window and maximum output from the selected model’s
  [Models](https://console.lithosai.cloud/models) page. The configuration examples use the
  limits from that page. A lower context window makes the agent compact earlier and reduces
  the cost of each request.
* Reasoning tokens and the final answer share the output budget. Selecting `max` effort
  does not increase that budget. If a response ends with `finish_reason: length`,
  increase the output budget within the model’s limit and allow room for the input.
* Keep your LithosAI API key in the agent's own settings or an environment variable. Do not
  commit it to a project repository.

### Troubleshooting

| Symptom | Cause |
| - | - |
| Authentication fails with `invalid API key` | The LithosAI API key is wrong, expired, or not visible to the process that runs the agent. If the environment variable is unset, some agents send no key at all. |
| ``the model `<id>` does not exist``, or the model is not selectable | The model ID does not exactly match the value on the [Models](https://console.lithosai.cloud/models) page. IDs are case-sensitive. |
| Context usage or compaction is inaccurate | Update the context window and output limit from the Models page. |
| Requests return `404` | The base URL must be `https://api.lithosai.cloud/v1`, unless the agent page says otherwise. |
| Requests return `400` with `invalid 'parameters' schema` | An MCP server provides a tool whose parameters are not valid JSON Schema. Disable that server or fix its schema. |
| Requests return `400` with `unknown_parameter` | The agent sends a request field LithosAI does not accept. Remove the option that adds it; the agent page names known cases. |


# Use LithosAI with Claude Code
Source: https://docs.lithosai.com/agent-integrations/claude-code

Connect Claude Code to LithosAI through a LiteLLM Anthropic Messages compatibility proxy.

## Before you begin

Create a key on the [API Keys](https://console.lithosai.cloud/keys) page, confirm the model ID
on the [Models](https://console.lithosai.cloud/models) page, and export the key in the shell where you start Claude Code or its local proxy.

```bash theme={null}
export LITHOSAI_API_KEY="your-key"
```

Claude Code speaks the Anthropic Messages API, so its proxy needs a different configuration
from the one Codex uses. Run it on a second port to use both agents at once.

<Warning>
  This is a community compatibility path for non-Claude models, not a configuration supported
  by Anthropic. LiteLLM maps common Messages API behavior to Chat Completions, but native
  thinking blocks, prompt caching, token counting, streaming details, and some tool-use flows
  may behave differently.
</Warning>

<Steps>
  <Step title="Install LiteLLM">
    [LiteLLM](https://docs.litellm.ai) bridges the Anthropic Messages API to Chat
    Completions.

    ```bash theme={null}
    pip install 'litellm[proxy]'
    ```

    <Warning>
      Install a current release. LiteLLM 1.82.7 and 1.82.8 were briefly replaced on PyPI in
      March 2026 by a [credential stealer](https://docs.litellm.ai/blog/security-update-march-2026).
    </Warning>
  </Step>

  <Step title="Configure the proxy">
    These model entries are examples, not the full LithosAI catalog. For other models
    or tiers, copy an entry and replace the ID after `hosted_vllm/` with one from
    [Models](https://console.lithosai.cloud/models). Use the corresponding `model_name`
    aliases in the Claude Code environment settings below.

    Give each model the `hosted_vllm/` prefix. It translates `/v1/messages` requests into
    Chat Completions requests for LithosAI.

    <Accordion title="LiteLLM proxy configuration">
      ```yaml claude-code.litellm.yaml theme={null}
      model_list:
        - model_name: kimi-k3-fast
          litellm_params:
            model: hosted_vllm/moonshotai/Kimi-K3-fast
            api_base: https://api.lithosai.cloud/v1
            api_key: os.environ/LITHOSAI_API_KEY
        - model_name: kimi-k3-ultra
          litellm_params:
            model: hosted_vllm/moonshotai/Kimi-K3-ultra
            api_base: https://api.lithosai.cloud/v1
            api_key: os.environ/LITHOSAI_API_KEY

      litellm_settings:
        drop_params: true

      general_settings:
        master_key: sk-claude-proxy
      ```
    </Accordion>

    <Warning>
      Do not reuse the Codex configuration here. An `openai/` entry with
      `use_chat_completions_api` answers `/v1/messages` with `200 OK` and empty content, so
      Claude Code appears to hang rather than reporting an error.
    </Warning>
  </Step>

  <Step title="Start the proxy">
    ```bash theme={null}
    litellm --config claude-code.litellm.yaml --host 127.0.0.1 --port 4001
    ```

    Leave it running, and confirm it is up. The proxy holds your LithosAI key, so keep it
    bound to `127.0.0.1` and do not expose it to a network.

    ```bash theme={null}
    curl http://127.0.0.1:4001/health/liveliness
    ```
  </Step>

  <Step title="Point Claude Code at it">
    ```bash theme={null}
    export ANTHROPIC_BASE_URL="http://127.0.0.1:4001"
    export ANTHROPIC_AUTH_TOKEN="sk-claude-proxy"
    export ANTHROPIC_MODEL="kimi-k3-fast"
    export ANTHROPIC_DEFAULT_HAIKU_MODEL="kimi-k3-fast"
    claude
    ```

    `ANTHROPIC_DEFAULT_HAIKU_MODEL` handles background work such as session titles. Without it,
    those requests fail against a model the proxy does not serve.

    <Warning>
      Setting `ANTHROPIC_AUTH_TOKEN` overrides a Claude.ai login for that shell. Export these
      in a dedicated shell or profile to keep an existing subscription usable elsewhere.
    </Warning>
  </Step>
</Steps>

Claude Code does not recognize LithosAI model names, so it assumes a 200k-token context
window and compacts early. Set the real window to avoid that.

```bash theme={null}
export CLAUDE_CODE_MAX_CONTEXT_TOKENS=1048576
```

<Note>
  Check the [Models](https://console.lithosai.cloud/models) console page for each model's
  context window.
</Note>

## Troubleshooting

| Symptom | Cause |
| - | - |
| Empty replies, or the session appears to hang | The model entry uses `openai/` with `use_chat_completions_api`. Claude Code needs `hosted_vllm/`. |
| Background requests fail while chat works | `ANTHROPIC_DEFAULT_HAIKU_MODEL` is unset or names a model the proxy does not serve. |
| `400` with `No connected db.` | `ANTHROPIC_AUTH_TOKEN` does not match the proxy's `master_key`. LiteLLM reports the lookup failure, not an auth error. |

Issues common to every agent are listed under [Common issues](/agent-integrations#common-issues).


# Use LithosAI with Cline
Source: https://docs.lithosai.com/agent-integrations/cline

Connect Cline directly to LithosAI with an OpenAI-compatible provider.

## Before you begin

Install Cline CLI, create a key on the
[API Keys](https://console.lithosai.cloud/keys) page, and choose a model on the
[Models](https://console.lithosai.cloud/models) page.

<Steps>
  <Step title="Configure LithosAI">
    Run `cline auth`, select **OpenAI Compatible**, and enter:

    | Setting | Value |
    | - | - |
    | Base URL | `https://api.lithosai.cloud/v1` |
    | API key | Your LithosAI API key |
    | Model ID | A full ID from [Models](https://console.lithosai.cloud/models), such as `moonshotai/Kimi-K3-fast` |

    The examples below use `moonshotai/Kimi-K3-fast`. Replace it with your chosen
    model ID and adjust its token limits and supported reasoning settings.

    <Accordion title="Optional: edit provider settings">
      Edit the record created by `cline auth`, preserving other providers, `updatedAt`
      and `tokenSource`. Keep the API key private and set token limits for your model.

      ```json <data-dir>/settings/providers.json theme={null}
      {
        "version": 1,
        "lastUsedProvider": "openai-compatible",
        "modes": {},
        "providers": {
          "openai-compatible": {
            "settings": {
              "provider": "openai-compatible",
              "apiKey": "your-key",
              "model": "moonshotai/Kimi-K3-fast",
              "baseUrl": "https://api.lithosai.cloud/v1",
              "protocol": "openai-chat",
              "client": "openai-compatible",
              "reasoning": {
                "enabled": true,
                "effort": "high"
              },
              "capabilities": [
                "reasoning",
                "streaming",
                "tools"
              ],
              "contextWindow": 1048576,
              "maxTokens": 32768
            },
            "updatedAt": "2026-09-29T00:00:00.000Z",
            "tokenSource": "manual"
          }
        }
      }
      ```
    </Accordion>
  </Step>

  <Step title="Start a conversation">
    ```bash theme={null}
    cline --tui --provider openai-compatible \
      --model moonshotai/Kimi-K3-fast --thinking high --auto-approve false
    ```

    Use `/model` to switch models or tiers in the same conversation.
  </Step>
</Steps>

## Reasoning effort

Use `--thinking low` or `--thinking high` when starting or resuming Cline.
`max` is not supported.

<Accordion title="Set effort when resuming a conversation">
  ```bash theme={null}
  cline --tui --id SESSION_ID --provider openai-compatible \
    --model moonshotai/Kimi-K3-fast --thinking low --auto-approve false
  ```

  Get `SESSION_ID` from `cline history`. Keep the same `--data-dir` if you use one.
</Accordion>

`/model` resets the effort selected at startup.

Issues common to every agent are listed under [Common issues](/agent-integrations#common-issues).

## Resources

* [Cline documentation](https://docs.cline.bot/cli/cli-reference)
* [LithosAI models](https://console.lithosai.cloud/models)


# Use LithosAI with Codex
Source: https://docs.lithosai.com/agent-integrations/codex

Connect Codex to LithosAI through a LiteLLM Responses API compatibility proxy.

## Before you begin

Create a key on the [API Keys](https://console.lithosai.cloud/keys) page, confirm the model ID
on the [Models](https://console.lithosai.cloud/models) page, and export the key in the shell where you start Codex or its local proxy.

```bash theme={null}
export LITHOSAI_API_KEY="your-key"
```

Codex no longer speaks Chat Completions. `wire_api = "chat"` is rejected at startup, and
`responses` is the only accepted value, so Codex reaches LithosAI through a proxy that
accepts Responses API requests.

<Warning>
  This is a compatibility path, not native Responses API support. LiteLLM translates common
  text and function-tool requests, but Responses-only tools and metadata may not map to Chat
  Completions. If your workflow depends on a specific Codex tool, verify it before relying on
  this setup.
</Warning>

<Steps>
  <Step title="Install LiteLLM">
    [LiteLLM](https://docs.litellm.ai) bridges the Responses API to Chat Completions.

    ```bash theme={null}
    pip install 'litellm[proxy]'
    ```

    <Warning>
      Install a current release. LiteLLM 1.82.7 and 1.82.8 were briefly replaced on PyPI in
      March 2026 by a [credential stealer](https://docs.litellm.ai/blog/security-update-march-2026).
    </Warning>
  </Step>

  <Step title="Configure the proxy">
    The model below is an example, not the full LithosAI catalog. For another model
    or tier, replace the ID after `openai/` with one from [Models](https://console.lithosai.cloud/models).
    Keep the proxy's `model_name` and the Codex `model` setting consistent.

    Give the model the `openai/` prefix and set `use_chat_completions_api`, which bridges
    incoming `/v1/responses` requests to LithosAI's `/v1/chat/completions`.

    <Accordion title="LiteLLM proxy configuration">
      ```yaml codex.litellm.yaml theme={null}
      model_list:
        - model_name: kimi-k3-fast
          litellm_params:
            model: openai/moonshotai/Kimi-K3-fast
            api_base: https://api.lithosai.cloud/v1
            api_key: os.environ/LITHOSAI_API_KEY
            use_chat_completions_api: true
            additional_drop_params: ["reasoning_effort", "client_metadata"]

      litellm_settings:
        drop_params: true

      general_settings:
        master_key: sk-codex-proxy
      ```
    </Accordion>

    `drop_params` discards parameters a model does not accept rather than failing the
    request. `additional_drop_params` removes `reasoning_effort`: Codex asks for a reasoning
    summary, LiteLLM forwards that request in this field in a form LithosAI rejects, and
    Codex works without it. It also removes `client_metadata`, which LithosAI does not
    accept as a Chat Completions parameter. `master_key` is the token Codex sends to the proxy, not your
    LithosAI key.
  </Step>

  <Step title="Start the proxy">
    ```bash theme={null}
    litellm --config codex.litellm.yaml --host 127.0.0.1 --port 4000
    ```

    Leave it running, and confirm it is up. The proxy holds your LithosAI key, so keep it
    bound to `127.0.0.1` and do not expose it to a network.

    ```bash theme={null}
    curl http://127.0.0.1:4000/health/liveliness
    ```
  </Step>

  <Step title="Point Codex at it">
    <Accordion title="Codex configuration">
      ```toml ~/.codex/config.toml theme={null}
      model = "kimi-k3-fast"
      model_provider = "lithosai"

      [model_providers.lithosai]
      name = "LithosAI"
      base_url = "http://127.0.0.1:4000/v1"
      env_key = "LITELLM_API_KEY"
      wire_api = "responses"
      requires_openai_auth = false
      ```
    </Accordion>

    `env_key` names the variable holding the proxy's `master_key`, so export that too.

    ```bash theme={null}
    export LITELLM_API_KEY="sk-codex-proxy"
    codex
    ```
  </Step>
</Steps>

## Troubleshooting

| Symptom | Cause |
| - | - |
| `wire_api = "chat"` is no longer supported | `base_url` points at LithosAI directly. Point it at the proxy. |
| `404` on `/v1/responses` | The model entry uses `hosted_vllm/`. Codex needs `openai/` with `use_chat_completions_api`. |
| `400` with `No connected db.` | `LITELLM_API_KEY` does not match the proxy's `master_key`. LiteLLM reports the lookup failure, not an auth error. |
| `400` mentioning `reasoning_effort` and `Input should be 'none', 'minimal', ...` | The proxy configuration is missing `additional_drop_params: ["reasoning_effort", "client_metadata"]`. |

Issues common to every agent are listed under [Common issues](/agent-integrations#common-issues).


# Use LithosAI with DeepSeek Harness
Source: https://docs.lithosai.com/agent-integrations/deepseek-harness

Connect DeepSeek Harness directly to LithosAI through the OpenAI Chat Completions API.

## Before you begin

Install DeepSeek Harness, create a key on the
[API Keys](https://console.lithosai.cloud/keys) page, and choose a model on the
[Models](https://console.lithosai.cloud/models) page.

<Note>
  DeepSeek Harness is in developer preview, and its configuration format can change between
  releases. These steps were tested with versions 0.2.0-rc.2 and 0.2.1-rc.2.
</Note>

<Steps>
  <Step title="Set your API key">
    Export your key in the shell where you start DeepSeek Harness:

    ```bash theme={null}
    export LITHOSAI_API_KEY="your-key"
    ```

    The desktop app reads your login shell's environment, so add this line to `~/.zshrc` and
    restart the app. After you configure LithosAI in the next step, you can instead enter the key in
    **Settings → Models**: edit **LithosAI**, enter the key, and select **Apply**. DeepSeek Harness
    stores it in `~/.dsh/.credentials.yaml`.
  </Step>

  <Step title="Configure LithosAI">
    The configuration uses `moonshotai/Kimi-K3-fast` as an example.

    Add the configuration to the profile for the way you run DeepSeek Harness:

    * `dsh web`: `~/.dsh/profiles/web/cordis.patch.yml`
    * Desktop app: `~/.dsh/profiles/desktop/cordis.patch.yml`
    * `dsh headless`: `~/.dsh/profiles/headless/cordis.patch.yml`

    `llm-pi-ai` is the plugin DeepSeek Harness uses for third-party model providers. DeepSeek
    Harness also writes to this file, for example when you change the model or effort. If the file
    already has an `llm-pi-ai` entry, don't add a second one. Copy only the `lithosai:` block into
    that entry's `providers`. If it already has an `agent-default-model` entry, change that entry
    instead. Set the token limits to match your model.

    <Accordion title="DeepSeek Harness configuration">
      ```yaml cordis.patch.yml theme={null}
      - id: llm-pi-ai
        config:
          providers:
            lithosai:
              displayName: LithosAI
              apiKeyEnv: LITHOSAI_API_KEY
              api: openai-completions
              baseURL: https://api.lithosai.cloud/v1
              compat:
                supportsReasoningEffort: true
                maxTokensField: max_tokens
              models:
                - id: moonshotai/Kimi-K3-fast
                  name: moonshotai/Kimi-K3-fast
                  contextWindow: 1048576
                  maxTokens: 32768
                  reasoningEfforts:
                    low: low
                    high: high
                    max: max
      - id: agent-default-model
        config:
          provider: lithosai
          model: moonshotai/Kimi-K3-fast
          reasoningEffort: high
      ```
    </Accordion>

    To add another model or tier, copy the entry under `providers.lithosai.models`.
    Set `id` and `name` to the ID from the [model catalog](https://console.lithosai.cloud/models),
    and adjust `contextWindow` and `maxTokens` to match the model. Restart DeepSeek Harness to
    load the changes.
  </Step>

  <Step title="Start a conversation">
    Start DeepSeek Harness from the profile you configured.

    **Web UI:** Run the following command:

    ```bash theme={null}
    npx @deepseek-ai/dsh web
    ```

    The Web UI opens in your browser. If it doesn't, open the URL that the command prints. The URL
    includes an access token.

    **Desktop app:** Open the app. If it shows a welcome screen, select **Add API Key**, then
    **Configure later**. You don't need a DeepSeek account.

    **Headless:** Run DeepSeek Harness in your project directory with the task as an argument. It
    prints the answer and exits.

    ```bash theme={null}
    npx @deepseek-ai/dsh headless "Summarize this repository"
    ```
  </Step>
</Steps>

## Model and reasoning effort

* **Model and tier:** Open the model menu in the message box and choose **Model**.
* **Reasoning effort:** In the same menu, choose **Effort** and select **Low**, **High**, or
  **Max**. The configuration starts at **High**. The level you select becomes the new default.
* **Headless:** There is no menu. Change `model` and `reasoningEffort` in the
  `agent-default-model` entry of the headless profile.

Issues common to every agent are listed under [Common issues](/agent-integrations#common-issues).

## Resources

* [DeepSeek Harness model configuration](https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/user/guide/providers.md)
* [LithosAI models](https://console.lithosai.cloud/models)


# Use LithosAI with Hermes Agent
Source: https://docs.lithosai.com/agent-integrations/hermes-agent

Connect Hermes Agent directly to LithosAI through the OpenAI Chat Completions API.

## Before you begin

Install Hermes Agent CLI, create a key on the
[API Keys](https://console.lithosai.cloud/keys) page, and choose a model on the
[Models](https://console.lithosai.cloud/models) page.

<Steps>
  <Step title="Set your API key">
    Add your key to `~/.hermes/.env`:

    <Accordion title="Hermes API key configuration">
      ```bash ~/.hermes/.env theme={null}
      LITHOSAI_API_KEY=your-key
      ```
    </Accordion>
  </Step>

  <Step title="Configure LithosAI">
    The configuration uses `moonshotai/Kimi-K3-fast` as an example.

    Merge into `~/.hermes/config.yaml`, keeping existing providers. Set
    `context_length` to match your model, with a minimum of
    [64,000 tokens](https://hermes-agent.nousresearch.com/docs/getting-started/quickstart).

    <Accordion title="Hermes configuration">
      ```yaml ~/.hermes/config.yaml theme={null}
      providers:
        lithosai:
          api: https://api.lithosai.cloud/v1
          key_env: LITHOSAI_API_KEY
          transport: chat_completions
          default_model: moonshotai/Kimi-K3-fast
          discover_models: false
          context_length: 1048576
          models:
            moonshotai/Kimi-K3-fast:
              context_length: 1048576
              supports_reasoning: true
      model:
        default: moonshotai/Kimi-K3-fast
        provider: custom:lithosai
      agent:
        reasoning_effort: high
      ```
    </Accordion>

    To add another model or tier, copy the entry under `providers.lithosai.models`.
    Use its ID from the [model catalog](https://console.lithosai.cloud/models) as the new key,
    and set `context_length` to match the model. Reopen Hermes to load the changes.
  </Step>

  <Step title="Start a conversation">
    Run `hermes` to start a conversation.
  </Step>
</Steps>

## Model and reasoning effort

* **Model and tier:** Use `/model` to switch in the current conversation.
* **Reasoning effort:** Use `/reasoning` to select **low**, **high**, or **max**. The default is **high**.

Issues common to every agent are listed under [Common issues](/agent-integrations#common-issues).

## Resources

* [Hermes Agent documentation](https://hermes-agent.nousresearch.com/docs/user-guide/sessions)
* [LithosAI models](https://console.lithosai.cloud/models)


# Use LithosAI with Kilo Code
Source: https://docs.lithosai.com/agent-integrations/kilo-code

Connect Kilo Code directly to LithosAI with an OpenAI-compatible custom provider.

## Before you begin

Install Kilo Code in VS Code or use its CLI, create a key on the
[API Keys](https://console.lithosai.cloud/keys) page, and choose a model on the
[Models](https://console.lithosai.cloud/models) page.

Choose your interface:

<Tabs>
  <Tab title="VS Code extension">
    <Steps>
      <Step title="Configure LithosAI">
        Open **Settings → Providers → Custom provider** and enter:

        | Setting | Value |
        | - | - |
        | Provider ID | `lithosai` |
        | Display name | `LithosAI` |
        | Provider API | **OpenAI Compatible** |
        | Base URL | `https://api.lithosai.cloud/v1` |
        | API key | Your LithosAI API key |
        | Models | Add or select IDs from the [LithosAI model catalog](https://console.lithosai.cloud/models), such as `moonshotai/Kimi-K3-fast` |
      </Step>

      <Step title="Save the provider">
        Click **Submit** to save the provider. Its configured models are then available
        in the chat model picker.

        In **Global Config**, set `limit.context` and `limit.output` to match your model.
      </Step>
    </Steps>

    **Reasoning effort**

    <Accordion title="VS Code reasoning effort configuration">
      Open **Global Config** and merge these fields into your model entry under
      `provider.lithosai.models` to enable **low**, **high**, and **max**, with **high** as the default:

      ```json theme={null}
      {
        "reasoning": true,
        "options": { "reasoningEffort": "high" },
        "variants": {
          "low": { "reasoningEffort": "low" },
          "high": { "reasoningEffort": "high" },
          "max": { "reasoningEffort": "max" },
          "medium": { "disabled": true },
          "minimal": { "disabled": true },
          "xhigh": { "disabled": true }
        }
      }
      ```
    </Accordion>
  </Tab>

  <Tab title="CLI">
    <Steps>
      <Step title="Set your API key">
        Export your key:

        ```bash theme={null}
        export LITHOSAI_API_KEY="your-key"
        ```
      </Step>

      <Step title="Configure LithosAI">
        The configuration below uses `moonshotai/Kimi-K3-fast` as an example.

        Merge into `~/.config/kilo/kilo.jsonc` and set the token limits to match your model.
        Use this global file: `{env:...}` credentials do not resolve in untrusted project files.

        <Accordion title="Kilo CLI configuration">
          ```json ~/.config/kilo/kilo.jsonc theme={null}
          {
            "$schema": "https://app.kilo.ai/config.json",
            "model": "lithosai/moonshotai/Kimi-K3-fast",
            "provider": {
              "lithosai": {
                "npm": "@ai-sdk/openai-compatible",
                "name": "LithosAI",
                "options": {
                  "baseURL": "https://api.lithosai.cloud/v1",
                  "apiKey": "{env:LITHOSAI_API_KEY}"
                },
                "models": {
                  "moonshotai/Kimi-K3-fast": {
                    "name": "moonshotai/Kimi-K3-fast",
                    "reasoning": true,
                    "limit": {
                      "context": 1048576,
                      "output": 32768
                    },
                    "options": { "reasoningEffort": "high" },
                    "variants": {
                      "low": { "reasoningEffort": "low" },
                      "high": { "reasoningEffort": "high" },
                      "max": { "reasoningEffort": "max" },
                      "medium": { "disabled": true },
                      "minimal": { "disabled": true },
                      "xhigh": { "disabled": true }
                    }
                  }
                }
              }
            }
          }
          ```
        </Accordion>

        To add another model or tier, copy the entry under `provider.lithosai.models` and
        update its key and `name` using the [model catalog](https://console.lithosai.cloud/models).
        Adjust its token limits and supported reasoning efforts, then reopen Kilo.
      </Step>

      <Step title="Start a conversation">
        Run `kilo`. Use `/models` to switch between configured models in the current conversation.
      </Step>
    </Steps>

    **Reasoning effort**

    Use `/variants` to select **low**, **high**, or **max**. The default is **high**.
  </Tab>
</Tabs>

Issues common to every agent are listed under [Common issues](/agent-integrations#common-issues).

## Resources

* [Kilo Code documentation](https://kilo.ai/docs/ai-providers/openai-compatible)
* [LithosAI models](https://console.lithosai.cloud/models)


# Use LithosAI with omp
Source: https://docs.lithosai.com/agent-integrations/omp

Connect omp directly to LithosAI through the OpenAI Chat Completions API.

## Before you begin

Install omp CLI, create a key on the
[API Keys](https://console.lithosai.cloud/keys) page, and choose a model on the
[Models](https://console.lithosai.cloud/models) page.

<Steps>
  <Step title="Set your API key">
    Export your key:

    ```bash theme={null}
    export LITHOSAI_API_KEY="your-key"
    ```
  </Step>

  <Step title="Configure LithosAI">
    The configuration uses `moonshotai/Kimi-K3-fast` as an example.

    Add to `~/.omp/agent/models.yml`. Keep existing providers and set the token
    limits to match your model.

    <Accordion title="omp configuration">
      ```yaml ~/.omp/agent/models.yml theme={null}
      providers:
        lithosai:
          baseUrl: https://api.lithosai.cloud/v1
          api: openai-completions
          apiKey: LITHOSAI_API_KEY
          models:
          - id: moonshotai/Kimi-K3-fast
            name: moonshotai/Kimi-K3-fast
            reasoning: true
            thinking:
              mode: effort
              efforts:
              - low
              - high
              - max
              defaultLevel: high
              effortMap:
                low: low
                high: high
                max: max
            contextWindow: 1048576
            maxTokens: 32768
            compat:
              supportsReasoningEffort: true
              thinkingFormat: openai
              maxTokensField: max_tokens
              reasoningEffortMap:
                low: low
                high: high
                max: max
      ```
    </Accordion>

    To add another model or tier, copy the entry in `providers.lithosai.models`.
    Set `id` and `name` to the ID from the [model catalog](https://console.lithosai.cloud/models),
    and adjust `contextWindow` and `maxTokens` to match the model. Reopen omp to load the changes.
  </Step>

  <Step title="Start a conversation">
    Run the following command:

    ```bash theme={null}
    omp --provider lithosai --model moonshotai/Kimi-K3-fast --thinking high
    ```
  </Step>
</Steps>

## Model and reasoning effort

* **Current model and tier:** Use `/switch lithosai/<model-id>:high`.
* **Default model:** Use `/model`.
* **Reasoning effort:** Press **Shift+Tab** to choose **low**, **high**, or **max**.

Issues common to every agent are listed under [Common issues](/agent-integrations#common-issues).

## Resources

* [omp documentation](https://github.com/can1357/oh-my-pi/blob/main/docs/models.md)
* [LithosAI models](https://console.lithosai.cloud/models)


# Use LithosAI with OpenClaw
Source: https://docs.lithosai.com/agent-integrations/openclaw

Connect OpenClaw directly to LithosAI with a custom OpenAI-compatible provider.

## Before you begin

Install OpenClaw CLI, create a key on the
[API Keys](https://console.lithosai.cloud/keys) page, and choose a model on the
[Models](https://console.lithosai.cloud/models) page.

<Steps>
  <Step title="Set your API key">
    Set your key in the Gateway’s environment:

    ```bash theme={null}
    export LITHOSAI_API_KEY="your-key"
    ```

    For a managed service, set the variable in its service configuration.
  </Step>

  <Step title="Configure LithosAI">
    The configuration uses `moonshotai/Kimi-K3-fast` as an example.

    Merge into `~/.openclaw/openclaw.json`, keeping existing settings. Set the token
    limits to match your model.

    <Accordion title="OpenClaw configuration">
      ```json ~/.openclaw/openclaw.json theme={null}
      {
        "agents": {
          "defaults": {
            "model": { "primary": "lithosai/moonshotai/Kimi-K3-fast" },
            "models": {
              "lithosai/moonshotai/Kimi-K3-fast": {}
            },
            "thinkingDefault": "high"
          }
        },
        "models": {
          "mode": "merge",
          "providers": {
            "lithosai": {
              "baseUrl": "https://api.lithosai.cloud/v1",
              "apiKey": "${LITHOSAI_API_KEY}",
              "api": "openai-completions",
              "models": [
                {
                  "id": "moonshotai/Kimi-K3-fast",
                  "name": "moonshotai/Kimi-K3-fast",
                  "reasoning": true,
                  "input": ["text"],
                  "contextWindow": 1048576,
                  "maxTokens": 32768,
                  "compat": {
                    "supportsReasoningEffort": true,
                    "supportedReasoningEfforts": ["low", "high", "max"],
                    "reasoningEffortMap": {
                      "low": "low",
                      "high": "high",
                      "max": "max",
                      "xhigh": "max"
                    },
                    "thinkingFormat": "openai",
                    "maxTokensField": "max_tokens"
                  },
                  "thinkingLevelMap": {
                    "minimal": null,
                    "low": "low",
                    "medium": null,
                    "high": "high",
                    "xhigh": null,
                    "max": "max"
                  }
                }
              ]
            }
          }
        }
      }
      ```
    </Accordion>

    To add another model or tier, copy the entry in `models.providers.lithosai.models`.
    Set `id` and `name` to the ID from the [model catalog](https://console.lithosai.cloud/models),
    and adjust `contextWindow` and `maxTokens` to match the model. Also add
    `lithosai/<model-id>` to `agents.defaults.models`.
  </Step>

  <Step title="Restart the Gateway">
    Restart your Gateway to load the provider and key:

    ```bash theme={null}
    openclaw gateway restart
    ```
  </Step>
</Steps>

## Model and reasoning effort

* **Model and tier:** Use `/model lithosai/<model-id>`; in the TUI, use `/models`.
* **Reasoning effort:** Use `/think low`, `/think high`, or `/think max`.

<Accordion title="Use a local TUI without a Gateway">
  With the same configuration and your key exported:

  ```bash theme={null}
  openclaw tui --local
  ```

  Use `/models` and `/think`. Omit the startup `--thinking` flag, which overrides
  the session’s effort selection.
</Accordion>

Issues common to every agent are listed under [Common issues](/agent-integrations#common-issues).

## Resources

* [OpenClaw documentation](https://docs.openclaw.ai/gateway/config-tools/custom-providers)
* [LithosAI models](https://console.lithosai.cloud/models)


# Use LithosAI with OpenCode
Source: https://docs.lithosai.com/agent-integrations/opencode

Connect OpenCode directly to LithosAI through the OpenAI Chat Completions API.

## Before you begin

Install the OpenCode CLI with `npm i -g opencode-ai`, create a key on the
[API Keys](https://console.lithosai.cloud/keys) page, and choose a model on the
[Models](https://console.lithosai.cloud/models) page. These steps were tested with OpenCode 1.19.0.

<Steps>
  <Step title="Set your API key">
    Export your key in the shell that runs OpenCode:

    ```bash theme={null}
    export LITHOSAI_API_KEY="your-key"
    ```
  </Step>

  <Step title="Configure LithosAI">
    Merge this configuration into `~/.config/opencode/opencode.json`, keeping your existing
    providers, or create the file if it does not exist. The example includes Kimi K3 fast,
    Kimi K3 ultra, and DeepSeek V4.1 Flash fast. Keep the top-level `model` line; without it,
    OpenCode picks its own default.

    <Accordion title="OpenCode configuration">
      ```json ~/.config/opencode/opencode.json theme={null}
      {
        "$schema": "https://opencode.ai/config.json",
        "model": "lithosai/moonshotai/Kimi-K3-fast",
        "provider": {
          "lithosai": {
            "npm": "@ai-sdk/openai-compatible",
            "name": "LithosAI",
            "options": {
              "baseURL": "https://api.lithosai.cloud/v1",
              "apiKey": "{env:LITHOSAI_API_KEY}"
            },
            "models": {
              "moonshotai/Kimi-K3-fast": {
                "name": "moonshotai/Kimi-K3-fast",
                "reasoning": true,
                "limit": {
                  "context": 1048576,
                  "output": 32768
                },
                "options": { "reasoningEffort": "high" },
                "variants": {
                  "low": { "reasoningEffort": "low" },
                  "high": { "reasoningEffort": "high" },
                  "max": { "reasoningEffort": "max" },
                  "minimal": { "disabled": true },
                  "medium": { "disabled": true },
                  "xhigh": { "disabled": true }
                }
              },
              "moonshotai/Kimi-K3-ultra": {
                "name": "moonshotai/Kimi-K3-ultra",
                "reasoning": true,
                "limit": {
                  "context": 1048576,
                  "output": 32768
                },
                "options": { "reasoningEffort": "high" },
                "variants": {
                  "low": { "reasoningEffort": "low" },
                  "high": { "reasoningEffort": "high" },
                  "max": { "reasoningEffort": "max" },
                  "minimal": { "disabled": true },
                  "medium": { "disabled": true },
                  "xhigh": { "disabled": true }
                }
              },
              "deepseek-ai/DeepSeek-V4.1-Flash-fast": {
                "name": "deepseek-ai/DeepSeek-V4.1-Flash-fast",
                "reasoning": true,
                "limit": {
                  "context": 1048576,
                  "output": 32768
                },
                "options": { "reasoningEffort": "high" },
                "variants": {
                  "low": { "reasoningEffort": "low" },
                  "high": { "reasoningEffort": "high" },
                  "max": { "reasoningEffort": "max" },
                  "minimal": { "disabled": true },
                  "medium": { "disabled": true },
                  "xhigh": { "disabled": true }
                }
              }
            }
          }
        }
      }
      ```
    </Accordion>

    For other models or tiers, copy an entry under `provider.lithosai.models` and update
    its key and `name` using the [model catalog](https://console.lithosai.cloud/models).
    Adjust the token limits and supported reasoning efforts for that model, then reopen OpenCode.
  </Step>

  <Step title="Start a conversation">
    Run `opencode` to start a conversation.
  </Step>
</Steps>

## Model and reasoning effort

* **Model and tier:** Use `/models` to switch in the current conversation.
* **Reasoning effort:** Use `/variants` to select **low**, **high**, or **max**. The default is
  **high**. With `opencode run`, pass `--variant` followed by **low**, **high**, or **max**.
  OpenCode ignores any other value and uses **high**.

## Troubleshooting

* If `opencode run` prints `UnknownError` with `Unexpected server error`, check that the
  selected model matches a model key in your configuration. With `-m`, include the provider
  prefix, for example `lithosai/moonshotai/Kimi-K3-fast`. Model IDs are case-sensitive.
  Run the command again with `--print-logs` to see the underlying error.
* Don't set `setCacheKey` in the provider options. If it is set, OpenCode sends `promptCacheKey`,
  which LithosAI rejects with `400 unknown_parameter`. LithosAI caches repeated prompts without it.

Issues common to every agent, with the errors LithosAI returns, are listed under
[Common issues](/agent-integrations#common-issues).

## Resources

* [OpenCode documentation](https://opencode.ai/docs/)
* [LithosAI models](https://console.lithosai.cloud/models)


# Use LithosAI with OpenHands
Source: https://docs.lithosai.com/agent-integrations/openhands

Connect OpenHands directly to LithosAI through its OpenAI-compatible LLM settings.

## Before you begin

Install and start OpenHands, create a key on the
[API Keys](https://console.lithosai.cloud/keys) page, and confirm the model ID you want to use
on the [Models](https://console.lithosai.cloud/models) page.

<Steps>
  <Step title="Open the LLM settings">
    Open the OpenHands web interface. In the initial setup dialog, select
    **See advanced settings**. If setup is already complete, open **Settings**, choose
    **LLM**, and enable **Advanced**.
  </Step>

  <Step title="Configure LithosAI">
    Enter the following values:

    | Field | Value |
    | - | - |
    | Custom Model | `openai/moonshotai/Kimi-K3-fast` |
    | Base URL | `https://api.lithosai.cloud/v1` |
    | API Key | Your LithosAI API key |

    `moonshotai/Kimi-K3-fast` is an example. Replace it with your chosen model or tier.

    The `openai/` prefix selects OpenHands' OpenAI-compatible client. The remainder must match
    the model ID shown in the LithosAI console.

    <Tip>
      OpenHands needs a large context window for its system prompt and tools. Pick a model with
      enough context for your repository and task.
    </Tip>
  </Step>

  <Step title="Save and start a session">
    Select **Save Settings**, create a workspace, and start a new conversation.
  </Step>
</Steps>

## Troubleshooting

| Symptom | Cause |
| - | - |
| OpenHands cannot find the model | The Custom Model value is missing `openai/`, or the remaining model ID is incorrect. |
| OpenHands behaves like a plain chatbot | The selected model may not perform tool calls reliably. Try a stronger coding model. |
| The agent loses context early | The selected model's context window is too small for the OpenHands prompt and workspace. |

Issues common to every agent are listed under [Common issues](/agent-integrations#common-issues).

## Resources

* [OpenHands OpenAI-compatible LLM setup](https://docs.openhands.dev/openhands/usage/llms/local-llms)
* [Install OpenHands](https://docs.openhands.dev/openhands/usage/installation)
* [LithosAI models](https://console.lithosai.cloud/models)


# Use LithosAI with Pi
Source: https://docs.lithosai.com/agent-integrations/pi

Connect Pi directly to LithosAI through the OpenAI Chat Completions API.

## Before you begin

Install Pi CLI, create a key on the
[API Keys](https://console.lithosai.cloud/keys) page, and choose a model on the
[Models](https://console.lithosai.cloud/models) page.

<Steps>
  <Step title="Set your API key">
    Export your key:

    ```bash theme={null}
    export LITHOSAI_API_KEY="your-key"
    ```
  </Step>

  <Step title="Configure LithosAI">
    The configuration uses `moonshotai/Kimi-K3-fast` as an example.

    Add to `~/.pi/agent/models.json`. Keep existing providers and set the token
    limits to match your model.

    <Accordion title="Pi configuration">
      ```json ~/.pi/agent/models.json theme={null}
      {
        "providers": {
          "lithosai": {
            "baseUrl": "https://api.lithosai.cloud/v1",
            "api": "openai-completions",
            "apiKey": "$LITHOSAI_API_KEY",
            "models": [
              {
                "id": "moonshotai/Kimi-K3-fast",
                "name": "moonshotai/Kimi-K3-fast",
                "reasoning": true,
                "contextWindow": 1048576,
                "maxTokens": 32768,
                "thinkingLevelMap": {
                  "minimal": null,
                  "low": "low",
                  "medium": null,
                  "high": "high",
                  "xhigh": null,
                  "max": "max"
                },
                "compat": {
                  "supportsReasoningEffort": true,
                  "maxTokensField": "max_tokens"
                }
              }
            ]
          }
        }
      }
      ```
    </Accordion>

    To add another model or tier, copy the entry in `providers.lithosai.models`.
    Set `id` and `name` to the ID from the [model catalog](https://console.lithosai.cloud/models),
    and adjust `contextWindow` and `maxTokens` to match the model. Reopen Pi to load the changes.
  </Step>

  <Step title="Start a conversation">
    Run the following command:

    ```bash theme={null}
    pi --provider lithosai --model moonshotai/Kimi-K3-fast --thinking high
    ```
  </Step>
</Steps>

## Model and reasoning effort

* **Model and tier:** Use `/model` to switch in the current conversation.
* **Reasoning effort:** Open `/settings` and select **low**, **high**, or **max**.

Issues common to every agent are listed under [Common issues](/agent-integrations#common-issues).

## Resources

* [Pi documentation](https://github.com/badlogic/pi-mono/tree/main/packages/coding-agent)
* [LithosAI models](https://console.lithosai.cloud/models)


# Use LithosAI with VS Code
Source: https://docs.lithosai.com/agent-integrations/vscode

Connect the built-in chat in VS Code to LithosAI with a Custom Endpoint model.

<Note>
  This guide configures the chat built into VS Code. Agent extensions keep their own
  provider settings: if you use Kilo Code in VS Code, follow the
  [Kilo Code guide](/agent-integrations/kilo-code) instead.
</Note>

## Before you begin

Install VS Code 1.122 or later, create a key on the [API Keys](https://console.lithosai.cloud/keys) page,
and choose a model on the [Models](https://console.lithosai.cloud/models) page.

<Steps>
  <Step title="Add a Custom Endpoint">
    In the Chat view, open the model picker (**Models**) and select **+**, or run
    **Chat: Manage Language Models** from the Command Palette.
    The **Language Models** editor opens.

    Select **Add Models → Custom Endpoint**. VS Code asks for these values in turn:

    | Prompt | Value |
    | - | - |
    | Group Name | `LithosAI` |
    | API Key | Your LithosAI API key |
    | API Type | **Chat Completions** |
  </Step>

  <Step title="Configure the model">
    VS Code opens `chatLanguageModels.json` with a `LithosAI` entry and an empty model.
    Leave `name`, `vendor`, `apiKey`, and `apiType` as VS Code wrote them: `apiKey` refers to
    the key you entered, which VS Code keeps in secret storage. Replace the empty model under
    `models` with the entry below and save the file.

    The entry below uses `moonshotai/Kimi-K3-fast` as an example.

    <Accordion title="VS Code model entry">
      ```json theme={null}
      {
        "id": "moonshotai/Kimi-K3-fast",
        "name": "moonshotai/Kimi-K3-fast",
        "url": "https://api.lithosai.cloud/v1/chat/completions",
        "toolCalling": true,
        "vision": false,
        "maxInputTokens": 1015808,
        "maxOutputTokens": 32768,
        "thinking": true,
        "supportsReasoningEffort": ["low", "high", "max"],
        "reasoningEffortFormat": "chat-completions"
      }
      ```
    </Accordion>

    Set `url` to the full Chat Completions endpoint, not the base URL. VS Code treats
    `maxInputTokens` plus `maxOutputTokens` as the context window, so set `maxInputTokens`
    to the model's context window minus `maxOutputTokens`.

    To add another model or tier, copy the entry under `models` and update its `id`, `name`,
    and token limits using the [model catalog](https://console.lithosai.cloud/models).
  </Step>

  <Step title="Start a conversation">
    In the Chat view, select **New Chat** (`+`), set **Session Target** to **Local**, and choose
    your LithosAI model in the model picker. Select **Agent** in the agent picker to let the model
    edit files and run tools.
  </Step>
</Steps>

## Model and reasoning effort

* **Model and tier:** Use the model picker in the Chat view.
* **Reasoning effort:** In the model picker, select **>** next to your LithosAI model to open
  **Thinking Effort**, then select **low**, **high**, or **max**. VS Code remembers the level for
  each session.

## Use VS Code without a GitHub account

Chat and Agent sessions with a LithosAI model work without a GitHub sign-in or a Copilot plan.
Without a sign-in, VS Code has no model for background tasks such as chat titles and
commit messages, and it shows **Set BYOK utility models** in the Chat view. Setting utility models
is optional. To enable those tasks, open Settings and select your LithosAI model for
`chat.utilityModel` and `chat.utilitySmallModel`. VS Code recommends a fast, inexpensive model
for `chat.utilitySmallModel`. Each background task is a separate LithosAI request.

Inline suggestions (code completions) and semantic search still require a GitHub account.

## Limitations

* The **Copilot** session target and the **Agents** window don't list LithosAI models by
  default. To use them there, enable `chat.agentHost.byokModels.enabled`, which VS Code
  marks as experimental.
* On Copilot Business or Enterprise, your administrator can disable the
  **Bring Your Own Language Model Key in VS Code** policy. You then can't add LithosAI models.

Issues common to every agent are listed under [Common issues](/agent-integrations#common-issues).

## Resources

* [VS Code language models](https://code.visualstudio.com/docs/agent-customization/language-models)
* [VS Code agent harnesses](https://code.visualstudio.com/docs/agents/run/agent-harnesses)
* [LithosAI models](https://console.lithosai.cloud/models)


# Create a chat completion
Source: https://docs.lithosai.com/api-reference/chat/create-a-chat-completion

/openapi.yaml post /chat/completions
Generates a completion for the supplied conversation.

Set `stream: true` to receive Server-Sent Events. Most chunks carry
a `usage` object: the opening role delta and the chunk carrying `finish_reason` omit
it. The final chunk before `[DONE]` reports the totals with an empty `choices`
array.

Sampling constraints are **per model**. The bounds in this schema are the OpenAI-wire
bounds, not the per-model ones.

Retry 429 and 5xx with exponential backoff and jitter. Prefer the delay we advise,
`retry-after-ms` first and then `retry-after`, over an interval of your own. Do not
retry 400, 401, 402 or 404, and do not retry anything carrying `x-should-retry: false`:
the answer will not change until you do something about it.

A 429 means one of your three per-minute budgets is empty. See
[Rate limits](/rate-limits) for what they are and how to read the headers that
report them.




# List available models
Source: https://docs.lithosai.com/api-reference/models/list-available-models

/openapi.yaml get /models
Lists the models your organization can call.



# Retrieve a model
Source: https://docs.lithosai.com/api-reference/models/retrieve-a-model

/openapi.yaml get /models/{author}/{slug}
Retrieves a single model by author and slug.




# Authentication
Source: https://docs.lithosai.com/authentication



Create a bearer token at [API Keys](https://console.lithosai.cloud/keys), and set the
`Authorization` header to `Bearer $LITHOSAI_API_KEY`, where `$LITHOSAI_API_KEY` is the
generated token.

```bash theme={null}
curl https://api.lithosai.cloud/v1/models \
  -H "Authorization: Bearer $LITHOSAI_API_KEY"
```

<Warning>
  A key is shown only at its creation.
</Warning>

A key is associated with its organization, not the user who created it.

Every key in an organization draws on the same [rate limits](/rate-limits) and the same
credit balance, so adding keys separates attribution, not budget.


# Billing
Source: https://docs.lithosai.com/billing



LithosAI inference service is prepaid. Each request is metered to the token and debited
from your organization's balance.

## Rates

Each model carries three rates per million tokens: input, cached input and output. Cached
input is a subset of input rather than an addition to it, so a request is charged the input
rate for `prompt_tokens - cached_tokens`, the cached rate for `cached_tokens`, and the
output rate for `completion_tokens`.

## Running out

At a zero balance, requests return 402 with code `insufficient_quota` and `x-should-retry: false`. Top up from the [Billing](https://console.lithosai.cloud/billing) page, between \$5 and \$5,000 a purchase.

## Automatic reload

The platform supports automatic reload. Set a threshold, a target and a monthly cap: when
the balance falls below the threshold we charge your saved card enough to restore the
target, and never more than the cap in one calendar month. If a charge fails, reload
disarms itself and your organization's admins are emailed rather than the card being
retried indefinitely.

## Reporting

Spend and token counts are broken down by day, model and API key on the
[Billing](https://console.lithosai.cloud/billing) and
[Analytics](https://console.lithosai.cloud/analytics) pages.


# LithosAI APIs
Source: https://docs.lithosai.com/index



LithosAI provides an OpenAI-compatible API. Use any OpenAI client library, such as [the official OpenAI SDK](https://developers.openai.com/api/docs/libraries?language=python#install-an-official-sdk), to access the LithosAI APIs.

## Base URL

Use the `https://api.lithosai.cloud/v1` base URL for all requests to the LithosAI APIs.

## Your first request

Create a key on the [API Keys](https://console.lithosai.cloud/keys) page, export it as `LITHOSAI_API_KEY`, and send a request.

<CodeGroup>
  ```python Python theme={null}
  import os

  from openai import OpenAI

  client = OpenAI(
      api_key=os.environ["LITHOSAI_API_KEY"],
      base_url="https://api.lithosai.cloud/v1",
  )

  response = client.chat.completions.create(
      model="moonshotai/Kimi-K3",
      messages=[{"role": "user", "content": "Hello"}],
  )
  print(response.choices[0].message.content)
  ```

  ```typescript TypeScript theme={null}
  import OpenAI from "openai";

  const client = new OpenAI({
    apiKey: process.env.LITHOSAI_API_KEY,
    baseURL: "https://api.lithosai.cloud/v1",
  });

  const response = await client.chat.completions.create({
    model: "moonshotai/Kimi-K3",
    messages: [{ role: "user", content: "Hello" }],
  });
  console.log(response.choices[0].message.content);
  ```

  ```bash curl theme={null}
  curl https://api.lithosai.cloud/v1/chat/completions \
    -H "Authorization: Bearer $LITHOSAI_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"model":"moonshotai/Kimi-K3","messages":[{"role":"user","content":"Hello"}]}'
  ```
</CodeGroup>

## Next steps

<CardGroup>
  <Card title="Authentication" icon="key" href="/authentication">
    Create a key and authorize your requests.
  </Card>

  <Card title="Chat Completions" icon="message" href="/api-reference/chat/create-a-chat-completion">
    Send prompts and stream tokens back.
  </Card>

  <Card title="Agent Integrations" icon="terminal" href="/agent-integrations">
    Connect popular coding agents to LithosAI models.
  </Card>

  <Card title="Rate limits" icon="gauge" href="/rate-limits">
    Three per-minute budgets, and how to read them.
  </Card>

  <Card title="Billing" icon="credit-card" href="/billing">
    Prepaid credit, per-token rates and automatic reload.
  </Card>
</CardGroup>


# Rate Limits
Source: https://docs.lithosai.com/rate-limits



Your organization has three per-minute budgets for each model: requests, input tokens and output tokens. Input and output are counted separately, so a large prompt and a long generation draw down different budgets.

Every key in an organization draws on the same rate limits and the same credit balance, so adding keys separates attribution, not budget.

Each budget refills continuously rather than resetting on a clock, and its capacity is set separately from its per-minute rate. So the remaining figures are not your limit minus what you have spent this minute. Read them as a balance rather than a countdown.

Exhausting one returns 429 with code `rate_limit_exceeded`, and `error.type` names the budget that refused: `requests`, `input_tokens` or `output_tokens`.

## Headers

| Header | Meaning |
| - | - |
| `x-ratelimit-limit-requests` | The capacity of your request bucket. |
| `x-ratelimit-remaining-requests` | Requests left in it. |
| `x-ratelimit-reset-requests` | How long until that bucket is full again. |
| `x-ratelimit-limit-tokens` | The capacity of whichever token bucket is nearer its limit. |
| `x-ratelimit-remaining-tokens` | Tokens left in it. |
| `x-ratelimit-reset-tokens` | How long until it is full again. |
| `retry-after` | Seconds to wait, on a refusal where waiting helps. |
| `retry-after-ms` | The same advice in milliseconds, and the more precise of the two. |
| `x-should-retry` | Set to false where no amount of waiting will change the answer. |

The rate limit headers accompany any response where your budgets were consulted, which is every admitted request and every rate limit refusal.

Retry 429 and 5xx with exponential backoff and jitter. Prefer the delay we advise, `retry-after-ms` first and then `retry-after`, over an interval of your own. Do not retry 400, 401, 402 or 404, and do not retry anything carrying `x-should-retry: false`: the answer will not change until you do something about it.

Your current limits are on the [Limits](https://console.lithosai.cloud/limits) page. Get in touch to raise them.