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

# Dify

> Configure Dify with NEAR AI Cloud through the OpenAI-API-compatible model provider plugin.

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 theme={"dark"}
   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 theme={"dark"}
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 theme={"dark"}
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 theme={"dark"}
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)
* [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)


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