🔧 Environment Variables Configuration Guide¶

This document provides all environment variables supported by New API and their configuration instructions. You can customize the system behavior by setting these environment variables.

Tip

New API supports reading environment variables from a .env file. Please refer to the .env.example file and rename it to .env when using.

🔄 Basic Configuration¶

Environment Variable	Description	Default	Example
`PORT`	Service listening port	`3000`	`PORT=8080`
`TZ`	Timezone setting	`Asia/Shanghai`	`TZ=America/New_York`

💾 Database Configuration¶

Environment Variable	Description	Default	Example
`SQL_DSN`	Database connection string	SQLite (data/one-api.db)	`SQL_DSN=root:123456@tcp(localhost:3306)/oneapi`
`SQL_MAX_IDLE_CONNS`	Max idle connections in pool	`100`	`SQL_MAX_IDLE_CONNS=50`
`SQL_MAX_OPEN_CONNS`	Max open connections in pool	`1000`	`SQL_MAX_OPEN_CONNS=500`
`SQL_CONN_MAX_LIFETIME`	Max connection lifetime (minutes)	`60`	`SQL_CONN_MAX_LIFETIME=120`
`LOG_SQL_DSN`	Separate database connection string for logs	-	`LOG_SQL_DSN=root:123456@tcp(localhost:3306)/oneapi_logs`
`SQLITE_BUSY_TIMEOUT`	SQLite lock wait timeout (ms)	`3000`	`SQLITE_BUSY_TIMEOUT=5000`

📦 Cache Configuration¶

Environment Variable	Description	Default	Example
`REDIS_CONN_STRING`	Redis connection string	-	`REDIS_CONN_STRING=redis://default:redispw@localhost:6379`
`MEMORY_CACHE_ENABLED`	Enable in-memory cache	`false`	`MEMORY_CACHE_ENABLED=true`
`REDIS_CONN_POOL_SIZE`	Redis connection pool size	-	`REDIS_CONN_POOL_SIZE=10`
`REDIS_PASSWORD`	Redis cluster or sentinel mode password	-	`REDIS_PASSWORD=your_password`
`REDIS_MASTER_NAME`	Redis sentinel mode master name	-	`REDIS_MASTER_NAME=mymaster`
`BATCH_UPDATE_ENABLED`	Enable database batch update aggregation	`false`	`BATCH_UPDATE_ENABLED=true`
`BATCH_UPDATE_INTERVAL`	Batch update aggregation interval (seconds)	`5`	`BATCH_UPDATE_INTERVAL=10`

🌐 Multi-Node & Security Configuration¶

Environment Variable	Description	Default	Example
`SESSION_SECRET`	Session secret (required for multi-node deployment)	-	`SESSION_SECRET=random_string`
`CRYPTO_SECRET`	Encryption secret (for encrypting database content)	-	`CRYPTO_SECRET=your_crypto_secret`
`FRONTEND_BASE_URL`	Frontend base URL	-	`FRONTEND_BASE_URL=https://your-domain.com`
`SYNC_FREQUENCY`	Cache and database sync frequency (seconds)	`600`	`SYNC_FREQUENCY=60`
`NODE_TYPE`	Node type	`master`	`NODE_TYPE=slave`
`INITIAL_ROOT_TOKEN`	Root user token created on first startup	-	`INITIAL_ROOT_TOKEN=your_token`
`INITIAL_ROOT_ACCESS_TOKEN`	System admin token created on first startup	-	`INITIAL_ROOT_ACCESS_TOKEN=your_token`

Cluster Deployment

For how to use these environment variables to build a complete cluster deployment, please refer to the Cluster Deployment Guide.

👤 User & Token Configuration¶

Environment Variable	Description	Default	Example
`DEFAULT_QUOTA`	Default quota for new users	`0`	`DEFAULT_QUOTA=10`
`GLOBAL_USER_QUOTA`	Global user quota limit	-	`GLOBAL_USER_QUOTA=100`
`GENERATE_DEFAULT_TOKEN`	Generate initial token for new registered users	`false`	`GENERATE_DEFAULT_TOKEN=true`
`NOTIFICATION_LIMIT_DURATION_MINUTE`	Notification limit duration (minutes)	`10`	`NOTIFICATION_LIMIT_DURATION_MINUTE=15`
`NOTIFY_LIMIT_COUNT`	Max notifications in specified duration	`2`	`NOTIFY_LIMIT_COUNT=3`

