next-ai-draw-io/docs/en/ai-providers.md

# AI Provider Configuration

This guide explains how to configure different AI model providers for next-ai-draw-io.

## Quick Start

1. Copy `.env.example` to `.env.local`
2. Set your API key for your chosen provider
3. Set `AI_MODEL` to your desired model
4. Run `npm run dev`

## Supported Providers

### Doubao (ByteDance Volcengine)

```bash
DOUBAO_API_KEY=your_api_key
AI_MODEL=doubao-seed-1-8-251215  # or other Doubao model
```

### Google Gemini

```bash
GOOGLE_GENERATIVE_AI_API_KEY=your_api_key
AI_MODEL=gemini-2.0-flash
```

Optional custom endpoint:

```bash
GOOGLE_BASE_URL=https://your-custom-endpoint
```

### Google Vertex AI (Enterprise GCP)

Google Vertex AI offers enterprise-grade features and data residency. **Express Mode** allows for simple API key authentication, making it compatible with edge runtimes like Vercel and Cloudflare.

```bash
GOOGLE_VERTEX_API_KEY=your_api_key
AI_MODEL=gemini-2.0-flash
```

Optional custom endpoint:

```bash
GOOGLE_VERTEX_BASE_URL=https://your-custom-endpoint
```

### OpenAI

```bash
OPENAI_API_KEY=your_api_key
AI_MODEL=gpt-4o
```

Optional custom endpoint (for OpenAI-compatible services):

```bash
OPENAI_BASE_URL=https://your-custom-endpoint/v1
```

