# inception-2api

**Repository Path**: Chinese-tingfeng/inception-2api

## Basic Information

- **Project Name**: inception-2api
- **Description**: 无头浏览器技术、无需 Cookie、自动绕过 Cloudflare (CF) 人机验证、匿名与反检测、原生流式 API 转换、Docker 一键部署
- **Primary Language**: Python
- **License**: Apache-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-11-10
- **Last Updated**: 2025-11-24

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

<div align="center">

# 🔮 inception-2api (v2.0.0)

**将 `chat.inceptionlabs.ai` 网页服务转换为兼容 OpenAI 格式 API 的高性能代理**

[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
[![GitHub Repo stars](https://img.shields.io/github/stars/lzA6/inception-2api?style=social)](https://github.com/lzA6/inception-2api)
[![Docker](https://img.shields.io/badge/Docker-Ready-blue?logo=docker)](https://hub.docker.com/)
[![Python](https://img.shields.io/badge/Python-3.10+-yellow?logo=python)](https://www.python.org/)

</div>

---

> "我们并非在创造全新的大陆，而是在已有的群岛之间架起桥梁。每一行代码，都是通往更广阔世界的一步。"

欢迎来到 `inception-2api` 的世界！这个项目的核心使命很简单，却意义非凡：**解放 Inception Labs 强大的 `mercury` 模型，让它能被任何兼容 OpenAI API 的工具、应用和脚本轻松调用。**

我们相信，技术的价值在于连接与分享。如果你也曾因一个优秀的 AI 服务没有提供 API 而感到惋惜，那么这个项目就是为你而生。它不仅是一个工具，更是一种宣言：**只要有社区和创造力，就没有无法连接的孤岛。**

## ✨ 核心特性

-   **🤖 OpenAI 兼容性**: 完美模拟 `/v1/chat/completions` 和 `/v1/models` 接口，无缝对接到所有支持 OpenAI 的生态系统
-   **🛡️ Cloudflare 穿透**: 内置 `cloudscraper` 模块，优雅绕过 Cloudflare 的机器人验证，确保服务稳定
-   **⚡ 高性能架构**: 基于 `FastAPI` + `Uvicorn` 构建，天生支持高并发异步处理
-   **🔐 企业级安全**: 支持 `API_MASTER_KEY` 访问控制，保护你的 API 不被滥用
-   **📦 一键化部署**: 提供极简的 `docker-compose.yml` 配置，一条命令即可启动服务
-   **🌊 流式响应**: 完全支持流式输出，带来与原生网页版一致的实时打字机体验

## 🎯 项目价值

### ✅ 优势亮点

| 维度 | 价值体现 |
| :--- | :--- |
| **功能性** | 将封闭的网页应用转变为开放的、可编程的 API 服务，极大扩展应用场景 |
| **便利性** | 使用熟悉的 OpenAI SDK 直接调用，无需适配私有接口 |
| **成本效益** | 免费使用 Inception Labs 的强大模型，仅需一个账号 |
| **学习价值** | 绝佳的逆向工程、API 封装和网络编程实战案例 |

### ⚠️ 注意事项

| 维度 | 潜在挑战 |
| :--- | :--- |
| **稳定性** | 依赖 Inception 网站接口，对方更新时可能需要适配 |
| **易用性** | 需要手动获取 Cookie 凭证，对非技术用户有一定门槛 |
| **服务等级** | 非官方 SLA 服务，稳定性取决于网络环境和上游服务 |
| **健壮性** | 错误处理仍在完善中，生产环境使用需谨慎 |

## 🏗️ 架构概览

### 项目结构

```mermaid
graph TB
    A[inception-2api/] --> B[.env]
    A --> C[.env.example]
    A --> D[Dockerfile]
    A --> E[docker-compose.yml]
    A --> F[main.py]
    A --> G[nginx.conf]
    A --> H[app/]
    
    H --> I[core/]
    I --> J[config.py]
    
    H --> K[providers/]
    K --> L[base_provider.py]
    K --> M[inception_provider.py]
    
    H --> N[utils/]
    N --> O[sse_utils.py]
    
    style M fill:#e1f5fe
    style J fill:#f3e5f5
    style O fill:#e8f5e8
```

### 核心组件说明

-   **`inception_provider.py`** - API 核心实现，处理请求转换和流式响应
-   **`config.py`** - 配置管理，使用 Pydantic 进行数据验证
-   **`sse_utils.py`** - SSE（服务器发送事件）格式化工具
-   **`docker-compose.yml`** - 容器编排配置，简化部署流程

## 🔧 技术原理

### 工作流程

```mermaid
sequenceDiagram
    participant C as Client
    participant P as inception-2api
    participant I as Inception Website
    participant CF as Cloudflare

    C->>P: 发送 OpenAI 格式请求
    P->>P: 解析和验证请求
    P->>I: 创建新会话 (获取 chat_id)
    CF->>P: Cloudflare 挑战
    P->>CF: cloudscraper 自动处理
    P->>I: 发送转换后的请求
    I->>P: 流式返回响应
    P->>P: 实时格式转换
    P->>C: 返回 OpenAI 兼容格式
```

### 技术栈深度解析

| 技术组件 | 角色定位 | 关键性 | 学习曲线 |
| :--- | :--- | :--- | :--- |
| **FastAPI** | 现代化异步 Web 框架 | ⭐⭐⭐⭐⭐ | ⭐⭐☆☆☆ |
| **Cloudscraper** | Cloudflare 挑战绕过 | ⭐⭐⭐⭐⭐ | ⭐⭐⭐☆☆ |
| **Docker** | 应用容器化与部署 | ⭐⭐⭐⭐⭐ | ⭐⭐☆☆☆ |
| **Pydantic** | 数据验证与配置管理 | ⭐⭐⭐⭐☆ | ⭐☆☆☆☆ |
| **Nginx** | 反向代理与负载均衡 | ⭐⭐⭐☆☆ | ⭐⭐⭐☆☆ |

## 🚀 快速开始

### 步骤 1：获取 Cookie 凭证

1.  访问 [chat.inceptionlabs.ai](https://chat.inceptionlabs.ai/) 并登录
2.  按 `F12` 打开开发者工具
3.  切换到 **Network** 标签页
4.  发送任意消息，找到 `completions` 请求
5.  复制 **Request Headers** 中的完整 `cookie` 值


### 步骤 2：配置环境变量

复制并修改 `.env.example` 为 `.env`：

```env
# inception-2api 生产环境配置
# 安全配置
API_MASTER_KEY=sk-your-secret-key-12345

# 端口配置
NGINX_PORT=8087

# Inception Labs 凭证
INCEPTION_COOKIE="cf_clearance=...; _ga=...; AWSALB=...; (你的完整 Cookie 字符串)"
```

### 步骤 3：一键部署

```bash
# 克隆项目并启动服务
git clone https://github.com/lzA6/inception-2api.git
cd inception-2api
docker-compose up -d
```

服务将在 `http://localhost:8087` 启动！

### 验证部署

```bash
# 检查服务状态
curl http://localhost:8087/v1/models
```

## 💻 使用示例

### Python 客户端

```python
from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:8087",
    api_key="sk-your-secret-key-12345"
)

response = client.chat.completions.create(
    model="mercury",
    messages=[
        {"role": "user", "content": "你好，请介绍一下你自己"}
    ],
    stream=True
)

for chunk in response:
    if chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="")
```

### cURL 示例

```bash
curl http://localhost:8087/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-your-secret-key-12345" \
  -d '{
    "model": "mercury",
    "messages": [
      {"role": "user", "content": "Hello, how are you?"}
    ],
    "stream": true
  }'
```

## 🔍 核心实现解析

### `inception_provider.py` - 心脏组件

```python
class InceptionProvider:
    def __init__(self):
        # 初始化 cloudscraper 会话
        self.scraper = cloudscraper.create_scraper()
        
    async def _get_new_chat_id(self) -> str:
        """获取新的会话 ID - 对话的'入场券'"""
        response = self.scraper.post(f"{self.base_url}/chats/new")
        return response.json()["id"]
    
    async def chat_completion(self, request: ChatCompletionRequest):
        """核心翻译函数：OpenAI → Inception → OpenAI"""
        # 1. 获取会话 ID
        chat_id = await self._get_new_chat_id()
        
        # 2. 准备请求数据和头部
        payload = self._prepare_payload(request, chat_id)
        headers = self._prepare_headers()
        
        # 3. 流式响应处理
        async def stream_generator():
            response = self.scraper.post(
                f"{self.base_url}/completions",
                json=payload,
                headers=headers,
                stream=True
            )
            
            async for line in response.iter_lines():
                if line:
                    yield self._format_sse_data(line)
        
        return StreamingResponse(stream_generator(), media_type="text/plain")
```

### 关键技术点

1.  **Cloudflare 绕过机制**
    - 使用 `cloudscraper` 模拟真实浏览器行为
    - 自动处理 JavaScript 挑战和 Cookie 验证
    - 维持会话状态以提升性能

2.  **流式响应处理**
    - 使用 Server-Sent Events (SSE) 实现实时传输
    - 异步生成器确保高并发性能
    - 实时格式转换减少延迟

3.  **协议适配层**
    - OpenAI 格式到 Inception 格式的智能映射
    - 错误处理和重试机制
    - 请求验证和数据清理

## 🛠️ 故障排除

### 常见问题

**Q: 服务启动失败**
```bash
# 检查 Docker 服务状态
docker-compose logs app
docker-compose logs nginx
```

**Q: Cookie 失效**
- 重新获取最新 Cookie 并更新 `.env` 文件
- 确保 Cookie 格式正确，包含所有必要的字段

**Q: Cloudflare 挑战失败**
```python
# 在 inception_provider.py 中调整超时设置
self.scraper = cloudscraper.create_scraper(
    browser={'custom': 'ScraperBot/1.0'},
    delay=10
)
```

**Q: 流式响应中断**
- 检查网络连接稳定性
- 验证客户端是否正确处理 SSE 格式
- 查看服务端日志获取详细错误信息

## 🚀 进阶配置

### 性能调优

```env
# .env 高级配置
UVICORN_WORKERS=4
UVICORN_MAX_REQUESTS=1000
REQUEST_TIMEOUT=30
STREAM_BUFFER_SIZE=1024
```

### 多账号负载均衡

```python
# 扩展支持多账号轮询
class MultiAccountProvider:
    def __init__(self, cookies_list):
        self.cookies = cookies_list
        self.current_index = 0
        
    def get_next_cookie(self):
        cookie = self.cookies[self.current_index]
        self.current_index = (self.current_index + 1) % len(self.cookies)
        return cookie
```

## 📈 项目路线图

### 🎯 近期目标 (v2.1)

-   [ ] Cookie 自动刷新机制
-   [ ] 增强错误处理和重试逻辑
-   [ ] 性能监控和指标收集
-   [ ] 多账号负载均衡支持

### 🌟 中期规划 (v3.0)

-   [ ] 插件化架构，支持更多 AI 服务
-   [ ] Web UI 管理面板
-   [ ] 请求缓存和限流机制
-   [ ] 完整的测试覆盖

### 🚀 长期愿景

-   [ ] 分布式部署支持
-   [ ] 智能路由和故障转移
-   [ ] 第三方集成生态
-   [ ] 企业级特性支持

## 🤝 贡献指南

我们欢迎各种形式的贡献！无论是代码改进、文档完善，还是创意想法，都是宝贵的。

### 如何参与

1.  **报告问题**: 在 Issues 中反馈 bug 或建议
2.  **提交代码**: Fork 项目并创建 Pull Request
3.  **改进文档**: 帮助完善文档和示例
4.  **分享用例**: 分享你的使用场景和经验

### 开发环境设置

```bash
# 克隆项目
git clone https://github.com/lzA6/inception-2api.git
cd inception-2api

# 安装依赖
pip install -r requirements.txt

# 设置开发环境
cp .env.example .env
# 编辑 .env 文件配置你的 Cookie

# 启动开发服务器
uvicorn main:app --reload --host 0.0.0.0 --port 8000
```

### 代码规范

- 遵循 PEP 8 Python 代码规范
- 使用类型注解提高代码可读性
- 为新功能添加适当的测试用例
- 更新相关文档反映变更

## 📄 开源协议

本项目采用 **Apache License 2.0** 开源协议。

这意味着你可以：
- ✅ 自由使用、修改和分发代码
- ✅ 用于个人或商业项目
- ✅ 专利授权
- 📝 需要保留版权声明和许可声明
- 📝 对修改部分需要明确说明

详见 [LICENSE](LICENSE) 文件。

---

<div align="center">

**Made with ❤️ and a belief in the power of connection.**

[项目主页](https://github.com/lzA6/inception-2api) · [问题反馈](https://github.com/lzA6/inception-2api/issues) · [使用讨论](https://github.com/lzA6/inception-2api/discussions)

</div>

## 🙏 致谢

感谢所有为这个项目做出贡献的开发者，特别是：

- **Inception Labs** - 提供强大的 mercury 模型
- **FastAPI 社区** - 优秀的异步 Web 框架
- **Cloudscraper 维护者** - Cloudflare 绕过的关键技术
- **所有用户和贡献者** - 你们的反馈和使用让项目不断进步

---

*如果这个项目对你有帮助，请给我们一个 ⭐ 支持我们的工作！*