## 1. Project Overview & Quickstart (nearai/LICENSE-MIT)

# LICENSE-MIT

Open-source repository nearai/LICENSE-MIT

### Repository Details
- **Repository:** [nearai/LICENSE-MIT](https://github.com/nearai/LICENSE-MIT)
- **Primary Language:** Code

*Note: High-volume repository documentation is actively indexed and synchronized by YakaAI.*

## 2. Official Technical Reference & Guides (nearai/docs)

## File: README.md

---

## About

This repository contains the official documentation for [NEAR AI Cloud](https://cloud.near.ai), a platform offering developers access to secure, private, verifiable AI models through a unified API.

The site is built and hosted with [Mintlify](https://mintlify.com/docs). Content is plain MDX; `docs.json` holds the navigation, branding, and site settings.

The **API Reference** tab is generated by Mintlify from `api-reference/openapi.json`, a vendored copy of the live spec. Refresh it with `./scripts/sync-openapi.py` whenever the API changes.

## Prerequisites

Before you begin, ensure you have the following installed:

- **Node.js** >= 20.0.0 ([Download](https://nodejs.org/))
- **Mintlify CLI**: `npm i mint`

## Quick Start

### Installation

```bash
# Clone the repository
git clone https://github.com/nearai/docs.git
cd docs

# Install the Mintlify CLI (once)
npm i mint
```

### Local Development

```bash
# Start the local preview
mint dev
```

This starts a local preview at `http://localhost:3000`. Changes are reflected live without restarting the server.

### Validate

```bash
# Strict build validation (fails on warnings or errors)
mint validate

# Check for broken internal links
mint broken-links
```

Run both before opening a pull request; CI runs the broken-link check on every PR.

## Available Commands

| Command | Description |
|---------|-------------|
| `mint dev` | Start the local preview with hot reload |
| `mint validate` | Validate the build in strict mode |
| `mint broken-links` | Check for broken links |
| `mint update` | Update the Mintlify CLI |

## Deployment

Mintlify deploys automatically from the `main` branch through the Mintlify GitHub App; every pull request gets a preview deployment. The production domain (`docs.near.ai`) is configured in the [Mintlify dashboard](https://dashboard.mintlify.com).

## Contributing

We welcome contributions to improve our documentation! Here's how you can help:

1. **Fork the repository**
2. **Create a feature branch** (`git checkout -b feature/amazing-improvement`)
3. **Make your changes** and test locally (`mint dev`)
4. **Validate** (`mint validate && mint broken-links`)
5. **Commit your changes** (`git commit -m 'Add amazing improvement'`)
6. **Push to the branch** (`git push origin feature/amazing-improvement`)
7. **Open a Pull Request**

### Documentation Guidelines

- Use clear, concise language
- Include code examples where applicable
- Follow the existing documentation structure
- Test all code snippets before submitting
- Use proper markdown formatting

## Documentation Standards

- **Markdown Files**: Use the `.mdx` extension; a page's URL is its file path (e.g., `cloud/quickstart.mdx` → `/cloud/quickstart`)
- **Navigation**: Add every new page to the `navigation` tree in `docs.json`
- **Code Blocks**: Include language identifiers for syntax highlighting; add a filename after the language for a title (```` ```yaml librechat.yaml ````)
- **Links**: Use absolute paths for internal links (e.g., `/cloud/quickstart`)
- **Images**: Store in `images/` and reference with absolute paths (e.g., `/images/cloud.png`)
- **Components**: Use Mintlify's built-in components (`Card`, `CardGroup`, `Tabs`, `Accordion`, `Note`/`Tip`/`Warning`, …) rather than custom React
- **Integration guides**: Follow the section contract in `.github/INTEGRATION_GUIDE_TEMPLATE.md`

## Bug Reports & Feature Requests

Found a bug or have a feature request? Please [open an issue](https://github.com/nearai/docs/issues) with:

- Clear title and description
- Steps to reproduce (for bugs)
- Expected vs actual behavior
- Screenshots (if applicable)
  
## Links

- **Documentation**: [https://docs.near.ai](https://docs.near.ai)
- **NEAR AI Cloud**: [https://cloud.near.ai](https://cloud.near.ai)
- **GitHub**: [https://github.com/nearai/docs](https://github.com/nearai/docs)
- **Issues**: [https://github.com/nearai/docs/issues](https://github.com/nearai/docs/issues)

## Support

Need help? Reach out through:

- [NEAR AI Telegram Channel](https://t.me/nearaialpha)
- [GitHub Issues](https://github.com/nearai/docs/issues)

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

---

## File: cloud/guides/integrations/aider-zed.mdx

---
title: "Aider and Zed"
---


NEAR AI Cloud exposes an OpenAI-compatible API, so Aider and Zed can use NEAR AI models with a base URL, an API key, and a model ID.

Use the gateway by default:

| Setting | Value |
| --- | --- |
| Base URL | `https://cloud-api.near.ai/v1` |
| Model ID | `z-ai/glm-5.2` |
| API key | A NEAR AI Cloud API key |

Create an API key from the [NEAR AI Cloud Dashboard](https://cloud.near.ai/dashboard/organizations). Do not paste API keys into shared files, docs, issue comments, or screenshots.

## Aider

Aider uses OpenAI-compatible endpoints through the standard OpenAI environment variables. Set them in the shell that starts Aider:

```bash
export OPENAI_API_BASE=https://cloud-api.near.ai/v1
export OPENAI_API_KEY="<your NEAR AI API key>"
```

Then run Aider with the `openai/` model prefix:

```bash
aider --model openai/z-ai/glm-5.2
```

To refresh the model, update the command-line model string. For example, after confirming a new model ID from `/v1/models`, replace `openai/z-ai/glm-5.2` with `openai/<new-model-id>`.

If Aider warns that it does not recognize a new model, first confirm the model works with the curl smoke test below. Aider may need a model metadata update before it can infer limits for a newly released model.

### Optional: set limits and enable reasoning for Aider

Aider does not auto-detect limits or reasoning for an unknown model ID, so it falls back to generic defaults and may print `Warning ...: Unknown context window size and costs, using sane defaults.` These steps are optional — basic chat and tool calls work without them — but they fix the warning and expose GLM 5.2's thinking. Both files key on the exact `--model` string, so use `openai/z-ai/glm-5.2`.

Set the limits in `.aider.model.metadata.json` and pass it with `--model-metadata-file`:

```json .aider.model.metadata.json
{
  "openai/z-ai/glm-5.2": {
    "max_input_tokens": 500000,
    "max_output_tokens": 131072,
    "max_tokens": 131072,
    "litellm_provider": "openai",
    "mode": "chat"
  }
}
```

Allow the reasoning options in `.aider.model.settings.yml` and pass it with `--model-settings-file`:

```yaml .aider.model.settings.yml
- name: openai/z-ai/glm-5.2
  accepts_settings:
    - reasoning_effort
```

`accepts_settings` only allow-lists the reasoning options for this model; it does not turn reasoning on by itself. To actually request reasoning you must also pass `--reasoning-effort` on the launch command, which Aider sends as `extra_body.reasoning_effort` for an `openai/`-prefixed model:

```bash
aider --model openai/z-ai/glm-5.2 \
  --model-metadata-file .aider.model.metadata.json \
  --model-settings-file .aider.model.settings.yml \
  --reasoning-effort high
```

The model name in both files must match the `--model` string exactly, or the entries are ignored.

## Zed

Zed supports custom OpenAI-compatible providers. Add NEAR AI Cloud to Zed from **Agent Settings** with `agent: open settings`, or add the provider to `settings.json` and keep the API key in Zed's provider settings UI, the system keychain, or an environment variable.

Do not store API keys in `settings.json`. For provider id `nearai`, Zed's generated environment variable is:

```bash
export NEARAI_API_KEY="<your NEAR AI API key>"
```

Add this provider config to Zed's `settings.json`:

```json settings.json
{
  "language_models": {
    "openai_compatible": {
      "nearai": {
        "api_url": "https://cloud-api.near.ai/v1",
        "available_models": [
          {
            "name": "z-ai/glm-5.2",
            "display_name": "GLM 5.2",
            "max_tokens": 500000,
            "max_output_tokens": 131072,
            "reasoning_effort": "xhigh"
          }
        ]
      }
    }
  }
}
```

`reasoning_effort` is what makes Zed expose GLM 5.2's thinking: if you omit it, Zed treats the model as non-thinking and shows no thinking toggle or effort variants in the agent panel. GLM 5.2 advertises `reasoning` in `/v1/models`, and it is a Z.AI model, for which Zed's docs recommend `xhigh`. Valid values are `none`, `minimal`, `low`, `medium`, `high`, and `xhigh`. Tool calling does not need a flag here — Zed defaults `openai_compatible` model `capabilities.tools` to `true`.

To refresh models in Zed, add or update entries in `available_models`, then restart Zed or reselect the provider in the model picker. If you used Agent Settings instead of editing JSON, open the NEAR AI provider entry and update the model ID and context window there.

Use `https://cloud-api.near.ai/v1` as the provider API URL. Do not paste the full chat-completions route into Zed's API URL field.

## Curl smoke test

Verify the model is listed:

```bash
curl -fsSL https://cloud-api.near.ai/v1/models \
  | jq -e '.data[] | select(.id == "z-ai/glm-5.2")'
```

Then verify a chat completion:

```bash
curl https://cloud-api.near.ai/v1/chat/completions \
  -H "Authorization: Bearer $NEARAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "z-ai/glm-5.2",
    "messages": [
      {"role": "user", "content": "Reply with only: near-ai-ok"}
    ],
    "max_tokens": 20
  }'
```

If you only set `OPENAI_API_KEY` for Aider, either export `NEARAI_API_KEY="$OPENAI_API_KEY"` before running the curl command or replace `$NEARAI_API_KEY` with `$OPENAI_API_KEY` in the `Authorization` header.

## Troubleshooting

| Symptom | Likely cause | Fix |
| --- | --- | --- |
| model not listed | The client has a stale model list, or the model was not added to the manual provider config. | Run the `/v1/models` curl check, copy the exact model ID, then update Aider's `--model openai/<model-id>` string or Zed's `available_models` entry. |
| `401` | Missing, invalid, expired, or unavailable API key in the process that starts the client. | Generate or copy a NEAR AI Cloud API key, set `OPENAI_API_KEY` for Aider or `NEARAI_API_KEY` for the Zed `nearai` provider, then restart the client. |
| Wrong base URL includes `/chat/completions` | The client expects a base URL, but the full request endpoint was pasted. | Use `https://cloud-api.near.ai/v1` in Aider's `OPENAI_API_BASE` and Zed's `api_url`. The client appends `/chat/completions` itself. |

## Related guides

- [Model Discovery and Refresh](/cloud/guides/integrations/model-discovery)
- [OpenAI Compatibility](/cloud/guides/openai-compatibility)
- [Available Models](/cloud/models)
- [Private Inference - Direct Completions](/cloud/private-inference#direct-completions)
- [Continue](/cloud/guides/integrations/continue)
- [Cline, Roo Code, and Kilo Code](/cloud/guides/integrations/cline-roo-kilo)

## Sources Checked

Sources checked on 2026-06-23:

- [Aider OpenAI compatible APIs](https://aider.chat/docs/llms/openai-compat.html)
- [Aider advanced model settings](https://aider.chat/docs/config/adv-model-settings.html)
- [Zed Use API Access](https://zed.dev/docs/ai/use-api-access)
- [Model Discovery and Refresh](/cloud/guides/integrations/model-discovery)

---

## File: cloud/guides/integrations/cline-roo-kilo.mdx

---
title: "Cline, Roo Code, and Kilo Code"
---


Cline, Roo Code, and Kilo Code can use NEAR AI Cloud through OpenAI-compatible provider settings. They share the same gateway base URL and model IDs, but their model refresh behavior differs.

Use these values unless you have a tool-specific reason to choose a different model:

| Setting | Value |
| --- | --- |
| Base URL | `https://cloud-api.near.ai/v1` |
| API key | A NEAR AI Cloud API key |
| Model ID | `z-ai/glm-5.2` |

## Prerequisites

- A NEAR AI Cloud API key stored in the tool's secret field, keychain, or an environment variable such as `NEARAI_API_KEY`.
- A Cline, Roo Code, or Kilo Code install that supports custom OpenAI-compatible providers.
- The current model ID from [Model Discovery](/cloud/guides/integrations/model-discovery) if you are not using `z-ai/glm-5.2`.

## Base URL

For provider configuration fields, use the gateway base URL:

```text
https://cloud-api.near.ai/v1
```

Do not paste the full chat completions request URL into a base URL field. The tools append the request path themselves.

## Model ID

Use `z-ai/glm-5.2` as the model ID. Copy model IDs exactly as returned by:

```bash
curl https://cloud-api.near.ai/v1/models
```

## Configure Cline

In Cline settings, configure the provider with:

| Field | Value |
| --- | --- |
| API Provider | `OpenAI Compatible` |
| Base URL | `https://cloud-api.near.ai/v1` |
| API Key | Your NEAR AI Cloud API key |
| Model ID | `z-ai/glm-5.2` |

After saving, run a small prompt in Cline. If the model is not listed, enter the model ID manually.

Cline's OpenAI Compatible provider also has a collapsible **Model Configuration** section. It is optional for basic chat, but recommended so Cline budgets context correctly instead of using its generic defaults (context window 128000, max output unset): set **Context Window Size** to `500000` and **Max Output Tokens** to `131072` (from `/v1/models`). To use GLM 5.2's thinking, set the **Reasoning Effort** selector (low/medium/high).

## Configure Roo Code

In Roo Code settings, configure the provider with:

| Field | Value |
| --- | --- |
| API Provider | `OpenAI Compatible` |
| Base URL | `https://cloud-api.near.ai/v1` |
| API Key | Your NEAR AI Cloud API key |
| Model ID | `z-ai/glm-5.2` |

Roo Code requires native OpenAI tool calling. If the selected model or provider path does not support OpenAI-compatible tool calls, Roo Code will fail tool-use workflows even if basic chat requests work. Choose a NEAR AI Cloud model whose `/v1/models` record includes tool support when you need Roo Code's coding-agent tools. GLM 5.2 lists `tools` in `/v1/models`, and Roo forwards the OpenAI `tools` array to OpenAI-compatible endpoints regardless of any per-model flag, so no extra capability toggle is needed for tool use.

Roo Code's OpenAI Compatible provider also exposes custom-model fields under **Model Configuration**. They are optional, but recommended for correct context budgeting: set **Context Window Size** to `500000` and **Max Output Tokens** to `131072` (from `/v1/models`). To use GLM 5.2's thinking, check **Enable Reasoning Effort** and pick a level (low/medium/high/xhigh).

## Configure Kilo Code

Kilo Code supports a custom provider flow. In the Providers tab, add a custom provider with:

| Field | Value |
| --- | --- |
| Provider ID | `nearai` |
| Display name | `NEAR AI Cloud` |
| Provider API | `OpenAI Compatible` |
| Base URL | `https://cloud-api.near.ai/v1` |
| API key | Your NEAR AI Cloud API key |
| Models | Select `z-ai/glm-5.2` if auto-fetched, or add it manually |

When the base URL is valid, Kilo can auto-fetch models from NEAR AI Cloud's OpenAI-compatible `/v1/models` endpoint. If auto-fetch does not show the model, add `z-ai/glm-5.2` manually with display name `GLM 5.2`.

If you use Kilo's config file for a manual model, keep the provider ID and model ID aligned:

```json
{
  "$schema": "https://app.kilo.ai/config.json",
  "model": "nearai/z-ai/glm-5.2",
  "provider": {
    "nearai": {
      "options": {
        "apiKey": "{env:NEARAI_API_KEY}",
        "baseURL": "https://cloud-api.near.ai/v1"
      },
      "models": {
        "z-ai/glm-5.2": {
          "name": "GLM 5.2",
          "tool_call": true,
          "reasoning": true,
          "limit": {
            "context": 500000,
            "output": 131072
          }
        }
      }
    }
  }
}
```

Use fresh limits from `/v1/models` if NEAR AI Cloud changes model metadata.

## Refresh models

When NEAR releases a new model:

1. Run `curl https://cloud-api.near.ai/v1/models` and copy the new `id`.
2. In Cline, paste the ID into the OpenAI Compatible model field if the picker does not show it.
3. In Roo Code, paste the ID into the OpenAI Compatible model field and confirm the model supports native OpenAI tool calling before using agent workflows.
4. In Kilo Code, re-save the `nearai` provider so it auto-fetches from `/v1/models`; if the model is still missing, add the ID manually in the provider's model list or `kilo.jsonc`.

## Quick test

Before debugging tool settings, verify the NEAR AI Cloud gateway and model:

```bash
curl -fsSL https://cloud-api.near.ai/v1/models \
  | jq -e '.data[] | select(.id == "z-ai/glm-5.2")'
```

Then test a chat completion:

```bash
curl https://cloud-api.near.ai/v1/chat/completions \
  -H "Authorization: Bearer $NEARAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "z-ai/glm-5.2",
    "messages": [
      {"role": "user", "content": "Reply with only: near-ai-ok"}
    ],
    "max_tokens": 20
  }'
```

## Troubleshooting

| Symptom | Likely cause | Fix |
| --- | --- | --- |
| `model not listed` | The tool cached an older model list, or the model must be entered manually. | Check `/v1/models`, copy `z-ai/glm-5.2`, then paste it into Cline or Roo manually. For Kilo, re-save the provider to auto-fetch from `/v1/models`, or add the model manually. |
| `401` | Missing, invalid, or expired NEAR AI Cloud API key. | Generate or copy a NEAR AI Cloud API key, store it in the tool's API key field or `NEARAI_API_KEY`, and retry without logging the key. |
| Wrong base URL includes `/chat/completions` | A full request URL was pasted into a base URL field. | Use `https://cloud-api.near.ai/v1` in provider settings. Keep `/chat/completions` only in curl or HTTP request URLs. |
| Roo Code tool calls fail | Roo Code requires native OpenAI tool calling. | Use a NEAR AI Cloud model whose metadata includes tool support, and verify basic chat plus tool-use workflows after saving. |
| Kilo shows the provider but no usable model | Auto-fetch failed or model limits were not set for a manual model. | Re-save the provider, then add `z-ai/glm-5.2` manually if needed. For manual config, set context and output limits from `/v1/models`. |

## Sources Checked

Sources checked on 2026-06-23: Cline OpenAI Compatible provider docs, Roo Code OpenAI Compatible provider docs, Kilo Code OpenAI Compatible provider docs, Kilo Code custom models docs, and NEAR AI Cloud `/v1/models`.

## Related guides

- [Model Discovery and Refresh](/cloud/guides/integrations/model-discovery)
- [OpenAI Compatibility](/cloud/guides/openai-compatibility)
- [Private Inference - Direct Completions](/cloud/private-inference#direct-completions)
- [Available Models](/cloud/models)
- [Continue](/cloud/guides/integrations/continue)
- [Aider and Zed](/cloud/guides/integrations/aider-zed)
- [OpenCode and Goose](/cloud/guides/opencode-goose)

---

## File: cloud/guides/integrations/continue.mdx

---
title: "Continue"
---


Use Continue with NEAR AI Cloud by configuring Continue's OpenAI provider with the NEAR AI Cloud gateway base URL and a NEAR AI model ID.

## Prerequisites

- Continue for VS Code, JetBrains, or the Continue CLI.
- A NEAR AI Cloud API key from the [NEAR AI Cloud Dashboard](https://cloud.near.ai/dashboard/organizations).
- A local Continue `config.yaml`.

Store the API key as a Continue secret instead of committing it to the config file. Continue supports `apiKey: ${{ secrets.NEARAI_API_KEY }}` in `config.yaml`; it resolves secrets from workspace `.env` files, `.continue/.env`, `~/.continue/.env`, or process environment variables for the CLI.

For IDE extensions, prefer a `.env` file because the extension may not read your shell environment. Do not commit `.env` files.

```bash
NEARAI_API_KEY=your-near-ai-api-key
```

## Base URL

Use the NEAR AI Cloud gateway base URL:

```text
https://cloud-api.near.ai/v1
```

Do not append `/chat/completions` to `apiBase`. Continue adds the request path when it calls the OpenAI-compatible API.

## Model ID

Use the NEAR AI Cloud gateway model ID:

```text
z-ai/glm-5.2
```

Check [Model Discovery and Refresh](/cloud/guides/integrations/model-discovery) when you need the freshest model list.

## Configure

Add a model entry like this to Continue's `config.yaml`:

```yaml
name: NEAR AI Cloud
version: 0.0.1
schema: v1

models:
  - name: NEAR AI GLM 5.2
    provider: openai
    model: z-ai/glm-5.2
    apiBase: https://cloud-api.near.ai/v1
    apiKey: ${{ secrets.NEARAI_API_KEY }}
    capabilities:
      - tool_use
    contextLength: 500000
    defaultCompletionOptions:
      maxTokens: 131072
      reasoning: true
```

`capabilities: [tool_use]` is required for Agent mode. Continue only auto-detects native tool calling for a fixed list of model names (GPT, o-series, and a few others); for a custom model ID like `z-ai/glm-5.2` it defaults to no tool support, so you must set `tool_use` explicitly or Agent mode falls back to a degraded prompt-based tool path instead of native function calling. GLM 5.2 advertises `tools` in `/v1/models`, so this is accurate, not aspirational.

The remaining fields are optional metadata that match the live `/v1/models` record. `contextLength: 500000` and `maxTokens: 131072` set the context and output budgets. `defaultCompletionOptions.reasoning: true` tells Continue to display and parse the model's thinking output — with `provider: openai` it is not added to the request, so it does not turn reasoning on. GLM 5.2 emits reasoning by default server-side, and this flag surfaces it in Continue's thinking pane. Basic chat works without these fields.

Reload Continue after saving the config. In VS Code, use the command palette and run `Developer: Reload Window` if the model list does not update.

## Refresh models

Continue uses the model IDs in your `config.yaml`; it does not need to discover this model from a provider catalog. When NEAR AI Cloud releases a new model:

1. Run `curl https://cloud-api.near.ai/v1/models`.
2. Copy the new model's `id`.
3. Replace or add the `model:` value in `config.yaml`.
4. Reload Continue or restart the IDE if the model picker is stale.

Use the exact model ID from `/v1/models`. Do not invent aliases unless NEAR AI Cloud lists them.

## Quick test

Before debugging Continue, verify the same key, base URL, and model with curl:

```bash
curl https://cloud-api.near.ai/v1/chat/completions \
  -H "Authorization: Bearer $NEARAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "z-ai/glm-5.2",
    "messages": [
      {
        "role": "user",
        "content": "Reply with only: near-ai-ok"
      }
    ],
    "max_tokens": 20
  }'
```

If curl fails, fix the NEAR AI Cloud key, model ID, or network path before changing Continue settings.

## Troubleshooting

| Symptom | Likely cause | Fix |
| --- | --- | --- |
| model not listed | Continue has not loaded the new `config.yaml`, the model picker is stale, or the model entry was not added to `models`. | Confirm the YAML contains `model: z-ai/glm-5.2`, save the file, then reload the IDE or restart Continue. |
| `401` | The secret is missing, invalid, or not visible to the Continue process. | Put `NEARAI_API_KEY=...` in a workspace `.env`, workspace `.continue/.env`, or `~/.continue/.env`, then restart the IDE. For the CLI, export the variable before running `cn`. |
| Wrong base URL includes `/chat/completions` | The full curl request URL was pasted into `apiBase`. | Set `apiBase: https://cloud-api.near.ai/v1`. Use `/chat/completions` only in full request URLs such as the curl smoke test. |
| Continue calls `/responses` and the request fails | Some OpenAI model families can make Continue use Responses features that require provider-side storage or built-in tools. NEAR AI Cloud supports only [stateless Responses](/cloud/guides/stateless-responses). | Add `useResponsesApi: false` to the affected model entry only if logs show Continue is calling `/responses`; keep it out of the default config. |

Example targeted fallback:

```yaml
models:
  - name: NEAR AI GLM 5.2
    provider: openai
    model: z-ai/glm-5.2
    apiBase: https://cloud-api.near.ai/v1
    apiKey: ${{ secrets.NEARAI_API_KEY }}
    capabilities:
      - tool_use
    useResponsesApi: false
```

## Related guides

- [Model Discovery and Refresh](/cloud/guides/integrations/model-discovery)
- [OpenAI Compatibility](/cloud/guides/openai-compatibility)
- [Available Models](/cloud/models)
- [Private Inference - Direct Completions](/cloud/private-inference#direct-completions)
- [Cline, Roo Code, and Kilo Code](/cloud/guides/integrations/cline-roo-kilo)
- [Aider and Zed](/cloud/guides/integrations/aider-zed)

## Sources Checked

Sources checked on 2026-06-23:

- [Continue OpenAI provider](https://docs.continue.dev/customize/model-providers/top-level/openai)
- [Continue model capabilities and `tool_use`](https://docs.continue.dev/reference)
- [Continue FAQ: secrets](https://docs.continue.dev/faqs)
- [Continue CLI configuration](https://docs.continue.dev/cli/configuration)

---

## File: cloud/guides/integrations/cursor.mdx

---
title: "Cursor"
---


<Warning>
  **Limited support**

  Cursor can accept an OpenAI API key and an overridden OpenAI-compatible base URL, but public Cursor reports show limits around custom endpoint routing. Treat this as a chat or plan-style setup, and verify in your Cursor install before relying on it for daily work.
</Warning>
These steps use public Cursor API key and base URL behavior checked on 2026-06-23. Composer, Agent, autocomplete, and inline edit routing are not documented as verified for NEAR AI Cloud, so do not assume those features use NEAR just because the OpenAI base URL is overridden.

## Overview

Use this guide when you want to try NEAR AI Cloud from Cursor's OpenAI-compatible settings. The intended settings are:

| Setting | Value |
| --- | --- |
| Base URL | `https://cloud-api.near.ai/v1` |
| Model ID | `z-ai/glm-5.2` |
| API key | A NEAR AI Cloud API key |

Keep the OpenAI API key toggle enabled while testing NEAR AI Cloud. If you turn it off, Cursor may stop sending requests with your custom key.

## Prerequisites

- Cursor installed.
- A NEAR AI Cloud API key from the [NEAR AI Cloud Dashboard](https://cloud.near.ai/dashboard/organizations).
- A text-only prompt you can use to test Chat or Plan mode.

Do not paste a real API key into shared screenshots, issue reports, or checked-in files.

## Base URL

Use the gateway base URL:

```text
https://cloud-api.near.ai/v1
```

Do not use the full chat completions endpoint as the Cursor base URL. Cursor adds paths such as `/chat/completions` itself, so a base URL ending in `/chat/completions` can become a doubled path.

## Model ID

Use the exact model ID from NEAR AI Cloud:

```text
z-ai/glm-5.2
```

Do not invent neutral aliases unless NEAR accepts them. For example, do not rename the model to `glm-5.2`, `nearai-glm`, or another convenience alias unless that exact ID appears in the NEAR model list or in the specific endpoint you are using.

For the current model list, see [Model Discovery and Refresh](/cloud/guides/integrations/model-discovery).

## Configure

In Cursor, follow this path:

```text
Settings -> Models -> Add OpenAI API Key -> Override OpenAI Base URL -> https://cloud-api.near.ai/v1 -> add model z-ai/glm-5.2
```

Recommended setup:

1. Open **Settings**.
2. Go to **Models**.
3. Choose **Add OpenAI API Key**.
4. Paste your NEAR AI Cloud API key into Cursor's OpenAI API key field.
5. Keep the OpenAI API key toggle enabled.
6. Enable **Override OpenAI Base URL**.
7. Enter `https://cloud-api.near.ai/v1`.
8. Add a custom model with the exact ID `z-ai/glm-5.2`.
9. Select `z-ai/glm-5.2` in the Chat or Plan model picker and send a small text-only prompt.

Important caveats:

- The custom base URL may affect Cursor-provided models while the override is enabled.
- Only chat/plan-style calls may work through the override.
- Composer, Agent, autocomplete, and inline edit routing is not documented as verified for NEAR AI Cloud.
- If you need Cursor-provided models again, you may need to disable the OpenAI API key toggle or the base URL override, then reselect the Cursor model.

## Refresh models

Cursor may not automatically discover every model from `GET /v1/models`. When NEAR AI Cloud releases a new model:

1. Check the live model list:

   ```bash
   curl -fsSL https://cloud-api.near.ai/v1/models \
     | jq '.data[] | select(.id == "z-ai/glm-5.2")'
   ```

2. Copy the exact `id` value.
3. Add or update that model ID in Cursor's Models settings.
4. Re-select the model in the Chat or Plan model picker.
5. Restart Cursor if the picker keeps showing an old model list.

## Quick test

First verify NEAR AI Cloud directly, before debugging Cursor:

```bash
curl https://cloud-api.near.ai/v1/chat/completions \
  -H "Authorization: Bearer $NEARAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "z-ai/glm-5.2",
    "messages": [
      {"role": "user", "content": "Reply with only: near-ai-ok"}
    ],
    "max_tokens": 20
  }'
```

If curl works, test Cursor with a plain text Chat or Plan prompt. If Cursor fails while curl succeeds, treat it as a Cursor custom-endpoint issue and verify the current behavior in your Cursor install.

## Troubleshooting

| Symptom | Likely cause | Fix |
| --- | --- | --- |
| `z-ai/glm-5.2` or another model not listed | Cursor has a stale model picker or does not auto-fetch NEAR's model list. | Confirm the model with `curl https://cloud-api.near.ai/v1/models`, then add the exact model ID manually in Cursor's Models settings. Restart Cursor if the picker does not update. |
| `401` | Cursor is not sending a valid NEAR AI Cloud API key, the OpenAI API key toggle is off, or the key is invalid. | Re-enter the NEAR AI Cloud API key, keep the OpenAI API key toggle enabled, and retry the curl smoke test without logging the key. |
| Wrong base URL `/chat/completions` | The full request endpoint was pasted into Cursor's base URL field. | Use `https://cloud-api.near.ai/v1` as the base URL. Do not append `/chat/completions`; Cursor adds request paths itself. |
| Cursor-provided models fail after enabling the override | Cursor's custom OpenAI base URL can affect models beyond the one you added. | Disable the OpenAI API key toggle or base URL override when switching back to Cursor-provided models, then reselect the Cursor model. |
| Composer, Agent, autocomplete, or inline edit does not use NEAR AI Cloud | Those routes are not documented as verified for NEAR AI Cloud through Cursor's custom OpenAI endpoint. | Use Cursor Chat or Plan for this limited setup, or use another NEAR AI Cloud integration for full coding-agent routing. |

## Related guides

- [Model Discovery and Refresh](/cloud/guides/integrations/model-discovery)
- [OpenAI Compatibility](/cloud/guides/openai-compatibility)
- [Private Inference - Direct Completions](/cloud/private-inference#direct-completions)
- [Available Models](/cloud/models)
- [Continue](/cloud/guides/integrations/continue)
- [Cline, Roo Code, and Kilo Code](/cloud/guides/integrations/cline-roo-kilo)

## Sources Checked

Sources checked on 2026-06-23:

- [Cursor API keys](https://cursor.com/help/models-and-usage/api-keys)
- [LLM Gateway Cursor guide](https://docs.llmgateway.io/guides/cursor)
- Public Cursor forum reports about custom OpenAI base URL and Composer/custom key behavior

---

## File: cloud/guides/integrations/dify.mdx

---
title: "Dify"
---


Dify can use NEAR AI Cloud through the OpenAI-API-compatible model provider plugin. Configure it as a custom provider, then add each NEAR AI Cloud model you want Dify apps to use.

## Prerequisites

- A Dify workspace where you are an owner or admin.
- The Dify OpenAI-API-compatible model provider plugin installed or available from the marketplace.
- A NEAR AI Cloud API key from the [NEAR AI Cloud Dashboard](https://cloud.near.ai/dashboard/organizations).

Use these NEAR AI Cloud values unless you are intentionally testing a different model:

| Setting | Value |
| --- | --- |
| Base URL | `https://cloud-api.near.ai/v1` |
| Model ID | `z-ai/glm-5.2` |
| Context length | `500000` |
| Output limit | `131072` |

The context and output limits above come from the live NEAR AI Cloud `/v1/models` metadata for `z-ai/glm-5.2`.

## Install or Select the Plugin

In Dify, open **Settings** -> **Model Providers**.

If **OpenAI-API-compatible** is not already listed, install it from the Dify marketplace. After installation, select **OpenAI-API-compatible** from the model provider list.

## Add the NEAR AI Cloud Model

Add a custom model with these values:

| Dify field | Value |
| --- | --- |
| Type | `LLM` |
| Name | `z-ai/glm-5.2` |
| API Key | Your NEAR AI Cloud API key |
| URL | `https://cloud-api.near.ai/v1` |
| Context size | `500000` |
| Maximum output tokens | `131072` |
| Function Call Type | `Tool Call` |
| Thinking Mode Support | `Both Modes` |
| Compatibility mode | `Enable extra settings` |
| Structured Output | `Support` |

Keep the model name exactly as NEAR AI Cloud returns it. Do not rename it to `glm-5.2`, `GLM-5.2-FP8`, or an OpenAI model name unless `/v1/models` lists that exact ID for the gateway.

The four capability fields below the limits default to "off" in the OpenAI-API-compatible plugin, so they must be set explicitly for GLM 5.2 (which advertises `tools`, `structured_outputs`, `reasoning`, and `json_mode` in `/v1/models`):

- **Function Call Type** defaults to `Not Support` (`no_call`). With the default, the plugin does not send the OpenAI `tools` array to NEAR AI Cloud and marks the model non-tool-capable in agent apps. Set it to `Tool Call` to enable tool/agent use.
- **Thinking Mode Support** defaults to `Only Non-Thinking Mode` (`not_supported`), which disables thinking and strips reasoning content from responses. Set it to `Both Modes` to expose the thinking toggle and the `reasoning_effort` parameter.
- **Compatibility mode** defaults to strict. Set it to `Enable extra settings` so the thinking toggle is actually transmitted to the backend; in strict mode the `enable_thinking` parameter is not sent.
- **Structured Output** defaults to `Not Support`. Set it to `Support` to expose the Response Format parameter (`text` / `json_object` / `json_schema`).

After entering the fields, use Dify's provider test action. Save the model only after the test succeeds.

## Refresh models

Dify custom providers do not necessarily receive the same automatic model updates that Dify system providers receive. Treat the OpenAI-API-compatible NEAR AI Cloud entry as a manual model list.

When NEAR AI Cloud releases a new model:

1. Fetch the live model metadata:

   ```bash
   curl -fsSL https://cloud-api.near.ai/v1/models \
     | jq '.data[] | {id, context_length, max_output_length, top_provider}'
   ```

2. Copy the new model's exact `id`.
3. In Dify, open **Settings** -> **Model Providers** -> **OpenAI-API-compatible**.
4. Add a new custom model with the copied `id`, the same URL, and the context/output limits from the live metadata.
5. Test and save the new model.

For GLM 5.2, the targeted metadata check is:

```bash
curl -fsSL https://cloud-api.near.ai/v1/models \
  | jq '.data[] | select(.id == "z-ai/glm-5.2") | {
      id,
      context_length,
      max_output_length,
      top_provider
    }'
```

## Curl smoke test

Before debugging Dify settings, verify the model appears in NEAR AI Cloud's OpenAI-compatible model list:

```bash
curl -fsSL https://cloud-api.near.ai/v1/models \
  | jq -e '.data[] | select(.id == "z-ai/glm-5.2")'
```

Then test the same base URL, API key, and model with chat completions:

```bash
curl https://cloud-api.near.ai/v1/chat/completions \
  -H "Authorization: Bearer $NEARAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "z-ai/glm-5.2",
    "messages": [
      {"role": "user", "content": "Reply with only: near-ai-ok"}
    ],
    "max_tokens": 20
  }'
```

If curl fails, fix the NEAR AI Cloud key, model ID, or base URL before changing Dify settings.

## Troubleshooting

| Symptom | Likely cause | Fix |
| --- | --- | --- |
| `model not listed` | The model was not added to Dify's OpenAI-API-compatible custom provider, or Dify is showing an older provider configuration. | Check `https://cloud-api.near.ai/v1/models`, copy `z-ai/glm-5.2`, add it as a custom model, then test and save the provider again. |
| `401` | The NEAR AI Cloud API key is missing, invalid, expired, or pasted into the wrong provider. | Replace the key in the OpenAI-API-compatible provider entry. Do not log or share the key while testing. |
| Wrong base URL includes `/chat/completions` | The full request endpoint was pasted into Dify's URL field. | Set the Dify URL field to `https://cloud-api.near.ai/v1`. Dify adds `/chat/completions` when it sends chat requests. |
| Test fails after adding a new model | The model ID or limits were copied from stale notes instead of live NEAR AI Cloud metadata. | Re-run the `/v1/models` command, copy the exact `id`, `context_length`, and `max_output_length`, then update the Dify custom model. |
| Tools/agent use or thinking does not work | The capability fields were left at their defaults (Function Call Type `Not Support`, Thinking Mode Support `Only Non-Thinking Mode`). | Edit the custom model and set Function Call Type = `Tool Call`, Thinking Mode Support = `Both Modes`, and Compatibility mode = `Enable extra settings`, then re-test and save. |

## Related guides

- [Model Discovery and Refresh](/cloud/guides/integrations/model-discovery)
- [OpenAI Compatibility](/cloud/guides/openai-compatibility)
- [Available Models](/cloud/models)
- [Private Inference - Direct Completions](/cloud/private-inference#direct-completions)
- [Open WebUI](/cloud/guides/integrations/open-webui)
- [LibreChat](/cloud/guides/integrations/librechat)

## Sources Checked

Sources checked on 2026-06-23:

- [Dify model providers](https://docs.dify.ai/en/use-dify/workspace/model-providers)
- [Dify OpenAI-API-compatible plugin](https://marketplace.dify.ai/plugin/langgenius/openai_api_compatible)
- [Dify OpenAI-API-compatible provider schema (`function_calling_type`, `agent_thought_support`, `structured_output_support`)](https://github.com/langgenius/dify-official-plugins/blob/main/models/openai_api_compatible/provider/openai_api_compatible.yaml)
- [Model Discovery and Refresh](/cloud/guides/integrations/model-discovery)

---

## File: cloud/guides/integrations/index.mdx

---
title: "Integrations"
sidebarTitle: "Overview"
---


Use these guides to connect third-party software to NEAR AI Cloud through its OpenAI-compatible API.

Most clients need the same values:

| Setting | Value |
| --- | --- |
| Base URL | `https://cloud-api.near.ai/v1` |
| API key | A NEAR AI Cloud API key |
| Model ID | A model available from NEAR AI Cloud |

## Software Covered

Use the OpenAI client guide when you are configuring code directly. Use the integration guides when a tool has its own provider settings, model picker, or model refresh behavior.

### Coding agents and IDEs

- [Cursor](/cloud/guides/integrations/cursor)
- [Continue](/cloud/guides/integrations/continue)
- [Cline, Roo Code, and Kilo Code](/cloud/guides/integrations/cline-roo-kilo)
- [Aider and Zed](/cloud/guides/integrations/aider-zed)
- [OpenCode and Goose](/cloud/guides/opencode-goose)

### Self-hosted and team apps

- [LibreChat](/cloud/guides/integrations/librechat)
- [Open WebUI](/cloud/guides/integrations/open-webui)
- [LiteLLM](/cloud/guides/integrations/litellm)
- [Dify](/cloud/guides/integrations/dify)

## Model Discovery

NEAR AI Cloud can add new models over time. Use the [Model Discovery guide](/cloud/guides/integrations/model-discovery) to check the current model list, choose between gateway and direct completions endpoints, and copy the right model ID into clients that do not refresh automatically.

```bash
curl https://cloud-api.near.ai/v1/models
```

## Related guides

- [OpenAI Client](/cloud/guides/openai-compatibility)
- [Model Discovery](/cloud/guides/integrations/model-discovery)
- [Available Models](/cloud/models)

---

## File: cloud/guides/integrations/librechat.mdx

---
title: "LibreChat"
---


LibreChat can use NEAR AI Cloud through a custom OpenAI-compatible endpoint in `librechat.yaml`. Keep the endpoint name unique, store the API key in `.env`, and mount the config file when running LibreChat with Docker.

## Prerequisites

- A running LibreChat installation.
- A NEAR AI Cloud API key from the [NEAR AI Cloud Dashboard](https://cloud.near.ai/dashboard/organizations).
- Access to the LibreChat project directory that contains `.env` and `docker-compose.yml`.

Do not put a real API key in `librechat.yaml`. Reference an environment variable from `.env` instead.

## Base URL

Use the NEAR AI Cloud gateway base URL:

```text
https://cloud-api.near.ai/v1
```

Do not append `/chat/completions` to `baseURL`. LibreChat appends the chat-completions path when it calls the OpenAI-compatible API.

## Model ID

Use the NEAR AI Cloud gateway model ID:

```text
z-ai/glm-5.2
```

Check [Model Discovery and Refresh](/cloud/guides/integrations/model-discovery) before adding newer model IDs.

## Configure

Create or edit `librechat.yaml` in the LibreChat project root:

```yaml librechat.yaml
version: 1.3.13
cache: true

endpoints:
  custom:
    - name: 'nearai'
      apiKey: '${NEARAI_API_KEY}'
      baseURL: 'https://cloud-api.near.ai/v1'
      models:
        default:
          - 'z-ai/glm-5.2'
      titleConvo: true
      titleModel: 'z-ai/glm-5.2'
      modelDisplayLabel: 'NEAR AI Cloud'
```

The custom endpoint name `nearai` is intentionally not a built-in LibreChat endpoint name. Do not add a `provider` field for NEAR AI Cloud; LibreChat uses the OpenAI-compatible custom endpoint path when that field is omitted.

Add the key to `.env` in the same project root:

```bash .env
NEARAI_API_KEY=your-near-ai-api-key
```

For Docker deployments, mount `librechat.yaml` into the API container. If you do not already have an override file, copy LibreChat's example:

```bash
cp docker-compose.override.yml.example docker-compose.override.yml
```

Then make sure the override includes this mount:

```yaml docker-compose.override.yml
services:
  api:
    volumes:
      - type: bind
        source: ./librechat.yaml
        target: /app/librechat.yaml
```

Restart LibreChat after changing `librechat.yaml`, `.env`, or the Docker mount:

```bash
docker compose down
docker compose up -d
```

For non-Docker local installs, place `librechat.yaml` in the project root next to `.env`, then restart the LibreChat backend process.

## Refresh models

The primary refresh path is manual because this guide keeps a short, explicit model list:

1. Run `curl https://cloud-api.near.ai/v1/models`.
2. Copy the new model's exact `id`.
3. Add it under `models.default` in `librechat.yaml`.
4. Restart LibreChat so the endpoint selector reads the updated config.

LibreChat's custom endpoint reference also documents `models.fetch: true` for OpenAI-compatible custom endpoints. If you want LibreChat to try `GET /v1/models`, add `fetch: true` under `models` after you confirm the curl check works in your environment:

```yaml
models:
  default:
    - 'z-ai/glm-5.2'
  fetch: true
```

Keep `models.default` populated even when using fetch. LibreChat uses the default list as the fallback if fetching is slow or fails.

## Quick test

Before debugging LibreChat, verify the same key, base URL, and model with curl:

```bash
curl https://cloud-api.near.ai/v1/chat/completions \
  -H "Authorization: Bearer $NEARAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "z-ai/glm-5.2",
    "messages": [
      {"role": "user", "content": "Reply with only: near-ai-ok"}
    ],
    "max_tokens": 20
  }'
```

If curl fails, fix the NEAR AI Cloud key, model ID, or network path before changing LibreChat settings.

## Troubleshooting

| Symptom | Likely cause | Fix |
| --- | --- | --- |
| model not listed | `librechat.yaml` was not mounted, LibreChat was not restarted, or `z-ai/glm-5.2` is missing from `models.default`. | Confirm the Docker mount points to `/app/librechat.yaml`, run `docker compose logs api` for config errors, add the exact model ID under `models.default`, and restart LibreChat. |
| `401` | `NEARAI_API_KEY` is missing from `.env`, the API container did not reload the environment, or the key is invalid. | Add `NEARAI_API_KEY=...` to `.env`, restart LibreChat, and rerun the curl smoke test without logging the key. |
| Wrong base URL includes `/chat/completions` | The full curl request URL was pasted into `baseURL`. | Set `baseURL: 'https://cloud-api.near.ai/v1'`. Use `/chat/completions` only in full request URLs such as the curl smoke test. |
| Endpoint not visible | The custom endpoint name conflicts with a built-in endpoint, YAML parsing failed, or the config file is in the wrong directory. | Keep `name: 'nearai'`, validate the YAML, make sure the file is in the LibreChat project root, and check `docker compose logs api`. |
| New NEAR AI model does not appear after release | LibreChat is reading the old manual list or cached endpoint config. | Recheck `/v1/models`, add the model ID under `models.default`, and restart LibreChat. If using `fetch: true`, keep the default fallback list and restart after changing fetch settings. |

## Related guides

- [Model Discovery and Refresh](/cloud/guides/integrations/model-discovery)
- [OpenAI Compatibility](/cloud/guides/openai-compatibility)
- [Available Models](/cloud/models)
- [Private Inference - Direct Completions](/cloud/private-inference#direct-completions)
- [Open WebUI](/cloud/guides/integrations/open-webui)
- [Dify](/cloud/guides/integrations/dify)
- [LiteLLM Proxy](/cloud/guides/integrations/litellm)

## Sources Checked

Sources checked on 2026-06-23:

- [LibreChat Custom Endpoints](https://www.librechat.ai/docs/quick_start/custom_endpoints)
- [LibreChat Custom Config](https://www.librechat.ai/docs/configuration/librechat_yaml)
- [LibreChat Custom Endpoint Object Structure](https://www.librechat.ai/docs/configuration/librechat_yaml/object_structure/custom_endpoint)
- [Model Discovery and Refresh](/cloud/guides/integrations/model-discovery)

---

## File: cloud/guides/integrations/litellm.mdx

---
title: "LiteLLM Proxy"
sidebarTitle: "LiteLLM"
---


Use LiteLLM with NEAR AI Cloud by routing LiteLLM's OpenAI-compatible provider to the NEAR AI Cloud gateway.

## Prerequisites

- LiteLLM Python SDK or LiteLLM Proxy.
- A NEAR AI Cloud API key from the [NEAR AI Cloud Dashboard](https://cloud.near.ai/dashboard/organizations).
- `NEARAI_API_KEY` exported in the shell or injected into the proxy container.

Keep the NEAR AI Cloud API key in an environment variable. Do not paste a real key into checked-in Python files or `config.yaml`.

```bash
export NEARAI_API_KEY="your-near-ai-api-key"
```

## Base URL

Use the NEAR AI Cloud gateway base URL:

```text
https://cloud-api.near.ai/v1
```

Do not append `/chat/completions` to `api_base`. LiteLLM and the OpenAI client add the request path when they make chat completion calls.

## Model ID

Use LiteLLM's OpenAI-compatible prefix for the upstream model:

```text
openai/z-ai/glm-5.2
```

The `openai/` prefix tells LiteLLM to send the request through OpenAI-compatible chat completions. The NEAR AI Cloud model ID after the prefix is `z-ai/glm-5.2`.

Check [Model Discovery and Refresh](/cloud/guides/integrations/model-discovery) when you need the freshest NEAR AI Cloud model list.

## Configure

### Python SDK

Call NEAR AI Cloud directly from the LiteLLM Python SDK:

```python
import os

import litellm

response = litellm.completion(
    model="openai/z-ai/glm-5.2",
    api_base="https://cloud-api.near.ai/v1",
    api_key=os.environ["NEARAI_API_KEY"],
    messages=[
        {
            "role": "user",
            "content": "Reply with only: near-ai-ok",
        }
    ],
    max_tokens=20,
)

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

### Proxy `config.yaml`

Expose NEAR AI Cloud through LiteLLM Proxy with a local model alias:

```yaml
model_list:
  - model_name: nearai-glm-5.2
    litellm_params:
      model: openai/z-ai/glm-5.2
      api_base: https://cloud-api.near.ai/v1
      api_key: os.environ/NEARAI_API_KEY

general_settings:
  master_key: os.environ/LITELLM_MASTER_KEY
```

Start the proxy with the config:

```bash
export NEARAI_API_KEY="your-near-ai-api-key"
export LITELLM_MASTER_KEY="sk-your-litellm-proxy-key"
litellm --config ./config.yaml
```

Clients that call your proxy use the proxy alias:

```bash
curl http://127.0.0.1:4000/chat/completions \
  -H "Authorization: Bearer $LITELLM_MASTER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "nearai-glm-5.2",
    "messages": [
      {
        "role": "user",
        "content": "Reply with only: near-ai-ok"
      }
    ],
    "max_tokens": 20
  }'
```

### Optional: report capabilities and limits

LiteLLM passes tool calls and reasoning through the `openai/` path regardless of metadata, so the config above is enough to use GLM 5.2. If you want LiteLLM's introspection endpoints (`/v1/models`, `/v1/model/info`, `/model_group/info`) to report GLM 5.2's real capabilities — instead of defaulting to `false`/`null` because `z-ai/glm-5.2` is not in LiteLLM's built-in model map — add a sibling `model_info` block:

```yaml
model_list:
  - model_name: nearai-glm-5.2
    litellm_params:
      model: openai/z-ai/glm-5.2
      api_base: https://cloud-api.near.ai/v1
      api_key: os.environ/NEARAI_API_KEY
    model_info:
      supports_function_calling: true
      supports_reasoning: true
      supports_vision: false
      max_input_tokens: 500000
      max_output_tokens: 131072
```

The values match the live `/v1/models` record for `z-ai/glm-5.2` (tools and reasoning supported, text-only, context 500000, output 131072). This block is reporting metadata only; it does not change request behavior.

## Refresh models

LiteLLM Proxy uses the entries in `model_list`; it does not automatically add every NEAR AI Cloud model to your config. When NEAR AI Cloud releases a new model:

1. Run `curl https://cloud-api.near.ai/v1/models`.
2. Copy the new model's `id`.
3. Add or update a `model_list` entry.
4. Set `litellm_params.model` to `openai/<model-id>`.
5. Restart or reload LiteLLM Proxy so the new alias appears.

You can generate starter entries from `/v1/models` and then review them before using the config:

```bash
curl -fsSL https://cloud-api.near.ai/v1/models \
  | jq -r '.data[].id | "- model_name: nearai-" + gsub("[^A-Za-z0-9._-]"; "-") + "\n  litellm_params:\n    model: openai/" + . + "\n    api_base: https://cloud-api.near.ai/v1\n    api_key: os.environ/NEARAI_API_KEY"'
```

Review generated aliases for readability and remove models you do not want to expose through your proxy.

## Quick test

Before debugging LiteLLM, verify the same key, base URL, and NEAR AI Cloud model with curl:

```bash
curl https://cloud-api.near.ai/v1/chat/completions \
  -H "Authorization: Bearer $NEARAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "z-ai/glm-5.2",
    "messages": [
      {
        "role": "user",
        "content": "Reply with only: near-ai-ok"
      }
    ],
    "max_tokens": 20
  }'
```

If curl fails, fix the NEAR AI Cloud key, model ID, or network path before changing LiteLLM settings.

## Troubleshooting

| Symptom | Likely cause | Fix |
| --- | --- | --- |
| model not listed in LiteLLM Proxy | The proxy only exposes `model_list` aliases, or the config was not reloaded after adding the model. | Add a `model_list` entry with a readable `model_name`, set `litellm_params.model` to `openai/z-ai/glm-5.2`, then restart or reload the proxy. |
| `401` | `NEARAI_API_KEY` is missing, invalid, or not visible to the Python process or proxy container. | Export `NEARAI_API_KEY` in the same shell that runs Python or pass it into the proxy container. Keep `api_key: os.environ/NEARAI_API_KEY` in the proxy config. |
| Wrong base URL includes `/chat/completions` | The full curl URL was pasted into `api_base`. | Set `api_base: https://cloud-api.near.ai/v1`. Use `/chat/completions` only in full request URLs such as curl smoke tests or requests sent to the proxy. |
| LiteLLM returns a routing or provider error | The LiteLLM upstream model value is missing the OpenAI-compatible provider prefix. | Use `openai/z-ai/glm-5.2` in the SDK and in `litellm_params.model`. Proxy callers can use your local alias, such as `nearai-glm-5.2`. |

## Related guides

- [Model Discovery and Refresh](/cloud/guides/integrations/model-discovery)
- [OpenAI Compatibility](/cloud/guides/openai-compatibility)
- [Available Models](/cloud/models)
- [Private Inference - Direct Completions](/cloud/private-inference#direct-completions)
- [LibreChat](/cloud/guides/integrations/librechat)
- [Open WebUI](/cloud/guides/integrations/open-webui)

## Sources Checked

Sources checked on 2026-06-23:

- [LiteLLM OpenAI-compatible endpoints](https://docs.litellm.ai/docs/providers/openai_compatible)
- [LiteLLM proxy config](https://docs.litellm.ai/docs/proxy/configs)
- [LiteLLM API key/base configuration](https://docs.litellm.ai/docs/set_keys)

---

## File: cloud/guides/integrations/model-discovery.mdx

---
title: "Model Discovery and Refresh"
sidebarTitle: "Model Discovery"
---


Use this guide when a client does not show a newly released NEAR AI Cloud model, or when you need to decide between the gateway model ID and a direct completions endpoint.

Most tools should use:

| Setting | Value |
| --- | --- |
| Base URL | `https://cloud-api.near.ai/v1` |
| Model ID | `z-ai/glm-5.2` |
| API key | A NEAR AI Cloud API key |

Do not copy a full static model catalog into your tool config. Check the live APIs, then copy only the model IDs your client needs.

## Discover gateway models

The gateway model list is available from:

```bash
curl https://cloud-api.near.ai/v1/models
```

To find the GLM 5.2 entry:

```bash
curl -fsSL https://cloud-api.near.ai/v1/models \
  | jq '.data[] | select(.id == "z-ai/glm-5.2")'
```

The response uses OpenAI-style model objects plus NEAR AI Cloud metadata. Important field names include:

| Field | Meaning |
| --- | --- |
| `id` | The model ID to use with the gateway. For GLM 5.2, use `z-ai/glm-5.2`. |
| `name` | Human-readable display name. |
| `context_length` | Maximum input context length reported for the model. |
| `max_output_length` | Maximum output length reported by NEAR AI Cloud. |
| `top_provider.context_length` | Provider context length used by clients that read OpenRouter-style metadata. |
| `top_provider.max_completion_tokens` | Provider maximum completion tokens used by clients that read OpenRouter-style metadata. |
| `supported_features` | Feature flags such as `tools`, `structured_outputs`, `reasoning`, and `json_mode`. |
| `supported_sampling_parameters` | Supported request parameters such as `temperature`, `top_p`, `max_tokens`, and `stop`. |
| `input_modalities` and `output_modalities` | Supported input and output types. |

As checked on 2026-06-23, the live GLM 5.2 gateway record reports `top_provider.context_length: 500000`, `top_provider.max_completion_tokens: 131072`, and `max_output_length: 131072`.

## Discover direct completions endpoints

Direct completions endpoints are listed at:

```bash
curl https://completions.near.ai/endpoints
```

To find the GLM 5.2 direct completions endpoint:

```bash
curl -fsSL https://completions.near.ai/endpoints \
  | jq '.endpoints[] | select(.domain == "glm-5-2.completions.near.ai")'
```

As checked on 2026-06-23, that endpoint is:

```text
https://glm-5-2.completions.near.ai/v1
```

The endpoints registry (`GET https://completions.near.ai/endpoints`) lists both `z-ai/glm-5.2` and `zai-org/GLM-5.2-FP8` for this domain, but the endpoint's own `GET https://glm-5-2.completions.near.ai/v1/models` currently returns only `z-ai/glm-5.2`. Use `z-ai/glm-5.2`. The `zai-org/GLM-5.2-FP8` served name still resolves at the direct endpoint, but treat it as a fallback only when your client needs that exact served model name.

## Gateway vs direct completions

Use the gateway by default:

```text
https://cloud-api.near.ai/v1
```

The gateway is the best fit for most third-party clients because one base URL can reach the full NEAR AI Cloud model catalog, and clients that auto-fetch models can use `GET /v1/models`.

Use direct completions only when you intentionally want one model's TEE endpoint:

```text
https://glm-5-2.completions.near.ai/v1
```

Direct completions can reduce routing hops and exposes the model-specific route set described in [Private Inference - Direct Completions](/cloud/private-inference#direct-completions). It is not a replacement for the gateway model catalog in clients that expect one provider to list every model.

## Why client model lists go stale

Client model lists can become stale for three common reasons:

1. The client cached `GET /v1/models` and has not refreshed the provider connection.
2. The client uses a separate catalog, such as models.dev, instead of reading NEAR AI Cloud live.
3. The client requires a manual model list in a settings file, environment variable, or admin UI.

When NEAR releases a new model, check `https://cloud-api.near.ai/v1/models`, copy the new `id`, and paste that exact value into the client's model field. For GLM 5.2, copy:

```text
z-ai/glm-5.2
```

If you are configuring a direct completions endpoint, also check `https://completions.near.ai/endpoints` and confirm the endpoint's `models` array includes the model name you plan to send.

## Tool behavior matrix

| Behavior | Tools | Refresh action |
| --- | --- | --- |
| Auto-fetch from an OpenAI-compatible model endpoint | Goose, Open WebUI, Kilo when the configured endpoint exposes `/v1/models` | Re-save or reconnect the provider, then refresh the model picker. If the picker still looks stale, test `GET https://cloud-api.near.ai/v1/models` with curl and restart the client. |
| Catalog-backed | OpenCode via models.dev | Check whether the catalog has the NEAR AI model. If not, add a manual provider model override when the tool supports it, or use the model only after the catalog updates. |
| Manual config | Cursor, Continue, Cline, Roo, Aider, Zed, LibreChat, LiteLLM, Dify | Copy the model ID from `/v1/models` into the tool's model field, config file, or provider settings. Restart or reload the tool if it caches settings. |

## Curl smoke test

First verify that the model is listed:

```bash
curl -fsSL https://cloud-api.near.ai/v1/models \
  | jq -e '.data[] | select(.id == "z-ai/glm-5.2")'
```

Then test a chat completion through the gateway:

```bash
curl https://cloud-api.near.ai/v1/chat/completions \
  -H "Authorization: Bearer $NEARAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "z-ai/glm-5.2",
    "messages": [
      {"role": "user", "content": "Reply with only: near-ai-ok"}
    ],
    "max_tokens": 20
  }'
```

Use the direct completions endpoint only after confirming it lists the model:

```bash
curl -fsS https://glm-5-2.completions.near.ai/v1/chat/completions \
  -H "Authorization: Bearer $NEARAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "z-ai/glm-5.2",
    "messages": [
      {"role": "user", "content": "Reply with only: near-ai-ok"}
    ],
    "max_tokens": 20
  }'
```

## Troubleshooting

| Symptom | Likely cause | Fix |
| --- | --- | --- |
| model not listed | The client cached an older model list, uses a catalog that has not updated, or requires manual config. | Run the `/v1/models` curl check, copy `z-ai/glm-5.2`, and paste it into the client's custom model field. Re-save, reconnect, or restart the client. |
| `401` | Missing, invalid, or expired NEAR AI Cloud API key. | Generate or copy a NEAR AI Cloud API key, store it in the client's secret field or environment variable, and retry without logging the key. |
| Wrong base URL includes `/chat/completions` | The client expects a base URL, but the full request endpoint was pasted. | Use `https://cloud-api.near.ai/v1` for gateway config, or `https://glm-5-2.completions.near.ai/v1` for direct completions config. Do not append `/chat/completions` to a base URL field. |

## Related guides

- [OpenAI Compatibility](/cloud/guides/openai-compatibility)
- [Available Models](/cloud/models)
- [Private Inference - Direct Completions](/cloud/private-inference#direct-completions)
- [Integrations Overview](/cloud/guides/integrations)

## Sources Checked

Sources checked on 2026-06-23:

- [NEAR AI Cloud models API](https://cloud-api.near.ai/v1/models)
- [NEAR AI Cloud direct completions endpoints](https://completions.near.ai/endpoints)
- [models.dev catalog](https://models.dev/)