new-api Documentation

1. Project Overview & Quickstart (QuantumNous/new-api) Copy Chapter

File: constant/README.md Copy Chapter

constant 包 (`/constant`)

该目录仅用于放置全局可复用的常量定义，不包含任何业务逻辑或依赖关系。

当前文件 Copy Chapter

使用约定 Copy Chapter

1. constant 包只能被其他包引用（import），禁止在此包中引用项目内的其他自定义包。如确有需要，仅允许引用 Go 标准库。
2. 不允许在此目录内编写任何与业务流程、数据库操作、第三方服务调用等相关的逻辑代码。
3. 新增类型时，请保持命名语义清晰，并在本 README 的 当前文件 表格中补充说明，确保团队成员能够快速了解其用途。

⚠️ 违反以上约定将导致包之间产生不必要的耦合，影响代码可维护性与可测试性。请在提交代码前自行检查。

File: docs/installation/BT.md Copy Chapter

宝塔面板部署教程

本文档提供使用宝塔面板 Docker 功能部署 New API 的图文教程。

📖 官方文档：宝塔面板部署

前置要求 Copy Chapter

步骤一：安装宝塔面板 Copy Chapter

1. 前往 宝塔面板官网 下载适合您系统的安装脚本
2. 运行安装脚本安装宝塔面板
3. 安装完成后，使用提供的地址、用户名和密码登录宝塔面板

步骤二：安装 Docker Copy Chapter

1. 登录宝塔面板后，在左侧菜单栏找到并点击 Docker
2. 首次进入会提示安装 Docker 服务，点击 立即安装
3. 按照提示完成 Docker 服务的安装

步骤三：安装 New API Copy Chapter

方法一：使用宝塔应用商店（推荐） Copy Section

1. 在宝塔面板 Docker 功能中，点击 应用商店
2. 搜索并找到 New-API
3. 点击 安装
4. 配置以下基本选项：
   • 容器名称：可自定义，默认为 new-api
   • 端口映射：默认为 3000:3000
   • 环境变量：
     • SESSION_SECRET：会话密钥（必填，多机部署时必须一致）
     • CRYPTO_SECRET：加密密钥（使用 Redis 时必填）
5. 点击 确认 开始安装
6. 等待安装完成后，访问 http://您的服务器IP:3000 即可使用

方法二：使用 Docker Compose Copy Section

1. 在宝塔面板中创建网站目录，如 /www/wwwroot/new-api
2. 创建 docker-compose.yml 文件：

version: '3'
services:
  new-api:
    image: calciumion/new-api:latest
    container_name: new-api
    restart: always
    ports:
      - "3000:3000"
    volumes:
      - ./data:/data
    environment:
      - SESSION_SECRET=your_session_secret_here  # 请修改为随机字符串
      - TZ=Asia/Shanghai

1. 在终端中进入目录并启动：

cd /www/wwwroot/new-api
docker-compose up -d

配置说明 Copy Chapter

必要环境变量 Copy Section

生成随机密钥 Copy Section

# 生成 SESSION_SECRET
openssl rand -hex 16

# 或使用 Linux 命令
head -c 16 /dev/urandom | xxd -p

常见问题 Copy Chapter

Q1：无法访问 3000 端口？ Copy Section

1. 检查服务器防火墙是否开放 3000 端口
2. 在宝塔面板 安全 中放行 3000 端口
3. 检查云服务器安全组是否开放端口

Q2：登录后提示会话失效？ Copy Section

确保设置了 SESSION_SECRET 环境变量，且值不为空。

Q3：数据如何持久化？ Copy Section

使用 Docker 卷映射数据目录：

volumes:
  - ./data:/data

Q4：如何更新版本？ Copy Section

# 拉取最新镜像
docker pull calciumion/new-api:latest

# 重启容器
docker-compose down && docker-compose up -d

相关链接 Copy Chapter

• 官方文档
• 环境变量配置
• 常见问题
• GitHub 仓库

截图示例 Copy Chapter

⚠️ 注意：密钥为环境变量 SESSION_SECRET，请务必设置！

File: docs/channel/other_setting.md Copy Chapter

渠道额外设置说明

该配置用于设置一些额外的渠道参数，可以通过 JSON 对象进行配置。主要包含以下三个设置项：

