Documentation renewed! For old docs, visit doc.newapi.pro
New APINew API
User GuideInstallationAPI ReferenceAI ApplicationsHelp & SupportBusiness Cooperation

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 the .env file. Please refer to the .env.example file and rename it to .env when using it.

Basic Configuration

Environment VariableDescriptionDefault ValueExample
PORTService listening port3000PORT=8080
TZTime zone setting-TZ=America/New_York
VERSIONOverride running version number-VERSION=1.2.3

Database Configuration

Environment VariableDescriptionDefault ValueExample
SQL_DSNDatabase connection stringSQLite (data/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_CONNSMaximum number of idle connections in the connection pool100SQL_MAX_IDLE_CONNS=50
SQL_MAX_OPEN_CONNSMaximum number of open connections in the connection pool1000SQL_MAX_OPEN_CONNS=500
SQL_MAX_LIFETIMEMaximum connection lifetime (minutes)60SQL_MAX_LIFETIME=120
LOG_SQL_DSNSeparate database connection string for log table-LOG_SQL_DSN=root:123456@tcp(localhost:3306)/oneapi_logs
SQLITE_PATHSQLite database path/path/to/sqlite.dbSQLITE_PATH=/var/lib/new-api/new-api.db

Cache Configuration

Environment VariableDescriptionDefault ValueExample
REDIS_CONN_STRINGRedis connection string-REDIS_CONN_STRING=redis://default:redispw@localhost:6379
MEMORY_CACHE_ENABLEDWhether to enable in-memory cachefalseMEMORY_CACHE_ENABLED=true
REDIS_POOL_SIZERedis connection pool size10REDIS_POOL_SIZE=20
BATCH_UPDATE_ENABLEDEnable database batch update aggregationfalseBATCH_UPDATE_ENABLED=true
BATCH_UPDATE_INTERVALBatch update aggregation interval (seconds)5BATCH_UPDATE_INTERVAL=10

Multi-node and Security Configuration

Environment VariableDescriptionDefault ValueExample
SESSION_SECRETSession secret (required for multi-machine deployment)-SESSION_SECRET=random_string
CRYPTO_SECRETEncryption key (for encrypting database content)-CRYPTO_SECRET=your_crypto_secret
FRONTEND_BASE_URLFrontend base URL-FRONTEND_BASE_URL=https://your-domain.com
SYNC_FREQUENCYCache and database synchronization frequency (seconds)60SYNC_FREQUENCY=60
NODE_TYPENode typemasterNODE_TYPE=slave

Cluster Deployment

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

User and Token Configuration

Environment VariableDescriptionDefault ValueExample
GENERATE_DEFAULT_TOKENGenerate initial token for new registered usersfalseGENERATE_DEFAULT_TOKEN=true
NOTIFICATION_LIMIT_DURATION_MINUTENotification limit duration (minutes)10NOTIFICATION_LIMIT_DURATION_MINUTE=15
NOTIFY_LIMIT_COUNTMaximum number of notifications within the specified duration2NOTIFY_LIMIT_COUNT=3

Request Limit Configuration

Environment VariableDescriptionDefault ValueExample
GLOBAL_API_RATE_LIMITGlobal API rate limit (per IP, three minutes)180GLOBAL_API_RATE_LIMIT=100
GLOBAL_WEB_RATE_LIMITGlobal Web rate limit (per IP, three minutes)60GLOBAL_WEB_RATE_LIMIT=30
RELAY_TIMEOUTRelay request timeout (seconds)0RELAY_TIMEOUT=60
STREAMING_TIMEOUTStreaming single response timeout (seconds)300STREAMING_TIMEOUT=120
MAX_FILE_DOWNLOAD_MBMaximum file download size (MB)20MAX_FILE_DOWNLOAD_MB=50
GLOBAL_API_RATE_LIMIT_ENABLEGlobal API rate limit switchtrueGLOBAL_API_RATE_LIMIT_ENABLE=false
GLOBAL_API_RATE_LIMIT_DURATIONGlobal API rate limit window (seconds)180GLOBAL_API_RATE_LIMIT_DURATION=120
GLOBAL_WEB_RATE_LIMIT_ENABLEGlobal Web rate limit switchtrueGLOBAL_WEB_RATE_LIMIT_ENABLE=false
GLOBAL_WEB_RATE_LIMIT_DURATIONGlobal Web rate limit window (seconds)180GLOBAL_WEB_RATE_LIMIT_DURATION=120
CRITICAL_RATE_LIMIT_ENABLECritical operation rate limit switchtrueCRITICAL_RATE_LIMIT_ENABLE=false
CRITICAL_RATE_LIMITCritical operation rate limit count20CRITICAL_RATE_LIMIT=10
CRITICAL_RATE_LIMIT_DURATIONCritical operation rate limit window (seconds)1200CRITICAL_RATE_LIMIT_DURATION=600

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 was not completed due to timeout

  • Causing billing discrepancies, which may lead to system losses

  • It is recommended not to set it unless you know what you are doing

Channel Management Configuration

Environment VariableDescriptionDefault ValueExample
CHANNEL_UPDATE_FREQUENCYRegularly update channel balance (minutes)-CHANNEL_UPDATE_FREQUENCY=1440
CHANNEL_TEST_FREQUENCYRegularly check channels (minutes)-CHANNEL_TEST_FREQUENCY=1440
POLLING_INTERVALRequest interval when batch updating channels (seconds)0POLLING_INTERVAL=5
ENABLE_METRICWhether to disable channels based on request success ratefalseENABLE_METRIC=true
METRIC_QUEUE_SIZERequest success rate statistics queue size10METRIC_QUEUE_SIZE=20
METRIC_SUCCESS_RATE_THRESHOLDRequest success rate threshold0.8METRIC_SUCCESS_RATE_THRESHOLD=0.7
TEST_PROMPTUser prompt when testing modelsPrint your model name exactly...TEST_PROMPT=Hello

Model and Request Processing Configuration

Environment VariableDescriptionDefault ValueExample
FORCE_STREAM_OPTIONOverride client stream_options parametertrueFORCE_STREAM_OPTION=false
GET_MEDIA_TOKENWhether to count image tokenstrueGET_MEDIA_TOKEN=false
GET_MEDIA_TOKEN_NOT_STREAMWhether to count image tokens in non-streaming modefalseGET_MEDIA_TOKEN_NOT_STREAM=false
UPDATE_TASKWhether to update asynchronous tasks (MJ, Suno)trueUPDATE_TASK=false
CountTokenWhether to count text tokenstrueCountToken=false
TASK_PRICE_PATCHTask price patch (comma-separated)""TASK_PRICE_PATCH=suno=0.8,mj=1.2

Specific Model Configuration

Environment VariableDescriptionDefault ValueExample
AZURE_DEFAULT_API_VERSIONAzure channel default API version2025-04-01-previewAZURE_DEFAULT_API_VERSION=2023-05-15
COHERE_SAFETY_SETTINGCohere model safety settingNONECOHERE_SAFETY_SETTING=CONTEXTUAL
GEMINI_VISION_MAX_IMAGE_NUMGemini model maximum image count16GEMINI_VISION_MAX_IMAGE_NUM=8
DIFY_DEBUGDify channel output workflow and node informationtrueDIFY_DEBUG=false

Other Configuration

Environment VariableDescriptionDefault ValueExample
ERROR_LOG_ENABLEDWhether to log and display error logs on the frontendfalseERROR_LOG_ENABLED=true

Analytics and Statistics

Environment VariableDescriptionDefault ValueExample
UMAMI_WEBSITE_IDUmami Website ID-UMAMI_WEBSITE_ID=xxxx-xxxx
UMAMI_SCRIPT_URLUmami Script URLhttps://analytics.umami.is/script.jsUMAMI_SCRIPT_URL=https://umami.example.com/script.js
GOOGLE_ANALYTICS_IDGoogle Analytics Site ID-GOOGLE_ANALYTICS_ID=G-XXXXXXX

Metadata Synchronization

Environment VariableDescriptionDefault ValueExample
SYNC_UPSTREAM_BASEModel/Vendor metadata upstream addresshttps://basellm.github.io/llm-metadataSYNC_UPSTREAM_BASE=https://mirror.example.com/llm-metadata
SYNC_HTTP_TIMEOUT_SECONDSSync HTTP timeout (seconds)10SYNC_HTTP_TIMEOUT_SECONDS=15
SYNC_HTTP_RETRYSync retry count3SYNC_HTTP_RETRY=5
SYNC_HTTP_MAX_MBMaximum response body size (MB)10SYNC_HTTP_MAX_MB=20

Frontend Configuration

Environment VariableDescriptionDefault ValueExample
VITE_REACT_APP_SERVER_URLFrontend request backend base address-VITE_REACT_APP_SERVER_URL=https://api.example.com

Deprecated Environment Variables

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

Environment VariableAlternative Method
GEMINI_MODEL_MAPPlease set in System Settings - Model Related Settings
GEMINI_SAFETY_SETTINGPlease set in System Settings - Model Related Settings

Multi-machine Deployment Example

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

Master Node Configuration

# 数据库配置 - 使用远程数据库
SQL_DSN=root:password@tcp(db-server:3306)/oneapi

# 安全配置
SESSION_SECRET=your_unique_session_secret
CRYPTO_SECRET=your_unique_crypto_secret

# Redis缓存配置
REDIS_CONN_STRING=redis://default:password@redis-server:6379

Slave Node Configuration

# 数据库配置 - 使用相同的远程数据库
SQL_DSN=root:password@tcp(db-server:3306)/oneapi

# 安全配置 - 与主节点使用相同的密钥
SESSION_SECRET=your_unique_session_secret
CRYPTO_SECRET=your_unique_crypto_secret

# Redis缓存配置 - 与主节点使用相同的Redis
REDIS_CONN_STRING=redis://default:password@redis-server:6379

# 节点类型设置
NODE_TYPE=slave

# 可选：前端基础URL
FRONTEND_BASE_URL=https://your-domain.com

# 可选：同步频率
SYNC_FREQUENCY=60

Full Cluster Configuration

This is just a basic multi-node configuration example. For complete cluster deployment configuration, architectural descriptions, 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 complete Docker Compose configuration, including more environment variable setting options, please refer to the Docker Compose Configuration Instructions document.

No modification is required under normal circumstances

Environment VariableDescriptionDefault ValueExample
LINUX_DO_TOKEN_ENDPOINTLinuxDo Token Endpointhttps://connect.linux.do/oauth2/tokenLINUX_DO_TOKEN_ENDPOINT=https://connect.linux.do/oauth2/token
LINUX_DO_USER_ENDPOINTLinuxDo User Endpointhttps://connect.linux.do/api/userLINUX_DO_USER_ENDPOINT=https://connect.linux.do/api/user
Environment VariableDescriptionDefault ValueExample
ENABLE_PPROFEnable pprof performance analysisfalseENABLE_PPROF=true
DEBUGEnable debug modefalseDEBUG=true
GIN_MODEGin running mode-GIN_MODE=release

How is this guide?

Last updated on

System Update Guide

Previous Page

Docker Compose Configuration Guide

Next Page

On this page

Basic Configuration
Database Configuration
Cache Configuration
Multi-node and Security Configuration
User and Token Configuration
Request Limit Configuration
Channel Management Configuration
Model and Request Processing Configuration
Specific Model Configuration
Other Configuration
Analytics and Statistics
Metadata Synchronization
Frontend Configuration
Deprecated Environment Variables
Multi-machine Deployment Example
Master Node Configuration
Slave Node Configuration
Environment Variable Example in Docker Compose
LinuxDo Related
Debugging Related