New API

https://docs.newapi.pro/zh/docs
Admin
New API is a next-generation AI gateway and asset management system that offers various deployment...
Tokens:157,643
Snippets:1,247
Trust Score:4.8
Update:1 month ago
Show doc for...
Tokens:
Raw
### Verify Node.js and npm Installation

Source: https://docs.newapi.pro/zh/docs/apps/claude-code

Verifies Node.js and npm installation on Windows. Run in PowerShell or CMD; if version numbers are displayed, the installation was successful.

```bash
node --version
npm --version
```

--------------------------------

### Install newapi-skills with npx

Source: https://docs.newapi.pro/zh/docs/skills/newapi

Installs the newapi skill from the QuantumNous/skills repository. Run this command in your terminal to add the skill to your editor environment.

```bash
npx skills add https://github.com/QuantumNous/skills --skill newapi
```

--------------------------------

### Install CC Switch on macOS via Homebrew

Source: https://docs.newapi.pro/zh/docs/apps/cc-switch

Install CC Switch on macOS using Homebrew. Run these commands in order to tap the repository and install the cask.

```bash
brew tap farion1231/ccswitch
brew install --cask cc-switch
```

--------------------------------

### Install CC Switch on Arch Linux via paru

Source: https://docs.newapi.pro/zh/docs/apps/cc-switch

Install CC Switch on Arch Linux using the paru AUR helper.

```bash
paru -S cc-switch-bin
```

--------------------------------

### Start Droid CLI in a Specific Project (Windows)

Source: https://docs.newapi.pro/zh/docs/apps/factory-droid-cli

Navigates to a specific project directory and starts Droid CLI there. Press Enter to launch; requires a free official account login.

```bash
# 进入你的项目目录
cd C:\path\to\your\project

# 启动 Droid CLI
droid
```

--------------------------------

### Start Droid CLI

Source: https://docs.newapi.pro/zh/docs/apps/factory-droid-cli

Starts the Droid CLI interactive session in the current directory. Press Enter to launch; requires a free official account login.

```bash
droid
```

--------------------------------

### Start Droid CLI in a Specific Project (macOS/Linux)

Source: https://docs.newapi.pro/zh/docs/apps/factory-droid-cli

Navigates to a specific project directory and starts Droid CLI there. Press Enter to launch; requires a free official account login.

```bash
# 进入你的项目目录
cd /path/to/your/project

# 启动 Droid CLI
droid
```

--------------------------------

### GET /api/log/

Source: https://docs.newapi.pro/zh/docs/guide/feature-guide/user/log

管理员接口，用于查询通用日志。受认证和权限限制，普通用户结果强制限定为当前账号。时间参数单位为秒（created_at）。

```APIDOC
## GET /api/log/

### Description
管理员接口，用于查询通用日志。受认证和权限限制，普通用户结果强制限定为当前账号。

### Method
GET

### Endpoint
/api/log/

### Parameters
#### Query Parameters
- **p** (integer) - Optional - 页码，从 1 开始。
- **page_size** (integer) - Optional - 每页数量，超过 100 会被截为 100。

### Response
#### Success Response (200)
- **logs** (array) - 日志列表。

#### Response Example
{
  "logs": []
}
```

--------------------------------

### Docker Compose environment variables for new-api service

Source: https://docs.newapi.pro/zh/docs/installation/config-maintenance/environment-variables

Sets environment variables for the new-api service in Docker Compose, including timezone, database connection, Redis, session and crypto secrets, cache and token generation flags, and timeouts. Use this as a starting point for configuring the service; refer to the Docker Compose configuration documentation for additional options.

```yaml
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
```

--------------------------------

### cURL request for GET /v1/fine-tunes/{fine_tune_id}/events

Source: https://docs.newapi.pro/zh/docs/api/ai-model/unimplemented/fine-tuning/listfinetuneevents

Sends a GET request to the unimplemented endpoint /v1/fine-tunes/{fine_tune_id}/events. The path parameter fine_tune_id is replaced with the literal string "string" in the example. Requires Bearer Token authentication in the Authorization header.

```cURL
curl -X GET "https://docs.newapi.pro/v1/fine-tunes/string/events"
```