1. force_format

   • 用于标识是否对数据进行强制格式化为 OpenAI 格式
   • 类型为布尔值，设置为 true 时启用强制格式化

2. proxy

   • 用于配置网络代理
   • 类型为字符串，支持 http、https、socks5 和 socks5h 协议
   • 保存时必须包含协议和主机；仅允许空路径或根路径 /，不允许 query 或 fragment
   • SOCKS 代理未填写端口时，运行时使用默认端口 1080

3. thinking_to_content

   • 用于标识是否将思考内容reasoning_content转换为``标签拼接到内容中返回
   • 类型为布尔值，设置为 true 时启用思考内容转换

JSON 格式示例 Copy Chapter

以下是一个示例配置，启用强制格式化并设置了代理地址：

{
    "force_format": true,
    "thinking_to_content": true,
    "proxy": "socks5://proxy.example:1080"
}

通过调整上述 JSON 配置中的值，可以灵活控制渠道的额外行为，比如是否进行格式化以及使用特定的网络代理。

升级兼容性 Copy Chapter

旧版本会忽略代理地址中的 path、query 和 fragment。为避免升级后中断已有渠道流量，运行时会继续剥离这些遗留后缀，并对同一代理地址每个进程记录一次不含凭证和后缀的警告。该兼容逻辑不会改写数据库；再次保存渠道时必须按上述严格规则修正代理地址。

代理连接使用 30 秒 TCP 拨号超时和 30 秒 KeepAlive；TLS 握手超时为 10 秒。这些超时同样适用于未配置渠道代理的中转请求。

File: docs/ionet-client.md Copy Chapter

Request URL
https://api.io.solutions/v1/io-cloud/clusters/654fc0a9-0d4a-4db4-9b95-3f56189348a2/update-name
Request Method
PUT

{"status":"succeeded","message":"Cluster name updated successfully"}

File: docs/translation-glossary.fr.md Copy Chapter

Glossaire Français (French Glossary)

Ce document fournit des traductions standards françaises pour la terminologie clé du projet afin d'assurer la cohérence et la précision des traductions.

This document provides standard French translations for key project terminology to ensure consistency and accuracy in translations.

Concepts de Base (Core Concepts) Copy Chapter

• L'utilisation d'émojis dans les traductions est autorisée s'ils sont présents dans l'original
• L'utilisation de termes purement techniques est autorisée s'ils sont présents dans l'original
• L'utilisation de termes techniques en anglais est autorisée s'ils sont largement utilisés dans l'environnement technique francophone (par exemple, API)

Modèles (Model Related) Copy Chapter

Gestion des Utilisateurs (User Management) Copy Chapter

Recharge et Échange (Recharge & Redemption) Copy Chapter

Gestion des Canaux (Channel Management) Copy Chapter

Sécurité (Security Related) Copy Chapter

Recommandations de Traduction (Translation Guidelines) Copy Chapter

Variantes Contextuelles de Traduction Copy Section

Invite/Entrée (Prompt/Input)

• Invite : Lors de l'interaction avec les LLM, dans l'interface utilisateur, lors de la description de l'interaction avec le modèle
• Entrée : Dans la tarification, la documentation technique, la description du processus de traitement des données
• Règle : S'il s'agit de l'expérience utilisateur et de l'interaction avec l'IA → "Invite", s'il s'agit du processus technique ou des calculs → "Entrée"

Jeton (Token)

• Jeton d'accès API (API Token)
• Unité de texte traitée par le modèle (Text Token)
• Jeton d'accès système (Access Token)

Quota (Quota)

• Quota de services disponible pour l'utilisateur
• Parfois traduit comme "Crédit"

Particularités de la Langue Française Copy Section

• Formes plurielles : Nécessite une implémentation correcte des formes plurielles (_one, _other)
• Accords grammaticaux : Attention aux accords grammaticaux dans les termes techniques
• Genre grammatical : Accord du genre des termes techniques (par exemple, "modèle" - masculin, "canal" - masculin)

Termes Standardisés Copy Section

• Complétion (Completion) : Contenu de sortie du modèle
• Ratio (Ratio) : Multiplicateur pour le calcul des prix
• Code d'échange (Redemption Code) : Utilisé au lieu de "Code d'échange" pour plus de précision
• Fournisseur (Provider/Vendor) : Organisation ou service fournissant des API ou des modèles d'IA

