Environment Variable Configuration Guide

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

Tip

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

Basic Configuration

Environment Variable	Description	Default Value	Example
`PORT`	Service listening port	`3000`	`PORT=8080`
`TZ`	Time zone setting	-	`TZ=America/New_York`
`VERSION`	Override running version number	-	`VERSION=1.2.3`

Database Configuration

Environment Variable	Description	Default Value	Example
`SQL_DSN`	Database connection string	SQLite (`one-api.db`)	MySQL: `SQL_DSN=root:123456@tcp(localhost:3306)/new-api` \| PostgreSQL: `SQL_DSN=postgresql://root:123456@postgres:5432/new-api`
`SQL_MAX_IDLE_CONNS`	Maximum idle connections in connection pool	`100`	`SQL_MAX_IDLE_CONNS=50`
`SQL_MAX_OPEN_CONNS`	Maximum open connections in connection pool	`1000`	`SQL_MAX_OPEN_CONNS=500`
`SQL_MAX_LIFETIME`	Maximum connection lifetime (seconds)	`60`	`SQL_MAX_LIFETIME=120`
`LOG_SQL_DSN`	Separate database connection string for log table	-	`LOG_SQL_DSN=root:123456@tcp(localhost:3306)/oneapi_logs`
`SQLITE_PATH`	SQLite database path	`one-api.db`	`SQLITE_PATH=/var/lib/new-api/new-api.db`

Cache Configuration

Environment Variable	Description	Default Value	Example
`REDIS_CONN_STRING`	Redis connection string	-	`REDIS_CONN_STRING=redis://default:redispw@localhost:6379`
`REDIS_POOL_SIZE`	Redis connection pool size	`10`	`REDIS_POOL_SIZE=20`
`MEMORY_CACHE_ENABLED`	Whether to enable memory cache (automatically enabled when Redis is enabled)	`false`	`MEMORY_CACHE_ENABLED=true`
`SYNC_FREQUENCY`	Cache and database synchronization frequency (seconds)	`60`	`SYNC_FREQUENCY=120`
`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 and Security Configuration

Environment Variable	Description	Default Value	Example
`SESSION_SECRET`	Session secret (required for multi-machine deployment)	-	`SESSION_SECRET=your_session_secret`
`CRYPTO_SECRET`	Encryption secret (encrypts database content, defaults to SESSION_SECRET)	-	`CRYPTO_SECRET=your_crypto_secret`
`FRONTEND_BASE_URL`	Frontend base URL (used by slave nodes, redirects unmatched routes to this address)	-	`FRONTEND_BASE_URL=https://your-domain.com`
`NODE_TYPE`	Node type	`master`	`NODE_TYPE=slave`
`TLS_INSECURE_SKIP_VERIFY`	Globally skip TLS certificate verification	`false`	`TLS_INSECURE_SKIP_VERIFY=true`
`TRUSTED_REDIRECT_DOMAINS`	List of trusted redirect domains (comma-separated)	-	`TRUSTED_REDIRECT_DOMAINS=example.com,api.example.com`

SESSION_SECRET Notes

SESSION_SECRET cannot be set to random_string, otherwise the program will refuse to start. All nodes must use the same secret for multi-machine deployment.

Cluster Deployment

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

User and Token Configuration

Environment Variable	Description	Default Value	Example
`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`	Maximum number of notifications within the specified duration	`2`	`NOTIFY_LIMIT_COUNT=3`

Request Limit Configuration