LM Studio and other local OpenAI-compatible servers work the same way: set the base URL to `http://localhost:1234/v1` (LM Studio's default port) and use any non-empty API key, such as `lm-studio`. This works both in the environment variables above and in the model settings.

### AIHubMix

AIHubMix provides access to Claude, GPT, Gemini, DeepSeek, and other models through a single API key.

```bash
AIHUBMIX_API_KEY=your_api_key
AI_MODEL=claude-sonnet-4-5-20250929
```

Optional custom endpoint:

```bash
AIHUBMIX_BASE_URL=https://aihubmix.com/v1
```

### Anthropic

```bash
ANTHROPIC_API_KEY=your_api_key
AI_MODEL=claude-sonnet-4-5-20250514
```

Or use a Bearer auth token instead of an API key (e.g. when going through a gateway that issues OAuth-style tokens). `ANTHROPIC_AUTH_TOKEN` is sent as `Authorization: Bearer <token>`, while `ANTHROPIC_API_KEY` is sent as `x-api-key`. The two are mutually exclusive — set only one:

```bash
ANTHROPIC_AUTH_TOKEN=your_auth_token
AI_MODEL=claude-sonnet-4-5-20250514
```

Optional custom endpoint:

```bash
ANTHROPIC_BASE_URL=https://your-custom-endpoint
```

### DeepSeek

```bash
DEEPSEEK_API_KEY=your_api_key
AI_MODEL=deepseek-chat
```

Optional custom endpoint:

```bash
DEEPSEEK_BASE_URL=https://your-custom-endpoint
```

### SiliconFlow (OpenAI-compatible)

```bash
SILICONFLOW_API_KEY=your_api_key
AI_MODEL=deepseek-ai/DeepSeek-V3  # example; use any SiliconFlow model id
```

Optional custom endpoint (defaults to the recommended domain):

```bash
SILICONFLOW_BASE_URL=https://api.siliconflow.com/v1  # or https://api.siliconflow.cn/v1
```

### SGLang

```bash
SGLANG_API_KEY=your_api_key
AI_MODEL=your_model_id
```

Optional custom endpoint:

```bash
SGLANG_BASE_URL=https://your-custom-endpoint/v1
```

### Azure OpenAI

```bash
AZURE_API_KEY=your_api_key
AZURE_RESOURCE_NAME=your-resource-name  # Required: your Azure resource name
AI_MODEL=your-deployment-name
```

Or use a custom endpoint instead of resource name:

```bash
AZURE_API_KEY=your_api_key
AZURE_BASE_URL=https://your-resource.openai.azure.com/openai  # Alternative to AZURE_RESOURCE_NAME
AI_MODEL=your-deployment-name
```

Optional reasoning configuration:

```bash
AZURE_REASONING_EFFORT=low      # Optional: low, medium, high
AZURE_REASONING_SUMMARY=detailed  # Optional: none, brief, detailed
```

### AWS Bedrock

```bash
AWS_REGION=us-west-2
AWS_ACCESS_KEY_ID=your_access_key_id
AWS_SECRET_ACCESS_KEY=your_secret_access_key
AI_MODEL=global.anthropic.claude-sonnet-5-5
```

Recent Claude models answer only through an inference profile id, which starts with a region prefix such as `global.` or `us.`. The plain id (`anthropic.claude-sonnet-5-5`) fails with "on-demand throughput isn't supported".

Note: On AWS (Lambda, EC2 with IAM role), credentials are automatically obtained from the IAM role.

### OpenRouter

```bash
OPENROUTER_API_KEY=your_api_key
AI_MODEL=anthropic/claude-sonnet-4
```

Optional custom endpoint:

```bash
OPENROUTER_BASE_URL=https://your-custom-endpoint
```

### Ollama (Local)

```bash
AI_PROVIDER=ollama
AI_MODEL=llama3.2
```

Optional custom URL:

```bash
OLLAMA_BASE_URL=http://localhost:11434/api
```

### ModelScope

```bash
MODELSCOPE_API_KEY=your_api_key
AI_MODEL=Qwen/Qwen3-235B-A22B-Instruct-2507
```

Optional custom endpoint:

```bash
MODELSCOPE_BASE_URL=https://your-custom-endpoint
```

### Vercel AI Gateway

Vercel AI Gateway provides unified access to multiple AI providers through a single API key. This simplifies authentication and allows you to switch between providers without managing multiple API keys.

**Basic Usage (Vercel-hosted Gateway):**

```bash
AI_GATEWAY_API_KEY=your_gateway_api_key
AI_MODEL=openai/gpt-4o
```

**Custom Gateway URL (for local development or self-hosted Gateway):**

```bash
AI_GATEWAY_API_KEY=your_custom_api_key
AI_GATEWAY_BASE_URL=https://your-custom-gateway.com/v1/ai
AI_MODEL=openai/gpt-4o
```

Model format uses `provider/model` syntax:

-   `openai/gpt-4o` - OpenAI GPT-4o
-   `anthropic/claude-sonnet-4-5` - Anthropic Claude Sonnet 4.5
-   `google/gemini-2.0-flash` - Google Gemini 2.0 Flash

**Configuration notes:**

-   If `AI_GATEWAY_BASE_URL` is not set, the default Vercel Gateway URL (`https://ai-gateway.vercel.sh/v1/ai`) is used
-   Custom base URL is useful for:
    -   Local development with a custom Gateway instance
    -   Self-hosted AI Gateway deployments
    -   Enterprise proxy configurations
-   When using a custom base URL, you must also provide `AI_GATEWAY_API_KEY`

Get your API key from the [Vercel AI Gateway dashboard](https://vercel.com/ai-gateway).

### MiniMax

MiniMax supports two API formats:
- **Anthropic-compatible** (`/anthropic` endpoint) — recommended, supports interleaved thinking
- **OpenAI-compatible** (`/v1` endpoint) — standard OpenAI chat completions format

```bash
MINIMAX_API_KEY=your_api_key
AI_MODEL=MiniMax-M3
```

Optional configuration:

```bash
# China mainland, Anthropic-compatible (default)
MINIMAX_BASE_URL=https://api.minimaxi.com/anthropic

# China mainland, OpenAI-compatible
MINIMAX_BASE_URL=https://api.minimaxi.com/v1

# International, Anthropic-compatible
MINIMAX_BASE_URL=https://api.minimax.io/anthropic

# International, OpenAI-compatible
MINIMAX_BASE_URL=https://api.minimax.io/v1
```

### GLM (Zhipu AI)

```bash
GLM_API_KEY=your_api_key
AI_MODEL=glm-4
```

Optional custom endpoint:

```bash
GLM_BASE_URL=https://your-custom-endpoint
```

### Qwen (Alibaba Cloud)

```bash
QWEN_API_KEY=your_api_key
AI_MODEL=qwen-turbo
```

Optional custom endpoint:

```bash
QWEN_BASE_URL=https://your-custom-endpoint
```

### Kimi (Moonshot AI)

```bash
KIMI_API_KEY=your_api_key
AI_MODEL=kimi-latest
```

Optional custom endpoint:

```bash
KIMI_BASE_URL=https://your-custom-endpoint
```

### Qiniu (Qiniu Cloud)

```bash
QINIU_API_KEY=your_api_key
AI_MODEL=your_model_id
```

Optional custom endpoint:

```bash
QINIU_BASE_URL=https://your-custom-endpoint
```

### MiMo (Xiaomi)

```bash
MIMO_API_KEY=your_api_key
AI_MODEL=mimo-v2.5-pro
```

Optional custom endpoint (Token Plan subscribers should set their dedicated Base URL):

```bash
MIMO_BASE_URL=https://token-plan-cn.xiaomimimo.com/v1
```

### Any OpenAI-compatible API (custom)

For a server not listed above (vLLM, LM Studio, LiteLLM, an API gateway), pick **OpenAI-compatible** in the settings and enter its base URL and a key; a server that ignores keys takes any non-empty value. Several system messages are merged into one, as open-source chat templates expect, and `<think>` reasoning is split from the reply.

```bash
CUSTOM_API_KEY=your_api_key
CUSTOM_BASE_URL=http://127.0.0.1:8000/v1
AI_MODEL=your_model_id
```

---

## Auto-Detection

If you only configure **one** provider's API key, the system will automatically detect and use that provider. No need to set `AI_PROVIDER`.

If you configure **multiple** API keys, you must explicitly set `AI_PROVIDER`:

```bash
AI_PROVIDER=google  # or: openai, anthropic, google, vertexai, azure, bedrock, ollama, openrouter, aihubmix, deepseek, siliconflow, sglang, gateway, edgeone, doubao, modelscope, glm, qwen, qiniu, kimi, minimax, novita, mimo, atlascloud, custom
```

## Server-Side Multi-Model Configuration

Administrators can configure multiple server-side models that are available to all users without requiring personal API keys.

### Configuration Methods

**Option 1: Environment Variable** (recommended for cloud deployments)

Set `AI_MODELS_CONFIG` as a JSON string:

```bash
AI_MODELS_CONFIG='{"providers":[{"name":"OpenAI","provider":"openai","models":["gpt-4o"],"default":true}]}'
```

**Option 2: Config File**

Create an `ai-models.json` file in the project root (or set `AI_MODELS_CONFIG_PATH` to a custom location).

**Option 3: Comma-separated `AI_MODEL`** (quick setup, single provider)

If you only need multiple models from one provider, list them in `AI_MODEL` separated by commas. The first model is treated as the default.

```bash
AI_PROVIDER=doubao
AI_MODEL=doubao-seed-1-8-251215,doubao-seed-1-6-flash,doubao-seed-1-6-pro
```

This is shorthand for the equivalent `ai-models.json`. For multiple providers or custom `apiKeyEnv` / `baseUrlEnv`, use Option 1 or 2 instead.

### Example Configuration

```json
{
  "providers": [
    {
      "name": "OpenAI Production",
      "provider": "openai",
      "models": ["gpt-4o", "gpt-4o-mini"],
      "default": true
    },
    {
      "name": "Custom DeepSeek",
      "provider": "deepseek",
      "models": ["deepseek-chat"],
      "apiKeyEnv": "MY_DEEPSEEK_KEY",
      "baseUrlEnv": "MY_DEEPSEEK_URL"
    }
  ]
}
```

### Field Reference

| Field | Required | Description |
|-------|----------|-------------|
| `name` | Yes | Display name (supports multiple configs for same provider) |
| `provider` | Yes | Provider type (`openai`, `anthropic`, `google`, `bedrock`, etc.) |
| `models` | Yes | List of model IDs |
| `default` | No | Set to `true` to auto-select this provider's first model as default |
| `apiKeyEnv` | No | Custom API key env var name (defaults to provider's standard var like `OPENAI_API_KEY`). May also be an array of env var names: each request picks one that has a value at random, spreading load over several keys |
| `baseUrlEnv` | No | Custom base URL env var name |

### Notes

- API keys and credentials are provided via environment variables. By default, standard var names are used (e.g., `OPENAI_API_KEY`), but you can specify custom var names with `apiKeyEnv`.
- The `name` field allows multiple configurations for the same provider (e.g., "OpenAI Production" and "OpenAI Staging" both using `provider: "openai"` but with different `apiKeyEnv` values).
- If config is not present, the app falls back to `AI_PROVIDER`/`AI_MODEL` environment variable configuration.

## Model Capability Requirements

This task requires exceptionally strong model capabilities, as it involves generating long-form text with strict formatting constraints (draw.io XML).

**Recommended models**:

-   Claude Sonnet 4.5 / Opus 4.5

**Note on Ollama**: While Ollama is supported as a provider, it's generally not practical for this use case unless you're running high-capability models like DeepSeek R1 or Qwen3-235B locally.

## Temperature Setting

You can optionally configure the temperature via environment variable:

```bash
TEMPERATURE=0  # More deterministic output (recommended for diagrams)
```

**Important**: Leave `TEMPERATURE` unset for models that don't support temperature settings, such as:
- GPT-5.1 and other reasoning models
- Some specialized models

When unset, the model uses its default behavior.

## Recommendations

-   **Best experience**: Use models with vision support (GPT-4o, Claude, Gemini) for image-to-diagram features
-   **Budget-friendly**: DeepSeek offers competitive pricing
-   **Privacy**: Use Ollama for fully local, offline operation (requires powerful hardware)
-   **Flexibility**: OpenRouter provides access to many models through a single API

## Adding a Provider

Every fact about a provider lives in one record in `lib/providers.ts`: which AI SDK runs it (`sdk`), what it signs in with (`credential`), the prefix of its `<PREFIX>_API_KEY` / `<PREFIX>_BASE_URL` variables (`envPrefix`), its official URL, the picker group, and optional notes. The settings UI, the connection test, the chat route and the admin panel all read that record, so adding an OpenAI-compatible provider is:

1. Add a record to `lib/providers.ts`, for example:

    ```ts
    acme: {
        label: "Acme AI",
        sdk: "openai-compatible",
        credential: "apiKey",
        group: "aggregators",
        envPrefix: "ACME",
        defaultBaseUrl: "https://api.acme.example/v1",
        apiKeyUrl: "https://acme.example/keys",
        modelList: "openai",
    },
    ```

    A provider that needs a hint under its base URL field, or a note in the picker, gets a `baseUrlHint` or `note` object with all four UI languages (`en`, `zh`, `ja`, `zh-Hant`). Providers that cannot list their models online keep a short `models` list instead of `modelList`.
2. Add `ACME_API_KEY` and `ACME_BASE_URL` to `env.example` (a unit test checks that every record's variables appear there).
3. Add a section for it to this document in `docs/en`, `docs/cn` and `docs/ja`.
4. Add it to the two lists at the top of `tests/unit/provider-matrix.test.ts` (`MATRIX_PROVIDERS` and `MATRIX_MODEL_IDS`) and regenerate the behavior snapshot with `npx vitest run tests/unit/provider-matrix.test.ts -u`; the new rows are the provider's, the existing rows must not change. `tests/unit/providers.test.ts` spells out the picker's groups and the provider sets that change what the server does (auto-detection, single system message), so add it there too. The provider count in the three READMEs and the `AI_PROVIDER` list in this document change as well.