--------------------------------

### GET /api/setup

Source: https://docs.newapi.pro/zh/docs/api/management/system/setup-get

获取系统的初始化状态。该接口无需鉴权，直接调用即可。

```APIDOC
## GET /api/setup

### Description
获取系统的初始化状态。该接口无需鉴权。

### Method
GET

### Endpoint
/api/setup

### Request Example
```
curl -X GET "https://docs.newapi.pro/api/setup"
```

### Response
#### Success Response (200)
Empty

```

--------------------------------

### 创建 .env 配置文件

Source: https://docs.newapi.pro/zh/docs/installation/deployment-methods/local-development

从 .env.example 复制生成 .env 文件，用于配置环境变量。

```bash
cp .env.example .env
```

--------------------------------

### Retrieve fine-tune details with cURL

Source: https://docs.newapi.pro/zh/docs/api/ai-model/unimplemented/fine-tuning/retrievefinetune

Sends a GET request to the unimplemented fine-tuning endpoint. The path parameter fine_tune_id is replaced with the literal string 'string' in the example URL.

```bash
curl -X GET "https://docs.newapi.pro/v1/fine-tunes/string"
```

--------------------------------

### Initialize System with cURL

Source: https://docs.newapi.pro/zh/docs/api/management/system/setup-post

Initializes the system by sending a POST request to the /api/setup endpoint. The request body is empty by default, but optional username and password fields can be provided. No authentication is required for this endpoint.

```cURL
curl -X POST "https://docs.newapi.pro/api/setup" \  -H "Content-Type: application/json" \  -d '{}'
```

--------------------------------

### Verify Claude Code Installation on Windows

Source: https://docs.newapi.pro/zh/docs/apps/claude-code

Verifies Claude Code installation on Windows. If a version number is displayed, the installation was successful.

```bash
claude --version
```

--------------------------------

### Verify Git Bash Installation

Source: https://docs.newapi.pro/zh/docs/apps/claude-code

Verifies Git Bash installation on Windows. Run in Git Bash; if a version number is displayed, the installation was successful.

```bash
git --version
```

--------------------------------

### POST /api/setup

Source: https://docs.newapi.pro/zh/docs/api/management/system/setup-post

初始化系统，用于首次部署时设置管理员账号。无需鉴权，请求体包含可选的用户名和密码。

```APIDOC
## POST /api/setup

### Description
初始化系统，用于首次部署时设置管理员账号。无需鉴权。

### Method
POST

### Endpoint
/api/setup

### Parameters
#### Request Body
- **username** (string) - Optional - 管理员用户名
- **password** (string) - Optional - 管理员密码

### Request Example
```json
{}
```

### Response
#### Success Response (200)
Empty

#### Response Example
```json
{}
```
```

--------------------------------

### 开发环境常用配置

Source: https://docs.newapi.pro/zh/docs/installation/deployment-methods/local-development

编辑 .env 文件，设置端口和数据库连接。默认使用 SQLite，如需 PostgreSQL 或 Redis 请取消注释并修改。

```bash
PORT=3000
# SQL_DSN=postgresql://newapi:password@localhost:5432/new-api  # 推荐使用 PostgreSQL，取消注释并修改
# REDIS_CONN_STRING=redis://localhost:6379         # 如使用Redis，取消注释并修改
```

--------------------------------

### 运行引导向导

Source: https://docs.newapi.pro/zh/docs/apps/openclaw

运行 openclaw onboard 命令，完成基础认证、Gateway 设置以及可选的渠道初始化。

```bash
openclaw onboard --install-daemon
```

--------------------------------

### POST /api/user/2fa/setup

Source: https://docs.newapi.pro/zh/docs/api/management/two-factor-auth/user-2fa-setup-post

Documentation for the POST /api/user/2fa/setup endpoint that enables two-factor authentication for the authenticated user.

```APIDOC
## [POST] /api/user/2fa/setup

### Description
Sets up two-factor authentication (2FA) for the authenticated user. This endpoint requires a logged-in user with User permissions.

### Method
POST

### Endpoint
/api/user/2fa/setup

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```
curl -X POST "https://docs.newapi.pro/api/user/2fa/setup"
```

### Response
#### Success Response (200)
Empty response body.

#### Response Example
```
(empty)
```
```