Environment Variable	Description	Default Value	Example
`GLOBAL_API_RATE_LIMIT_ENABLE`	Global API rate limit switch	`true`	`GLOBAL_API_RATE_LIMIT_ENABLE=false`
`GLOBAL_API_RATE_LIMIT`	Global API rate limit (per IP)	`180`	`GLOBAL_API_RATE_LIMIT=100`
`GLOBAL_API_RATE_LIMIT_DURATION`	Global API rate limit window (seconds)	`180`	`GLOBAL_API_RATE_LIMIT_DURATION=120`
`GLOBAL_WEB_RATE_LIMIT_ENABLE`	Global Web rate limit switch	`true`	`GLOBAL_WEB_RATE_LIMIT_ENABLE=false`
`GLOBAL_WEB_RATE_LIMIT`	Global Web rate limit (per IP)	`60`	`GLOBAL_WEB_RATE_LIMIT=30`
`GLOBAL_WEB_RATE_LIMIT_DURATION`	Global Web rate limit window (seconds)	`180`	`GLOBAL_WEB_RATE_LIMIT_DURATION=120`
`CRITICAL_RATE_LIMIT_ENABLE`	Critical operation rate limit switch	`true`	`CRITICAL_RATE_LIMIT_ENABLE=false`
`CRITICAL_RATE_LIMIT`	Critical operation rate limit count	`20`	`CRITICAL_RATE_LIMIT=10`
`CRITICAL_RATE_LIMIT_DURATION`	Critical operation rate limit window (seconds)	`1200`	`CRITICAL_RATE_LIMIT_DURATION=600`

Relay and Proxy Configuration

Environment Variable	Description	Default Value	Example
`RELAY_TIMEOUT`	Relay request timeout (seconds), 0 for unlimited	`0`	`RELAY_TIMEOUT=60`
`STREAMING_TIMEOUT`	Streaming single response timeout (seconds)	`300`	`STREAMING_TIMEOUT=120`
`RELAY_MAX_IDLE_CONNS`	Maximum idle connections in relay HTTP client pool	`500`	`RELAY_MAX_IDLE_CONNS=1000`
`RELAY_MAX_IDLE_CONNS_PER_HOST`	Maximum idle connections per host in relay HTTP client pool	`100`	`RELAY_MAX_IDLE_CONNS_PER_HOST=200`
`MAX_FILE_DOWNLOAD_MB`	Maximum file download size (MB)	`64`	`MAX_FILE_DOWNLOAD_MB=128`
`MAX_REQUEST_BODY_MB`	Maximum request body size (MB, counted after decompression; prevents zip bomb/OOM)	`128`	`MAX_REQUEST_BODY_MB=256`
`STREAM_SCANNER_MAX_BUFFER_MB`	SSE stream scanner maximum buffer size (MB)	`64`	`STREAM_SCANNER_MAX_BUFFER_MB=128`

RELAY_TIMEOUT Setting Warning

Please be cautious when setting the RELAY_TIMEOUT environment variable. Setting it too short may lead to the following issues:

Upstream API has completed the request and charged, but local billing failed due to timeout
Leading to billing desynchronization, which may result in system losses
It is recommended not to set it unless you know what you are doing

Channel Management Configuration

Environment Variable	Description	Default Value	Example
`CHANNEL_UPDATE_FREQUENCY`	Regularly update channel balance (minutes)	- (disabled if not set)	`CHANNEL_UPDATE_FREQUENCY=1440`
`CHANNEL_TEST_FREQUENCY`	Regularly check channels (minutes), overrides database settings	- (uses database settings if not set)	`CHANNEL_TEST_FREQUENCY=1440`
`POLLING_INTERVAL`	Request polling interval (seconds)	`0`	`POLLING_INTERVAL=5`

Channel Upstream Model Synchronization

Environment Variable	Description	Default Value	Example
`CHANNEL_UPSTREAM_MODEL_UPDATE_TASK_ENABLED`	Enable regular synchronization of upstream provider model list	`true`	`CHANNEL_UPSTREAM_MODEL_UPDATE_TASK_ENABLED=false`
`CHANNEL_UPSTREAM_MODEL_UPDATE_TASK_INTERVAL_MINUTES`	Model list synchronization interval (minutes)	`30`	`CHANNEL_UPSTREAM_MODEL_UPDATE_TASK_INTERVAL_MINUTES=60`
`CHANNEL_UPSTREAM_MODEL_UPDATE_MIN_CHECK_INTERVAL_SECONDS`	Minimum check interval per channel (seconds)	`300`	`CHANNEL_UPSTREAM_MODEL_UPDATE_MIN_CHECK_INTERVAL_SECONDS=600`