Note pour les contributeurs : Si vous trouvez des incohérences dans les traductions de terminologie ou si vous avez de meilleures suggestions de traduction pour le français, n'hésitez pas à créer une Issue ou une Pull Request.

Contribution Note for French: If you find any inconsistencies in terminology translations or have better translation suggestions for French, please feel free to submit an Issue or Pull Request.

File: docs/translation-glossary.md Copy Chapter

翻译术语表 (Translation Glossary)

本文档为翻译贡献者提供项目中关键术语的标准翻译参考，以确保翻译的一致性和准确性。

This document provides standard translation references for key terminology in the project to ensure consistency and accuracy for translation contributors.

核心概念 (Core Concepts) Copy Chapter

模型相关 (Model Related) Copy Chapter

用户管理 (User Management) Copy Chapter

充值与兑换 (Recharge & Redemption) Copy Chapter

渠道管理 (Channel Management) Copy Chapter

安全相关 (Security Related) Copy Chapter

计费相关 (Billing Related) Copy Chapter

翻译注意事项 (Translation Guidelines) Copy Chapter

• 提示 (Prompt) = 模型输入内容 / Model input content
• 补全 (Completion) = 模型输出内容 / Model output content
• 倍率 (Ratio) = 价格计算的乘数因子 / Multiplier factor for price calculation
• 额度 (Quota) = 可用的用户服务额度，有时也翻译为 Credit / Available service quota for users, sometimes also translated as Credit
• Token = 根据上下文可能指 / Depending on context, may refer to:
  • API访问令牌 (API Token)
  • 模型处理的文本单元 (Text Token)
  • 系统访问令牌 (Access Token)

贡献说明: 如发现术语翻译不一致或有更好的翻译建议，欢迎提交 Issue 或 Pull Request。

Contribution Note: If you find any inconsistencies in terminology translations or have better translation suggestions, please feel free to submit an Issue or Pull Request.

File: docs/translation-glossary.ru.md Copy Chapter

Русский глоссарий (Russian Glossary)

Данный раздел предоставляет стандартные переводы ключевой терминологии проекта на русский язык для обеспечения согласованности и точности переводов.

This section provides standard Russian translations for key project terminology to ensure consistency and accuracy in translations.

Основные концепции (Core Concepts) Copy Chapter

• Допускается использовать символы Emoji в переводе, если они были в оригинале.
• Допускается использование сугубо технических терминов, если они были в оригинале.
• Допускается использование технических терминов на английском языке, если они широко используются в русскоязычной технической среде (например, API).

Модели (Model Related) Copy Chapter

Управление пользователями (User Management) Copy Chapter

Пополнение и обмен (Recharge & Redemption) Copy Chapter

Управление каналами (Channel Management) Copy Chapter

Безопасность (Security Related) Copy Chapter

Рекомендации по переводу (Translation Guidelines) Copy Chapter

Контекстуальные варианты перевода Copy Section

Промпт/Ввод (Prompt/Input)

• Промпт: При общении с LLM, в пользовательском интерфейсе, при описании взаимодействия с моделью
• Ввод: При тарификации, технической документации, описании процесса обработки данных
• Правило: Если речь о пользовательском опыте и взаимодействии с AI → "Промпт", если о техническом процессе или расчетах → "Ввод"

Token

• API токен доступа (API Token)
• Текстовая единица, обрабатываемая моделью (Text Token)
• Токен доступа к системе (Access Token)

Квота (Quota)

• Доступная квота услуг пользователя
• Иногда переводится как "Кредит"

Особенности русского языка Copy Section

• Множественные формы: Требуется правильная реализация множественных форм (_one,_few, _many,_other)
• Падежные окончания: Внимательное отношение к падежным окончаниям в технических терминах
• Грамматический род: Согласование рода технических терминов (например, "модель" - женский род, "канал" - мужской род)

Стандартизированные термины Copy Section

• Вывод (Completion): Содержимое вывода модели
• Коэффициент (Ratio): Множитель для расчета цены
• Код купона (Redemption Code): Используется вместо "Код обмена" для большей точности
• Поставщик (Provider/Vendor): Организация или сервис, предоставляющий API или AI-модели