--------------------------------

### GET /api/oauth/state

Source: https://docs.newapi.pro/zh/docs/api/management/oauth/oauth-state-get

生成 OAuth State。该接口无需鉴权，通过 GET 请求即可获取 OAuth 状态标识。

```APIDOC
## [GET] /api/oauth/state

### Description
生成 OAuth State。该接口无需鉴权，通过 GET 请求即可获取 OAuth 状态标识。

### Method
GET

### Endpoint
/api/oauth/state

### Request Example

curl -X GET "https://docs.newapi.pro/api/oauth/state"


### Response
#### Success Response (200)
Empty

```

--------------------------------

### 创建 docker-compose.yml 文件

Source: https://docs.newapi.pro/zh/docs/installation/deployment-methods/docker-compose-installation

使用文本编辑器创建 docker-compose.yml 文件。将选择的配置内容复制到该文件中，并根据需要进行自定义修改。

```bash
# 使用nano编辑器
nano docker-compose.yml

# 或使用vim编辑器
vim docker-compose.yml
```

--------------------------------

### Start Claude Code on Windows

Source: https://docs.newapi.pro/zh/docs/apps/claude-code

Starts Claude Code directly in PowerShell on Windows.

```bash
claude
```

--------------------------------

### Install Claude Code CLI on macOS

Source: https://docs.newapi.pro/zh/docs/apps/claude-code

Installs Claude Code CLI on macOS. Run in Terminal.

```bash
curl -fsSL https://claude.ai/install.sh | bash
```

--------------------------------

### 安装前端依赖

Source: https://docs.newapi.pro/zh/docs/installation/deployment-methods/local-development

进入 web 目录并使用 bun install 安装前端依赖。

```bash
cd web
bun install   # 使用 bun 安装前端依赖
```

--------------------------------

### GET /v1/fine-tunes/{fine_tune_id}/events

Source: https://docs.newapi.pro/zh/docs/api/ai-model/unimplemented/fine-tuning/listfinetuneevents

Documentation for the GET /v1/fine-tunes/{fine_tune_id}/events endpoint, which is marked as not implemented.

```APIDOC
## GET /v1/fine-tunes/{fine_tune_id}/events

### Description
Retrieves the events for a fine-tuning job. This endpoint is currently not implemented.

### Method
GET

### Endpoint
`/v1/fine-tunes/{fine_tune_id}/events`

### Parameters
#### Path Parameters
- **fine_tune_id** (string) - Required - The ID of the fine-tuning job.

#### Authorization
- **Authorization** (header) - Required - Bearer Token. Format: `Authorization: Bearer sk-xxxxxx`

### Response
#### Success Response (200)
- **error** (object) - Error object containing details.
  - **message** (string) - Error message.
  - **type** (string) - Error type.
  - **param** (string) - Error parameter.
  - **code** (string) - Error code.

#### Response Example
```json
{
  "error": {
    "message": "string",
    "type": "string",
    "param": "string",
    "code": "string"
  }
}
```

### Notes
- This endpoint is not implemented and returns HTTP 501 Not Implemented.
```

--------------------------------

### POST /api/user/passkey/login/begin

Source: https://docs.newapi.pro/zh/docs/api/management/user-auth/user-passkey-login-begin-post

开始Passkey登录流程，无需鉴权。该端点用于初始化WebAuthn认证，响应体包含认证所需的挑战数据。

```APIDOC
## POST /api/user/passkey/login/begin

### Description
开始Passkey登录流程。此端点无需鉴权，用于初始化WebAuthn认证，返回认证所需的挑战数据。

### Method
POST

### Endpoint
https://docs.newapi.pro/api/user/passkey/login/begin

### Response
#### Success Response (200)
- 响应体为空（Empty）

#### Response Example
（响应体为空，无示例）

```

--------------------------------

### Install Claude Code on Linux with sudo

Source: https://docs.newapi.pro/zh/docs/apps/claude-code

Installs Claude Code on Linux with sudo if permission issues are encountered.

