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`)	PostgreSQL (recommended): `SQL_DSN=postgresql://root:123456@postgres:5432/new-api` \| MySQL: `SQL_DSN=root:123456@tcp(localhost:3306)/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=postgresql://root:123456@postgres:5432/oneapi_logs`
`SQLITE_PATH`	SQLite database path	`one-api.db`	`SQLITE_PATH=/var/lib/new-api/new-api.db`

Database recommendation

PostgreSQL is preferred for production. MySQL remains a compatible option; SQLite, used when SQL_DSN is unset, is better suited to local development and testing.

Cache Configuration

Environment Variable	Description	Default Value	Example
`REDIS_CONN_STRING`	One Redis-compatible connection endpoint; include credentials in the URI	-	`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 synchronization frequency and maximum Session-cache stale window with independent Redis (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`

REDIS_CONN_STRING must point to one Redis-compatible endpoint. New API does not natively parse Redis Cluster or Sentinel node lists. For Redis high availability, use a managed service or proxy that exposes one compatible endpoint.

The database is authoritative for dashboard Sessions. Redis caches each Session for the smaller of its remaining lifetime and the effective SYNC_FREQUENCY, and reads do not renew that TTL. With independent Redis per node, Session revocation and version changes therefore converge after a database fallback within this window. Delayed active-cache fills keep only the unused portion of their original database-observation window.

Multi-node and Security Configuration

Environment Variable	Description	Default Value	Example
`SESSION_SECRET`	Session secret; must be identical on every application node	-	`SESSION_SECRET=your_session_secret`
`CRYPTO_SECRET`	HMAC secret for cache keys; nodes sharing Redis must use the same effective value	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-newapi-domain>`
`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.

Redis Topology

Redis may be shared by all nodes, deployed independently per node, or omitted. Shared Redis normally propagates Session revocation immediately and shares Redis-backed rate-limit quotas. Independent Redis converges within the effective SYNC_FREQUENCY, but each node has a separate rate-limit quota. Without Redis, Session validation reads the database and rate limiting uses node-local memory.

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

Multi-machine deployments must use the same database and the same SESSION_SECRET. Redis may be shared by all nodes, deployed independently per node, or omitted; see the Cluster Deployment Guide for the behavioral differences.

Master Node Configuration

# Database Configuration - Use a remote database
SQL_DSN=postgresql://newapi:password@db-server:5432/oneapi

# Security Configuration
SESSION_SECRET=your_unique_session_secret
CRYPTO_SECRET=your_unique_crypto_secret

# Redis Cache Configuration (may instead use a node-local Redis, or be omitted)
REDIS_CONN_STRING=redis://default:password@redis-server:6379

Slave Node Configuration

# Database Configuration - Use the same remote database
SQL_DSN=postgresql://newapi:password@db-server:5432/oneapi

# Security Configuration - SESSION_SECRET must match the master
SESSION_SECRET=your_unique_session_secret
CRYPTO_SECRET=your_unique_crypto_secret # Must match when Redis is shared

# Redis Cache Configuration - May match the master or point to this node's independent Redis
REDIS_CONN_STRING=redis://default:password@redis-slave-node:6379

# Node Type Setting
NODE_TYPE=slave

# Optional: Frontend Base URL
# FRONTEND_BASE_URL=https://<your-newapi-domain>

# Optional: Synchronization Frequency
SYNC_FREQUENCY=60

Complete Cluster Configuration

This example shows independent Redis instances. To share Redis, use the same REDIS_CONN_STRING on both nodes. Without Redis, Session validation reads the shared database directly. For complete consistency semantics and deployment guidance, see 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=postgresql://newapi:123456@postgres:5432/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