Model and Request Processing Configuration

Environment Variable	Description	Default Value	Example
`FORCE_STREAM_OPTION`	Override client stream_options parameter, force retrieval of streaming usage information	`true`	`FORCE_STREAM_OPTION=false`
`CountToken`	Whether to enable local token counting	`true`	`CountToken=false`
`GET_MEDIA_TOKEN`	Whether to count image/audio tokens in streaming mode	`true`	`GET_MEDIA_TOKEN=false`
`GET_MEDIA_TOKEN_NOT_STREAM`	Whether to count image/audio tokens in non-streaming mode	`false`	`GET_MEDIA_TOKEN_NOT_STREAM=true`

Asynchronous Task Configuration

Environment Variable	Description	Default Value	Example
`UPDATE_TASK`	Whether to enable asynchronous task polling updates (MJ, Suno, etc.)	`true`	`UPDATE_TASK=false`
`TASK_QUERY_LIMIT`	Maximum number of tasks queried per poll	`1000`	`TASK_QUERY_LIMIT=500`
`TASK_TIMEOUT_MINUTES`	Asynchronous task timeout (minutes), marked as failed and refunded after timeout, 0 to disable	`1440`	`TASK_TIMEOUT_MINUTES=720`
`TASK_PRICE_PATCH`	Task price patch, specified models are billed per-use only, model names separated by English commas	-	`TASK_PRICE_PATCH=sora-2,sora-2-pro`

Specific Model Configuration

Environment Variable	Description	Default Value	Example
`AZURE_DEFAULT_API_VERSION`	Azure channel default API version	`2025-04-01-preview`	`AZURE_DEFAULT_API_VERSION=2023-05-15`
`COHERE_SAFETY_SETTING`	Cohere model safety setting	`NONE`	`COHERE_SAFETY_SETTING=CONTEXTUAL`
`DIFY_DEBUG`	Dify channel output workflow and node information	`true`	`DIFY_DEBUG=false`

Subscription Cache Configuration

Environment Variable	Description	Default Value	Example
`SUBSCRIPTION_PLAN_CACHE_TTL`	Subscription plan cache TTL (seconds)	`300`	`SUBSCRIPTION_PLAN_CACHE_TTL=600`
`SUBSCRIPTION_PLAN_INFO_CACHE_TTL`	Subscription plan details cache TTL (seconds)	`120`	`SUBSCRIPTION_PLAN_INFO_CACHE_TTL=300`
`SUBSCRIPTION_PLAN_CACHE_CAP`	Subscription plan cache maximum capacity	`5000`	`SUBSCRIPTION_PLAN_CACHE_CAP=10000`
`SUBSCRIPTION_PLAN_INFO_CACHE_CAP`	Subscription plan details cache maximum capacity	`10000`	`SUBSCRIPTION_PLAN_INFO_CACHE_CAP=20000`

Other Configuration

Environment Variable	Description	Default Value	Example
`ERROR_LOG_ENABLED`	Whether to log and display error logs on the frontend	`false`	`ERROR_LOG_ENABLED=true`

Analytics and Statistics

Environment Variable	Description	Default Value	Example
`UMAMI_WEBSITE_ID`	Umami Website ID	-	`UMAMI_WEBSITE_ID=xxxx-xxxx`
`UMAMI_SCRIPT_URL`	Umami Script URL	`https://analytics.umami.is/script.js`	`UMAMI_SCRIPT_URL=https://umami.example.com/script.js`
`GOOGLE_ANALYTICS_ID`	Google Analytics 4 Website ID	-	`GOOGLE_ANALYTICS_ID=G-XXXXXXX`

Metadata Synchronization