```bash
sudo curl -fsSL https://claude.ai/install.sh | bash
```

--------------------------------

### GET /api/oauth/linuxdo with cURL

Source: https://docs.newapi.pro/zh/docs/api/management/oauth/oauth-linuxdo-get

Sends a GET request to the LinuxDO OAuth callback endpoint. No authentication is required for this endpoint.

```bash
curl -X GET "https://docs.newapi.pro/api/oauth/linuxdo"
```

--------------------------------

### 使用 Git 克隆项目并编辑 docker-compose.yml

Source: https://docs.newapi.pro/zh/docs/installation/deployment-methods/docker-compose-installation

克隆 New API 项目并进入目录，然后编辑 docker-compose.yml 文件。项目自带的 docker-compose.yml 已按推荐方案配置 PostgreSQL 和 Redis，只需根据实际情况修改端口、密码等参数即可使用。

```bash
# 下载项目源码
git clone https://github.com/QuantumNous/new-api.git

# 进入项目目录
cd new-api

# 根据需要编辑 docker-compose.yml 文件
# 使用nano编辑器
nano docker-compose.yml
# 或使用vim编辑器
# vim docker-compose.yml
```

--------------------------------

### Docker 检查环境变量命令

Source: https://docs.newapi.pro/zh/docs/guide/wiki/basic-concepts/analytics-setup

使用 docker exec 检查容器内是否设置了 Google Analytics 和 Umami 环境变量。

```bash
# 检查环境变量是否设置
docker exec new-api env | grep -E "GOOGLE_ANALYTICS|UMAMI"
```

--------------------------------

### Install Factory Droid CLI on macOS/Linux

Source: https://docs.newapi.pro/zh/docs/apps/factory-droid-cli

One-line command to install Factory Droid CLI on macOS/Linux. Run in a terminal.

```bash
curl -fsSL https://app.factory.ai/cli | sh
```

--------------------------------

### Docker 检查性能分析环境变量

Source: https://docs.newapi.pro/zh/docs/guide/wiki/basic-concepts/performance-analysis

使用 docker exec 命令检查容器内与 PPROF 和 PYROSCOPE 相关的环境变量，用于故障排除。

```bash
# Check env vars
docker exec new-api env | grep -E "PPROF|PYROSCOPE"
```

--------------------------------

### GET /api/status/test

Source: https://docs.newapi.pro/zh/docs/api/management/system/status-test-get

Tests the system status by sending a GET request to the specified endpoint. This endpoint requires administrator privileges.

```APIDOC
## GET /api/status/test

### Description
Tests the system status by sending a GET request to the specified endpoint. This endpoint requires administrator privileges.

### Method
GET

### Endpoint
`/api/status/test`

### Parameters
None

### Request Example
```
curl -X GET "https://docs.newapi.pro/api/status/test"
```

### Response
#### Success Response (200)
Empty response body.

#### Response Example
```
(empty)
```
```

--------------------------------

### Docker run with PostgreSQL

Source: https://docs.newapi.pro/zh/docs/installation/deployment-methods/docker-installation

Deploy New API with PostgreSQL, recommended for production. Replace the SQL_DSN credentials and /your/data/path with your own values.

```bash
docker run --name new-api -d --restart always \
  -p 3000:3000 \
  -e SQL_DSN="postgresql://用户名:密码@数据库地址:5432/数据库名" \
  -e TZ=Asia/Shanghai \
  -v /your/data/path:/data \
  calciumion/new-api:latest
```

--------------------------------

### Get enabled models with cURL

Source: https://docs.newapi.pro/zh/docs/api/management/channel-management/channel-models_enabled-get

Retrieves the list of enabled models for a channel. Requires administrator privileges. The endpoint is GET /api/channel/models_enabled.

```cURL
curl -X GET "https://docs.newapi.pro/api/channel/models_enabled"
```

--------------------------------

### 构建前端资源

Source: https://docs.newapi.pro/zh/docs/installation/deployment-methods/local-development

进入 web 目录并使用 bun run build 构建前端资源，输出到 web/dist 目录。

```bash
cd web
bun run build   # 使用 bun 构建前端资源
```