Примечание для участников: При обнаружении несогласованности в переводах терминологии или наличии лучших предложений по переводу, не стесняйтесь создавать Issue или Pull Request.

Contribution Note for Russian: If you find any inconsistencies in terminology translations or have better translation suggestions for Russian, please feel free to submit an Issue or Pull Request.

File: electron/README.md Copy Chapter

New API Electron Desktop App

This directory contains the Electron wrapper for New API, providing a native desktop application with system tray support for Windows, macOS, and Linux.

Prerequisites Copy Chapter

1. Go Binary (Required) Copy Section

The Electron app requires the compiled Go binary to function. You have two options:

Option A: Use existing binary (without Go installed)

# If you have a pre-built binary (e.g., new-api-macos)
cp ../new-api-macos ../new-api

Option B: Build from source (requires Go)
TODO

2. Electron Dependencies Copy Section

cd electron
npm install

Development Copy Chapter

Start the backend, the frontend, and Electron in separate terminals:

# Repository root
go run main.go

# Repository root
make dev-web

# electron/
npm run dev-app

This will:

• Use the Go backend on port 3000
• Use the Rsbuild frontend development server on port 5173
• Open an Electron window with DevTools enabled
• Create a system tray icon (menu bar on macOS)
• Store database in ../data/new-api.db

Building for Production Copy Chapter

Quick Build Copy Section

# From electron/, build the frontend, Go binary, and desktop package
./build.sh

# Or package an existing binary for the current platform
npm run build

# Platform-specific builds
npm run build:mac    # Creates .dmg and .zip
npm run build:win    # Creates .exe installer
npm run build:linux  # Creates .AppImage and .deb

Build Output Copy Section

• Built applications are in electron/dist/
• macOS: .dmg (installer) and .zip (portable)
• Windows: .exe (installer) and portable exe
• Linux: .AppImage and .deb

Configuration Copy Chapter

Port Copy Section

Default port is 3000. To change, edit main.js:

const PORT = 3000; // Change to desired port

Database Location Copy Section

• Development: ../data/new-api.db (project directory)
• Production:
  • macOS: ~/Library/Application Support/New API/data/
  • Windows: %APPDATA%/New API/data/
  • Linux: ~/.config/New API/data/

File: README.fr.md Copy Chapter

📝 Description du projet Copy Chapter

New API est une passerelle IA auto-hébergée pour les applications, les agents et les équipes. Connectez vos fournisseurs de modèles, exposez une API commune à vos clients et gérez le routage, les accès, les usages et les coûts depuis une même console.

Utilisez-la pour partager des accès autorisés au sein d'une équipe, changer de fournisseur sans reconfigurer chaque client ou exploiter un service privé multi-modèles. Les fournisseurs incluent OpenAI, Anthropic, Google Gemini, Azure OpenAI, AWS Bedrock, Vertex AI, DeepSeek, Qwen et d'autres services compatibles.

[!IMPORTANT]

• Ce projet est exclusivement destiné aux scénarios de passerelle API d'IA légalement autorisés, d'authentification organisationnelle, de gestion multi-modèles, d'analyse d'utilisation, de comptabilisation des coûts et de déploiement privé.
• Les utilisateurs doivent obtenir légalement les clés API, comptes, services de modèles et autorisations d'interface en amont, et doivent respecter les conditions d'utilisation en amont et les lois et réglementations applicables.
• Les utilisateurs doivent s'assurer que leur utilisation est conforme aux conditions d'utilisation en amont et aux lois et réglementations applicables.
• Lors de la fourniture de services d'IA générative au public, les utilisateurs doivent se conformer aux exigences réglementaires applicables et remplir toutes les obligations d'enregistrement, de licence, de sécurité du contenu, de vérification d'identité, de conservation des journaux, de fiscalité et d'autorisation en amont requises par leur juridiction.

[!WARNING]
Lorsque vous exploitez ce projet en tant que service public d'IA générative ou service de revente d'API, les utilisateurs doivent d'abord remplir toutes les obligations requises en matière d'enregistrement, de licence, de sécurité du contenu, de vérification d'identité, de conservation des journaux, de fiscalité, de paiement et d'autorisation en amont.

🤝 Partenaires de confiance Copy Chapter

