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.

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:

Fetch the live model metadata:

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

Copy the new model’s exact id.
In Dify, open Settings -> Model Providers -> OpenAI-API-compatible.
Add a new custom model with the copied id, the same URL, and the context/output limits from the live metadata.
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

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

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.

Sources Checked

Sources checked on 2026-06-23:

Get Started

Models

Private Inference

Guides

Experimental

Prerequisites

Install or Select the Plugin

Add the NEAR AI Cloud Model

Refresh models

Curl smoke test

Troubleshooting

Sources Checked

​Prerequisites

​Install or Select the Plugin

​Add the NEAR AI Cloud Model

​Refresh models

​Curl smoke test

​Troubleshooting

​Related guides

​Sources Checked

Prerequisites

Install or Select the Plugin

Add the NEAR AI Cloud Model

Refresh models

Curl smoke test

Troubleshooting

Related guides

Sources Checked