--------------------------------

### 启动 Docker Compose 服务

Source: https://docs.newapi.pro/zh/docs/installation/config-maintenance/docker-compose-yml

在包含 docker-compose.yml 文件的目录下运行此命令，以启动所有服务。

```bash
docker compose up -d
```

--------------------------------

### cURL example for POST /api/user/passkey/login/begin

Source: https://docs.newapi.pro/zh/docs/api/management/user-auth/user-passkey-login-begin-post

Use this cURL command to invoke the begin passkey login endpoint. It returns a 200 response with an empty body.

```cURL
curl -X POST "https://docs.newapi.pro/api/user/passkey/login/begin"
```

--------------------------------

### Install Linux Dependencies for Claude Code

Source: https://docs.newapi.pro/zh/docs/apps/claude-code

Installs additional dependencies for Claude Code on some Linux distributions. Use the appropriate command for your distribution.

```bash
# Ubuntu/Debian
sudo apt install build-essential

# CentOS/RHEL
sudo dnf groupinstall "Development Tools"
```

--------------------------------

### 启动 New API 服务

Source: https://docs.newapi.pro/zh/docs/installation/deployment-methods/docker-compose-installation

启动 New API 服务，该命令会自动拉取所需镜像并在后台启动服务。

```bash
# 使用Docker Compose启动服务
docker compose up -d
```

--------------------------------

### cURL request to GET /api/oauth/state

Source: https://docs.newapi.pro/zh/docs/api/management/oauth/oauth-state-get

Use this cURL command to call the unauthenticated GET /api/oauth/state endpoint. The response is 200 with an empty body.

```bash
curl -X GET "https://docs.newapi.pro/api/oauth/state"
```

--------------------------------

### Get top-up info with cURL

Source: https://docs.newapi.pro/zh/docs/api/management/payment/user-topup-info-get

Retrieves the user's top-up information. Requires login with User permission. The endpoint is GET /api/user/topup/info.

```cURL
curl -X GET "https://docs.newapi.pro/api/user/topup/info"
```

--------------------------------

### Docker run with MySQL

Source: https://docs.newapi.pro/zh/docs/installation/deployment-methods/docker-installation

Deploy New API with MySQL, which is still compatible. Replace the SQL_DSN credentials and /your/data/path with your own values.

```bash
docker run --name new-api -d --restart always \
  -p 3000:3000 \
  -e SQL_DSN="用户名:密码@tcp(数据库地址:3306)/数据库名" \
  -e TZ=Asia/Shanghai \
  -v /your/data/path:/data \
  calciumion/new-api:latest
```

--------------------------------

### Get All Logs with cURL

Source: https://docs.newapi.pro/zh/docs/api/management/logs/log-get

Retrieves all logs from the management API. Requires administrator privileges. The endpoint is GET /api/log/ and returns a list of logs.

```cURL
curl -X GET "https://docs.newapi.pro/api/log/"
```

--------------------------------

### Install Claude Code via npm

Source: https://docs.newapi.pro/zh/docs/apps/claude-code

Installs the latest version of Claude Code globally from the npm official repository. Run in PowerShell on Windows.

```bash
npm install -g @anthropic-ai/claude-code
```

--------------------------------

### 查看服务列表/状态

Source: https://docs.newapi.pro/zh/docs/installation/deployment-methods/docker-compose-installation

查看服务列表和状态。

```bash
docker compose ps
```

--------------------------------

### Get all top-up records with cURL

Source: https://docs.newapi.pro/zh/docs/api/management/user-management/user-topup-get

Retrieves all top-up records. Requires administrator privileges. The endpoint is GET /api/user/topup. The response body is empty when there are no records.

```cURL
curl -X GET "https://docs.newapi.pro/api/user/topup"
```

--------------------------------

### 标准Docker Compose配置（生产环境）

Source: https://docs.newapi.pro/zh/docs/installation/config-maintenance/docker-compose-yml

适用于生产环境的完整Docker Compose配置，包含new-api、redis和postgres服务，以及可选的mysql服务（注释状态）。使用前需修改默认密码。