🚦 Request Limiting Configuration¶

Environment Variable	Description	Default	Example
`GLOBAL_API_RATE_LIMIT`	Global API rate limit (per IP, 3 minutes)	`180`	`GLOBAL_API_RATE_LIMIT=100`
`GLOBAL_WEB_RATE_LIMIT`	Global Web rate limit (per IP, 3 minutes)	`60`	`GLOBAL_WEB_RATE_LIMIT=30`
`RELAY_TIMEOUT`	Relay request timeout (seconds)	-	`RELAY_TIMEOUT=60`
`USER_CONTENT_REQUEST_TIMEOUT`	User content download timeout (seconds)	-	`USER_CONTENT_REQUEST_TIMEOUT=30`
`STREAMING_TIMEOUT`	Streaming single reply timeout (seconds)	`60`	`STREAMING_TIMEOUT=120`
`MAX_FILE_DOWNLOAD_MB`	Max file download size (MB)	`20`	`MAX_FILE_DOWNLOAD_MB=50`

RELAY_TIMEOUT Setting Warning

Be cautious when setting the RELAY_TIMEOUT environment variable. If set too short, it may cause the following issues:

The upstream API has completed the request and billed, but the local system did not complete billing due to timeout
Causes billing desynchronization, which may lead to system loss
It is recommended not to set unless you know what you are doing

📡 Channel Management Configuration¶

Environment Variable	Description	Default	Example
`CHANNEL_UPDATE_FREQUENCY`	Periodically update channel balance (minutes)	-	`CHANNEL_UPDATE_FREQUENCY=1440`
`CHANNEL_TEST_FREQUENCY`	Periodically check channels (minutes)	-	`CHANNEL_TEST_FREQUENCY=1440`
`POLLING_INTERVAL`	Request interval when batch updating channels (seconds)	`0`	`POLLING_INTERVAL=5`
`ENABLE_METRIC`	Disable channels based on request success rate	`false`	`ENABLE_METRIC=true`
`METRIC_QUEUE_SIZE`	Request success rate statistics queue size	`10`	`METRIC_QUEUE_SIZE=20`
`METRIC_SUCCESS_RATE_THRESHOLD`	Request success rate threshold	`0.8`	`METRIC_SUCCESS_RATE_THRESHOLD=0.7`
`TEST_PROMPT`	User prompt for model testing	`Print your model name exactly...`	`TEST_PROMPT=Hello`

🤖 Model & Request Handling Configuration¶

Environment Variable	Description	Default	Example
`FORCE_STREAM_OPTION`	Override client stream_options parameter	`true`	`FORCE_STREAM_OPTION=false`
`GET_MEDIA_TOKEN`	Count image tokens	`true`	`GET_MEDIA_TOKEN=false`
`GET_MEDIA_TOKEN_NOT_STREAM`	Count image tokens in non-stream mode	`true`	`GET_MEDIA_TOKEN_NOT_STREAM=false`
`UPDATE_TASK`	Update async tasks (MJ, Suno)	`true`	`UPDATE_TASK=false`
`ENFORCE_INCLUDE_USAGE`	Force return usage in stream mode	`false`	`ENFORCE_INCLUDE_USAGE=true`
`TIKTOKEN_CACHE_DIR`	Tiktoken encoder cache directory, for storing tokenizer files to avoid network download	-	`TIKTOKEN_CACHE_DIR=/cache/tiktoken`
`DATA_GYM_CACHE_DIR`	DataGym cache directory	-	`DATA_GYM_CACHE_DIR=/cache/data_gym`

Tiktoken File Configuration

After downloading tiktoken files, please rename them as follows:

cl100k_base.tiktoken rename to 9b5ad71b2ce5302211f9c61530b329a4922fc6a4
o200k_base.tiktoken rename to fb374d419588a4632f3f557e76b4b70aebbca790

These files should be placed in the directory specified by TIKTOKEN_CACHE_DIR to improve token calculation performance and reduce network dependency.

Tiktoken Configuration Example

# Docker environment example
TIKTOKEN_CACHE_DIR=/app/data/tiktoken