🙏 Remerciements spéciaux Copy Chapter

Fonctionnalités Copy Chapter

Protocoles et points d'accès Copy Section

RelayKit convertit les requêtes, réponses et flux entre les quatre protocoles textuels. Les capacités disponibles dépendent du canal, du modèle amont et du chemin de conversion ; certains outils et champs propres à un protocole ne sont pas entièrement transposables. WebSocket nécessite également un fournisseur et une configuration de canal compatibles.

Ce README décrit le code source actuel. Consultez les notes de la version que vous déployez.

Démarrage rapide Copy Chapter

Essai local avec Docker Copy Section

Cette commande démarre une instance SQLite accessible uniquement depuis la machine locale :

mkdir -p data
docker run --name new-api -d --restart unless-stopped \
  -p 127.0.0.1:3000:3000 \
  -e TZ=Asia/Shanghai \
  -v "$(pwd)/data:/data" \
  calciumion/new-api:latest

Ouvrez http://localhost:3000 et suivez l'assistant pour créer le compte administrateur. Le répertoire data conserve la base SQLite lors du remplacement du conteneur.

Première requête Copy Section

1. Ajoutez un canal avec votre clé API amont, ses modèles et son groupe, puis lancez un test du canal.
2. Configurez les prix des modèles et vérifiez que l'utilisateur dispose d'un quota ou d'un abonnement valide.
3. Créez une clé API dans la console, autorisée à accéder au même groupe et aux mêmes modèles.
4. Pour un client compatible OpenAI, utilisez http://localhost:3000/v1 comme URL de base et la clé émise par New API.

Définissez NEW_API_KEY dans votre shell avec cette clé, puis listez les modèles accessibles :

curl --fail-with-body http://localhost:3000/v1/models \
  -H "Authorization: Bearer ${NEW_API_KEY}"

Appelez ensuite Responses en remplaçant your-enabled-model par un modèle activé qui prend en charge cette interface :

curl --fail-with-body http://localhost:3000/v1/responses \
  -H "Authorization: Bearer ${NEW_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"model":"your-enabled-model","input":"Hello!"}'

Déploiement Copy Chapter

Docker Compose Copy Section

La configuration Compose du dépôt démarre New API + PostgreSQL + Redis par défaut. Elle contient aussi des exemples pour MySQL et une base de journaux ClickHouse distincte.

git clone https://github.com/QuantumNous/new-api.git
cd new-api

Avant de démarrer, modifiez docker-compose.yml : remplacez les mots de passe d'exemple de la base et de Redis dans les services et les chaînes de connexion, puis définissez un SESSION_SECRET aléatoire et persistant (générable avec openssl rand -hex 32). Pour une console HTTPS, définissez SESSION_COOKIE_SECURE=true et renseignez son origine HTTPS publique exacte dans SESSION_COOKIE_TRUSTED_URL.

docker compose up -d
docker compose logs -f new-api

Stockage et configuration Copy Section

Consultez l'exemple d'environnement, la référence des variables et le guide des sessions. Injectez les variables du conteneur avec environment ou env_file dans Compose ; copier .env.example ne suffit pas.

En production, utilisez HTTPS et configurez le proxy inverse pour le streaming et WebSocket. Conservez et sauvegardez les bases et les données montées. Tous les nœuds doivent partager la base principale et les secrets d'authentification ; des Redis distincts ou des limiteurs en mémoire comptent les limites séparément par nœud. Le guide des sessions détaille la propagation selon la topologie.

Choisissez une version précise d'image dans les versions publiées, lisez ses notes et sauvegardez avant toute mise à niveau. Le tag latest évolue avec les publications ; évaluez les migrations et la compatibilité de votre installation.

Développement et extensions Copy Chapter

Le backend utilise Go et Gin ; la console utilise React 19, TypeScript, Rsbuild, TanStack et Tailwind CSS 4. Utilisez Bun pour le frontend. Consultez go.mod pour la version de référence du langage Go et Dockerfile pour la chaîne de compilation du conteneur.

Compilez le frontend avant de démarrer le backend, qui intègre web/dist :

# Racine du dépôt
cd web
bun install --frozen-lockfile
bun run build
cd ..
go run .

Dans un second terminal, démarrez le serveur de développement frontend :