Environment Variable	Description	Default Value	Example
`SYNC_UPSTREAM_BASE`	Model/Vendor Metadata Upstream Address	`https://basellm.github.io/llm-metadata`	`SYNC_UPSTREAM_BASE=https://mirror.example.com/llm-metadata`
`SYNC_HTTP_TIMEOUT_SECONDS`	Sync HTTP Timeout (seconds)	`10`	`SYNC_HTTP_TIMEOUT_SECONDS=15`
`SYNC_HTTP_RETRY`	Sync Retry Count	`3`	`SYNC_HTTP_RETRY=5`
`SYNC_HTTP_MAX_MB`	Max Response Body Size (MB)	`10`	`SYNC_HTTP_MAX_MB=20`

Frontend Configuration

Environment Variable	Description	Default Value	Example
`VITE_REACT_APP_SERVER_URL`	Frontend base URL for backend requests (effective at compile time)	-	`VITE_REACT_APP_SERVER_URL=https://api.example.com`

Compile-time Variables

VITE_REACT_APP_SERVER_URL is a frontend variable injected by Vite at compile time, only effective during frontend build, cannot be modified at runtime.

Pyroscope Continuous Performance Analysis

Environment Variable	Description	Default Value	Example
`PYROSCOPE_URL`	Pyroscope server address, leave blank to disable	-	`PYROSCOPE_URL=http://pyroscope:4040`
`PYROSCOPE_APP_NAME`	Application name for reporting	`new-api`	`PYROSCOPE_APP_NAME=my-api`
`PYROSCOPE_BASIC_AUTH_USER`	Pyroscope Basic Auth username	-	`PYROSCOPE_BASIC_AUTH_USER=admin`
`PYROSCOPE_BASIC_AUTH_PASSWORD`	Pyroscope Basic Auth password	-	`PYROSCOPE_BASIC_AUTH_PASSWORD=secret`
`HOSTNAME`	Hostname label for reporting	`new-api`	`HOSTNAME=node-1`
`PYROSCOPE_MUTEX_RATE`	Mutex profiling sample rate	`5`	`PYROSCOPE_MUTEX_RATE=10`
`PYROSCOPE_BLOCK_RATE`	Block profiling sample rate	`5`	`PYROSCOPE_BLOCK_RATE=10`

LinuxDo OAuth

No modification is required under normal circumstances.

Environment Variable	Description	Default Value	Example
`LINUX_DO_TOKEN_ENDPOINT`	LinuxDo Token Endpoint	`https://connect.linux.do/oauth2/token`	`LINUX_DO_TOKEN_ENDPOINT=https://connect.linux.do/oauth2/token`
`LINUX_DO_USER_ENDPOINT`	LinuxDo User Endpoint	`https://connect.linux.do/api/user`	`LINUX_DO_USER_ENDPOINT=https://connect.linux.do/api/user`

Environment Variable	Description	Default Value	Example
`DEBUG`	Enable debug mode (including GORM debug output)	`false`	`DEBUG=true`
`GIN_MODE`	Gin running mode	`release`	`GIN_MODE=debug`
`ENABLE_PPROF`	Enable pprof performance analysis (port 8005)	`false`	`ENABLE_PPROF=true`

Deprecated Environment Variables

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

Environment Variable	Alternative Method
`GEMINI_MODEL_MAP`	Please set in System Settings - Model Related Settings
`GEMINI_SAFETY_SETTING`	Please set in System Settings - Model Related Settings
`GEMINI_VISION_MAX_IMAGE_NUM`	Please set in System Settings - Model Related Settings

Multi-machine Deployment Example

In multi-machine deployment scenarios, the following environment variables must be set:

Master Node Configuration

# Database Configuration - Use a 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 secret as the master node
SESSION_SECRET=your_unique_session_secret
CRYPTO_SECRET=your_unique_crypto_secret

# Redis Cache Configuration - Use the same Redis as the 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: Synchronization Frequency
SYNC_FREQUENCY=60

Complete Cluster Configuration

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

Environment Variable 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 setting options, please refer to the Docker Compose Configuration Instructions document.

Environment Variable Configuration Guide

On this page