LICENSE-MIT Documentation

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.

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 Copy Chapter

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

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 Copy Chapter

• Cursor installed.
• A NEAR AI Cloud API key from the NEAR AI Cloud Dashboard.
• 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 Copy Chapter

Use the gateway base URL:

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 Copy Chapter

Use the exact model ID from NEAR AI Cloud:

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.

Configure Copy Chapter

In Cursor, follow this path:

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 Copy Chapter

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 Copy

   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 Copy Chapter

First verify NEAR AI Cloud directly, before debugging Cursor:

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 Copy Chapter

Related guides Copy Chapter

• Model Discovery and Refresh
• OpenAI Compatibility
• Private Inference - Direct Completions
• Available Models
• Continue
• Cline, Roo Code, and Kilo Code

Sources Checked Copy Chapter

Sources checked on 2026-06-23:

• Cursor API keys
• LLM Gateway Cursor guide
• Public Cursor forum reports about custom OpenAI base URL and Composer/custom key behavior

File: cloud/guides/integrations/dify.mdx Copy Chapter

title: "Dify" Copy Chapter

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 Copy Chapter

• 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.

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

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 Copy Chapter

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 Copy Chapter

Add a custom model with these values:

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 Copy Chapter

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 Copy

   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:

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 Copy Chapter

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

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:

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 Copy Chapter

Related guides Copy Chapter

• Model Discovery and Refresh
• OpenAI Compatibility
• Available Models
• Private Inference - Direct Completions
• Open WebUI
• LibreChat

Sources Checked Copy Chapter

Sources checked on 2026-06-23:

• Dify model providers
• Dify OpenAI-API-compatible plugin
• Dify OpenAI-API-compatible provider schema (function_calling_type, agent_thought_support, structured_output_support)
• Model Discovery and Refresh

File: cloud/guides/integrations/index.mdx Copy Chapter

title: "Integrations" sidebarTitle: "Overview" Copy Chapter

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

Most clients need the same values:

Software Covered Copy Chapter

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 Copy Section

• Cursor
• Continue
• Cline, Roo Code, and Kilo Code
• Aider and Zed
• OpenCode and Goose

Self-hosted and team apps Copy Section

• LibreChat
• Open WebUI
• LiteLLM
• Dify

Model Discovery Copy Chapter

NEAR AI Cloud can add new models over time. Use the Model Discovery guide 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.

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

Related guides Copy Chapter

• OpenAI Client
• Model Discovery
• Available Models

File: cloud/guides/integrations/librechat.mdx Copy Chapter

title: "LibreChat" Copy Chapter

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 Copy Chapter

• A running LibreChat installation.
• A NEAR AI Cloud API key from the NEAR AI Cloud Dashboard.
• 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 Copy Chapter

Use the NEAR AI Cloud gateway base URL:

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 Copy Chapter

Use the NEAR AI Cloud gateway model ID:

z-ai/glm-5.2

Check Model Discovery and Refresh before adding newer model IDs.

Configure Copy Chapter

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

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:

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:

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

Then make sure the override includes this mount:

services:
  api:
    volumes:
      - type: bind
        source: ./librechat.yaml
        target: /app/librechat.yaml

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

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 Copy Chapter

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:

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 Copy Chapter

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

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 Copy Chapter

Related guides Copy Chapter

• Model Discovery and Refresh
• OpenAI Compatibility
• Available Models
• Private Inference - Direct Completions
• Open WebUI
• Dify
• LiteLLM Proxy

Sources Checked Copy Chapter

Sources checked on 2026-06-23:

• LibreChat Custom Endpoints
• LibreChat Custom Config
• LibreChat Custom Endpoint Object Structure
• Model Discovery and Refresh

File: cloud/guides/integrations/litellm.mdx Copy Chapter

title: "LiteLLM Proxy" sidebarTitle: "LiteLLM" Copy Chapter

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

Prerequisites Copy Chapter

• LiteLLM Python SDK or LiteLLM Proxy.
• A NEAR AI Cloud API key from the NEAR AI Cloud Dashboard.
• 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.

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

Base URL Copy Chapter

Use the NEAR AI Cloud gateway base URL:

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 Copy Chapter

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

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 when you need the freshest NEAR AI Cloud model list.

Configure Copy Chapter

Python SDK Copy Section

Call NEAR AI Cloud directly from the LiteLLM Python SDK:

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` Copy Section

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

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:

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:

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 Copy Section

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:

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 Copy Chapter

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:

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 Copy Chapter

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

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 Copy Chapter

Related guides Copy Chapter

• Model Discovery and Refresh
• OpenAI Compatibility
• Available Models
• Private Inference - Direct Completions
• LibreChat
• Open WebUI

Sources Checked Copy Chapter

Sources checked on 2026-06-23:

• LiteLLM OpenAI-compatible endpoints
• LiteLLM proxy config
• LiteLLM API key/base configuration

File: cloud/guides/integrations/model-discovery.mdx Copy Chapter

title: "Model Discovery and Refresh" sidebarTitle: "Model Discovery" Copy Chapter

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:

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 Copy Chapter

The gateway model list is available from:

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

To find the GLM 5.2 entry:

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:

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 Copy Chapter

Direct completions endpoints are listed at:

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

To find the GLM 5.2 direct completions endpoint:

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:

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 Copy Chapter

Use the gateway by default:

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:

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. 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 Copy Chapter

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:

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 Copy Chapter

Curl smoke test Copy Chapter

First verify that the model is listed:

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:

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:

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 Copy Chapter

Related guides Copy Chapter

• OpenAI Compatibility
• Available Models
• Private Inference - Direct Completions
• Integrations Overview

Sources Checked Copy Chapter

Sources checked on 2026-06-23:

• NEAR AI Cloud models API
• NEAR AI Cloud direct completions endpoints
• models.dev catalog