cd web
bun run dev -- --port 5173

Ouvrez http://localhost:5173 ; les requêtes API sont relayées vers le backend sur le port 3000. Pour un backend de développement en conteneur, consultez docker-compose.dev.yml et la cible make dev du makefile.

Lisez AGENTS.md avant de contribuer. Exécutez les vérifications adaptées : make test pour les modules Go ; bun run typecheck, bun run lint, bun run test et bun run build dans web/ pour le frontend. Une modification de RelayKit nécessite aussi GOWORK=off go build ./... depuis relaykit/.

Documentation et communauté Copy Chapter

Pour signaler un bug, indiquez la version, le déploiement, les étapes de reproduction et des journaux expurgés des données sensibles. Les contributions à la documentation, aux traductions, aux intégrations et aux tests de régression ciblés sont les bienvenues.

🔗 Projets connexes Copy Chapter

Projets en amont Copy Section

Outils d'accompagnement Copy Section

📜 Licence Copy Chapter

Ce projet est sous licence GNU Affero General Public License v3.0 (AGPLv3).

Des conditions supplémentaires s'appliquent au titre de la section 7 de l'AGPLv3. Les versions modifiées doivent conserver la mention Frontend design and development by New API contributors. dans les mentions légales appropriées et les emplacements visibles de l'interface dédiés aux informations, au droit, au pied de page ou aux attributions, ainsi qu'un lien visible vers le projet original : https://github.com/QuantumNous/new-api.

Il s'agit d'un projet open-source développé sur la base de One API (licence MIT).

Si les politiques de votre organisation ne permettent pas l'utilisation de logiciels sous licence AGPLv3, ou si vous souhaitez éviter les obligations open-source de l'AGPLv3, veuillez nous contacter à : [email protected]

Consultez NOTICE et les licences tierces pour les attributions et les dépendances.

🌟 Historique des étoiles Copy Chapter

File: README.ja.md Copy Chapter

📝 プロジェクト説明 Copy Chapter

New API は、アプリケーション、Agent、チーム向けのセルフホスト型 AI ゲートウェイです。各社のモデルサービスを共通の入口に接続し、ルーティング、アクセス権、使用量、コストを一つの管理画面で扱えます。

チーム内で許可済みのモデルを共有する、クライアントの再設定を減らしてプロバイダーを切り替える、複数モデルを扱うプライベートサービスを構築するといった用途に使えます。OpenAI、Anthropic、Google Gemini、Azure OpenAI、AWS Bedrock、Vertex AI、DeepSeek、Qwen などに対応しています。

[!IMPORTANT]

• 本プロジェクトは、合法的に許可された AI API ゲートウェイ、組織レベルの認証、マルチモデル管理、利用量分析、コスト管理、プライベートデプロイのシナリオのみを対象としています。
• ユーザーは、上流の API キー、アカウント、モデルサービス、インターフェース権限を合法的に取得し、上流のサービス利用規約および適用される法律法規を遵守する必要があります。
• ユーザーは、利用方法が上流のサービス利用規約および適用される法律法規に準拠していることを確認してください。
• 生成 AI サービスを公衆に提供する場合、ユーザーは適用される規制要件を遵守し、管轄区域で求められる届出、ライセンス、コンテンツセキュリティ、本人確認、ログ保持、税務、上流認可などのすべての義務を履行してください。

[!WARNING]
本プロジェクトを公衆向け生成 AI サービスまたは API 再販サービスとして運営する場合、ユーザーは届出、コンテンツセキュリティ、本人確認、ログ保持、税務、決済、上流認可などの必要なコンプライアンス義務を先に完了してください。

🤝 信頼できるパートナー Copy Chapter

🙏 特別な感謝 Copy Chapter

主な機能 Copy Chapter

プロトコルとエンドポイント Copy Section

RelayKit は、上記 4 種類のテキストプロトコル間でリクエスト、レスポンス、ストリームを変換します。利用できる機能はチャネル、上流モデル、変換経路に依存し、固有のツールやフィールドを完全には変換できない場合があります。WebSocket も対応する上流とチャネル設定が必要です。

この README は現在のソースコードを説明しています。デプロイするバージョンのリリースノートも確認してください。

クイックスタート Copy Chapter