# Then download and rename tiktoken files into this directory:
/app/data/tiktoken/9b5ad71b2ce5302211f9c61530b329a4922fc6a4
/app/data/tiktoken/fb374d419588a4632f3f557e76b4b70aebbca790

Tiktoken is the tokenizer used by OpenAI to calculate the number of tokens in text. By caching these files locally, you can avoid downloading from the network every time the system starts, improving stability and performance, especially in network-restricted environments.

🔎 Specific Model Configuration¶

Environment Variable	Description	Default	Example
`AZURE_DEFAULT_API_VERSION`	Default API version for Azure channel	`2024-12-01-preview`	`AZURE_DEFAULT_API_VERSION=2023-05-15`
`COHERE_SAFETY_SETTING`	Cohere model safety setting	`NONE`	`COHERE_SAFETY_SETTING=CONTEXTUAL`
`GEMINI_VISION_MAX_IMAGE_NUM`	Gemini model max image number	`16`	`GEMINI_VISION_MAX_IMAGE_NUM=8`
`GEMINI_VERSION`	Gemini version	`v1`	`GEMINI_VERSION=v1beta`
`DIFY_DEBUG`	Output workflow and node info for Dify channel	`true`	`DIFY_DEBUG=false`

📨 Other Configuration¶

Environment Variable	Description	Default	Example
`EMAIL_SERVER`	Email server configuration	-	`EMAIL_SERVER=smtp.example.com:25`
`EMAIL_FROM`	Email sender address	-	`EMAIL_FROM=noreply@example.com`
`EMAIL_PASSWORD`	Email server password	-	`EMAIL_PASSWORD=yourpassword`
`ERROR_LOG_ENABLE`	Record and display error logs on frontend	false	`ERROR_LOG_ENABLED=true`

⚠️ Deprecated Environment Variables¶

The following environment variables are deprecated. Please use the corresponding options in the system settings interface:

Environment Variable	Replacement
`GEMINI_MODEL_MAP`	Please set in System Settings - Model Related Settings
`GEMINI_SAFETY_SETTING`	Please set in System Settings - Model Related Settings

🌍 Multi-Node Deployment Example¶

In multi-node deployment scenarios, you must set the following environment variables:

👑 Master Node Configuration¶

# Database configuration - use remote database
SQL_DSN=root:password@tcp(db-server:3306)/oneapi

# Security configuration
SESSION_SECRET=your_unique_session_secret
CRYPTO_SECRET=your_unique_crypto_secret

# Redis cache configuration
REDIS_CONN_STRING=redis://default:password@redis-server:6379

👥 Slave Node Configuration¶

# Database configuration - use the same remote database
SQL_DSN=root:password@tcp(db-server:3306)/oneapi

# Security configuration - use the same secrets as master node
SESSION_SECRET=your_unique_session_secret
CRYPTO_SECRET=your_unique_crypto_secret

# Redis cache configuration - use the same Redis as master node
REDIS_CONN_STRING=redis://default:password@redis-server:6379

# Node type setting
NODE_TYPE=slave

# Optional: Frontend base URL
FRONTEND_BASE_URL=https://your-domain.com

# Optional: Sync frequency
SYNC_FREQUENCY=60

Full Cluster Configuration

This is just a basic multi-node configuration example. For full cluster deployment configuration, architecture explanation, and best practices, please refer to the Cluster Deployment Guide.

🐳 Environment Variables Example in Docker Compose¶

Below is a brief example of setting environment variables in a Docker Compose configuration file:

services:
  new-api:
    image: calciumion/new-api:latest
    environment:
      - TZ=Asia/Shanghai
      - SQL_DSN=root:123456@tcp(mysql:3306)/oneapi
      - REDIS_CONN_STRING=redis://default:redispw@redis:6379
      - SESSION_SECRET=your_unique_session_secret
      - CRYPTO_SECRET=your_unique_crypto_secret
      - MEMORY_CACHE_ENABLED=true
      - GENERATE_DEFAULT_TOKEN=true
      - STREAMING_TIMEOUT=120
      - CHANNEL_UPDATE_FREQUENCY=1440

For a complete Docker Compose configuration, including more environment variable options, please refer to the Docker Compose Configuration Guide document.