```yaml
# New-API Docker Compose Configuration
#
# Quick Start:
#   1. docker-compose up -d
#   2. Access at http://localhost:3000
#
# Using MySQL instead of PostgreSQL:
#   1. Comment out the postgres service and SQL_DSN line 15
#   2. Uncomment the mysql service and SQL_DSN line 16
#   3. Uncomment mysql in depends_on (line 28)
#   4. Uncomment mysql_data in volumes section (line 64)
#
# ⚠️  IMPORTANT: Change all default passwords before deploying to production!

version: '3.4' # For compatibility with older Docker versions

services:
  new-api:
    image: calciumion/new-api:latest
    container_name: new-api
    restart: always
    command: --log-dir /app/logs
    ports:
      - '3000:3000'
    volumes:
      - ./data:/data
      - ./logs:/app/logs
    environment:
      - SQL_DSN=postgresql://root:123456@postgres:5432/new-api # ⚠️ IMPORTANT: Change the password in production!
      #      - SQL_DSN=root:123456@tcp(mysql:3306)/new-api  # Point to the mysql service, uncomment if using MySQL
      - REDIS_CONN_STRING=redis://redis
      - TZ=Asia/Shanghai
      - ERROR_LOG_ENABLED=true # 是否启用错误日志记录
      - BATCH_UPDATE_ENABLED=true # 是否启用批量更新 batch update enabled
    #      - STREAMING_TIMEOUT=300  # 流模式无响应超时时间，单位秒，默认120秒，如果出现空补全可以尝试改为更大值 Streaming timeout in seconds, default is 120s. Increase if experiencing empty completions
    #      - SESSION_SECRET=random_string  # 多机部署时设置，必须修改这个随机字符串！！ multi-node deployment, set this to a random string!!!!!!!
    #      - SYNC_FREQUENCY=60  # 缓存同步频率；独立 Redis 部署下也是 Session 最大陈旧窗口

    depends_on:
      - redis
      - postgres
    #      - mysql  # Uncomment if using MySQL
    healthcheck:
      test:
        [
          'CMD-SHELL',
          "wget -q -O - http://localhost:3000/api/status | grep -o '\"success\":\\s*true' || exit 1",
        ]
      interval: 30s
      timeout: 10s
      retries: 3

  redis:
    image: redis:latest
    container_name: redis
    restart: always

  postgres:
    image: postgres:15
    container_name: postgres
    restart: always
    environment:
      POSTGRES_USER: root
      POSTGRES_PASSWORD: 123456 # ⚠️ IMPORTANT: Change this password in production!
      POSTGRES_DB: new-api
    volumes:
      - pg_data:/var/lib/postgresql/data
#    ports:
#      - "5432:5432"  # Uncomment if you need to access PostgreSQL from outside Docker

#  mysql:
#    image: mysql:8.2
#    container_name: mysql
#    restart: always
#    environment:
#      MYSQL_ROOT_PASSWORD: 123456  # ⚠️ IMPORTANT: Change this password in production!
#      MYSQL_DATABASE: new-api
#    volumes:
#      - mysql_data:/var/lib/mysql
#    ports:
#      - "3306:3306"  # Uncomment if you need to access MySQL from outside Docker

volumes:
  pg_data:
#  mysql_data:
```

--------------------------------

### Get system status with cURL

Source: https://docs.newapi.pro/zh/docs/api/management/system/status-get

Sends a GET request to the /api/status endpoint without authentication. The response body is empty with a 200 status code.

```cURL
curl -X GET "https://docs.newapi.pro/api/status"
```

--------------------------------

### Start Claude Code in a Project on macOS

Source: https://docs.newapi.pro/zh/docs/apps/claude-code

Starts Claude Code in a specific project directory on macOS. Replace the path with your actual project path.

```bash
# 进入你的项目目录
cd /path/to/your/project

# 启动 Claude Code
claude
```

--------------------------------

### 查看指定服务日志

Source: https://docs.newapi.pro/zh/docs/installation/deployment-methods/docker-compose-installation

查看指定服务（如 new-api、postgres、redis）的实时日志。

```bash
docker compose logs -f new-api
docker compose logs -f postgres
docker compose logs -f redis
```
Tokens:
Raw