Docker でローカル実行 Copy Section

SQLite を使う単一インスタンスを、ローカルホスト限定で起動します。

mkdir -p data
docker run --name new-api -d --restart unless-stopped \
  -p 127.0.0.1:3000:3000 \
  -e TZ=Asia/Shanghai \
  -v "$(pwd)/data:/data" \
  calciumion/new-api:latest

http://localhost:3000 を開き、初期設定ウィザードで管理者アカウントを作成します。SQLite データベースはマウントした data ディレクトリに保存され、コンテナを置き換えても残ります。

最初のリクエスト Copy Section

1. 上流の API キー、利用するモデル、グループを設定してチャネルを追加し、チャネルテストを実行します。
2. モデルの料金を設定し、ユーザーに利用可能なクォータまたは有効なサブスクリプションがあることを確認します。
3. 管理画面で、同じグループとモデルにアクセスできる API キーを作成します。
4. OpenAI 互換クライアントでは Base URL を http://localhost:3000/v1 に設定し、New API が発行したキーを使います。

シェルの NEW_API_KEY にそのキーを設定し、アクセス可能なモデルを確認します。

curl --fail-with-body http://localhost:3000/v1/models \
  -H "Authorization: Bearer ${NEW_API_KEY}"

次に Responses を呼び出します。your-enabled-model は、このインターフェースに対応する有効なモデル名に置き換えてください。

curl --fail-with-body http://localhost:3000/v1/responses \
  -H "Authorization: Bearer ${NEW_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"model":"your-enabled-model","input":"Hello!"}'

デプロイと運用 Copy Chapter

Docker Compose Copy Section

リポジトリの Compose 設定 は、既定で New API + PostgreSQL + Redis を起動します。MySQL と独立した ClickHouse ログデータベースの設定例も含まれます。

git clone https://github.com/QuantumNous/new-api.git
cd new-api

起動前に docker-compose.yml を編集し、データベースと Redis のサービスおよび接続文字列にあるサンプルパスワードを変更します。永続的に使うランダムな SESSION_SECRET も設定してください（openssl rand -hex 32 で生成可能）。HTTPS の管理画面には SESSION_COOKIE_SECURE=true を設定し、公開 HTTPS オリジンを SESSION_COOKIE_TRUSTED_URL に正確に指定します。

docker compose up -d
docker compose logs -f new-api

ストレージと設定 Copy Section

詳細は環境変数の例、環境変数リファレンス、認証とセッションの説明を参照してください。コンテナの変数は Compose の environment または env_file で渡します。.env.example のコピーだけではコンテナに反映されません。

本番環境では HTTPS を使い、リバースプロキシでストリーミングと WebSocket アップグレードを有効にします。データベースとマウントデータを永続化し、バックアップしてください。複数ノードはメインデータベースと認証シークレットを共有します。独立した Redis やメモリ内のレート制限はノードごとに計数します。構成別のセッション伝播については認証の説明を参照してください。

リリース一覧からイメージのバージョンを固定し、更新内容を読んでバックアップしてからアップグレードしてください。latest は公開ビルドに応じて変わります。既存環境の移行と互換性は、利用中のバージョンに応じて確認してください。

開発と拡張 Copy Chapter

バックエンドは Go と Gin、管理画面は React 19、TypeScript、Rsbuild、TanStack、Tailwind CSS 4 を使用します。フロントエンドの依存関係とスクリプトには Bun を使います。Go 言語の基準バージョンは go.mod、コンテナのビルドツールチェーンは Dockerfile を参照してください。

バックエンドは web/dist を埋め込むため、先にフロントエンドをビルドします。

# リポジトリのルート
cd web
bun install --frozen-lockfile
bun run build
cd ..
go run .

別のターミナルでフロントエンド開発サーバーを起動します。

cd web
bun run dev -- --port 5173

http://localhost:5173 を開きます。API リクエストはポート 3000 のバックエンドに転送されます。開発用バックエンドをコンテナで動かす場合は docker-compose.dev.yml と makefile の make dev を参照してください。

貢献前に AGENTS.md を確認してください。変更に応じて、Go モジュールは make test、フロントエンドは web/ で bun run typecheck、bun run lint、bun run test、bun run build を実行します。RelayKit を変更した場合は、relaykit/ で GOWORK=off go build ./... も実行してください。

ドキュメントとコミュニティ Copy Chapter

不具合の報告には、バージョン、デプロイ方法、再現手順、機密情報を除いたログを添えてください。ドキュメント、翻訳、プロバイダー連携、対象を絞った回帰テストへの貢献も歓迎します。

🔗 関連プロジェクト Copy Chapter

上流プロジェクト Copy Section

補助ツール Copy Section

📜 ライセンス Copy Chapter

このプロジェクトは GNU Affero General Public License v3.0 (AGPLv3) の下でライセンスされています。

AGPLv3 第 7 条に基づく追加条項が適用されます。変更版では、適切な法的表示と、画面上の目立つ概要・法的情報・フッター・著作者表示の箇所に Frontend design and development by New API contributors. を残し、元のプロジェクト https://github.com/QuantumNous/new-api への可視リンクを保持する必要があります。

本プロジェクトは、One API（MITライセンス）をベースに開発されたオープンソースプロジェクトです。

お客様の組織のポリシーがAGPLv3ライセンスのソフトウェアの使用を許可していない場合、またはAGPLv3のオープンソース義務を回避したい場合は、こちらまでお問い合わせください：[email protected]

著作者と依存関係の表示については NOTICE とサードパーティライセンスを参照してください。

🌟 スター履歴 Copy Chapter

2. Official Technical Reference & Guides (QuantumNous/new-api-docs) Copy Chapter

File: docs/index.md Copy Chapter

template: home.html
title: New API
social:
cards_layout_options:
title: 新一代大模型网关与 AI 资产管理系统

Welcome to New API.

File: docs/getting-started.md Copy Chapter

hide:

• footer
• navigation
• toc

🎯 **部署方式选择** Copy Chapter

• :fontawesome-brands-docker:{ .twemoji }

  Docker Compose部署 ⭐推荐

  ---

  使用Docker Compose编排多个服务，适合生产环境或需要MySQL、Redis等依赖的场景

  了解更多 →{ .more-link }

• :fontawesome-brands-docker:{ .twemoji }

  Docker 单容器部署

  ---

  使用Docker镜像快速部署New API，适合个人使用或小规模应用场景

  了解更多 →{ .more-link }

• :material-server:{ .twemoji }

  1Panel 面板部署

  ---

  通过 1Panel 面板图形化界面快速部署，适合不熟悉命令行的用户

  了解更多 →{ .more-link }

• :material-server:{ .twemoji }

  宝塔面板部署

  ---

  通过宝塔面板图形化界面快速部署，适合不熟悉命令行的用户

  了解更多 →{ .more-link }

• :material-server-network:{ .twemoji }

  集群部署模式

  ---

  多节点分布式部署，实现高可用、负载均衡和水平扩展，适合大规模应用和企业级场景

  了解更多 →{ .more-link }

• :material-code-braces:{ .twemoji }

  本地开发部署

  ---

  适合开发者进行代码贡献和二次开发，提供完整的本地开发环境设置指南

  了解更多 →{ .more-link }

📚 **浏览我们的文档** Copy Chapter

• :fontawesome-solid-book:{ .twemoji }

  维基百科

  ---

  了解项目介绍、特性说明、技术架构和路线图

  了解更多 →{ .more-link }

• :fontawesome-solid-user:{ .twemoji }

  用户指南

  ---

  详细的使用说明和最佳实践

  敬请期待{ .more-link }

• :fontawesome-solid-code:{ .twemoji }

  接口文档

  ---

  全面的API接口说明和调用示例

  了解更多 →{ .more-link }

• :fontawesome-solid-headset:{ .twemoji }

  帮助支持

  ---

  常见问题解答和社区交流

  了解更多 →{ .more-link }

• :fontawesome-solid-list:{ .twemoji }

  使用指南

  ---

  快速上手指南和详细步骤说明

  了解更多 →{ .more-link }

• :fontawesome-solid-robot:{ .twemoji }

  AI应用

  ---

  探索基于New API开发的各类AI应用示例

  了解更多 →{ .more-link }

• :fontawesome-solid-handshake:{ .twemoji }

  商务合作

  ---

  与我们合作，共同开拓AI生态与商业机会

  了解更多 →{ .more-link }