feeling
/
jimeng-free-api-all
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
jimeng-free-api-all/CLAUDE.md

327 lines
16 KiB
Markdown
Raw Permalink Normal View History

Initial commit: jimeng-free-api-all project
2026-02-27 09:11:29 +00:00
# CLAUDE.md
本文件为 Claude Code (claude.ai/claude-code) 在此代码仓库中工作时提供指导。
## 项目概述
即梦 AI 免费 API 服务 - 逆向工程的 API 服务器，提供 OpenAI 兼容接口，封装即梦 AI 的图像和视频生成能力。
**版本：** v0.8.6
**核心功能：**
- 文生图：支持 jimeng-5.0、jimeng-4.6、jimeng-4.5 等多款模型，最高 4K 分辨率
- 图生图：多图合成，支持 1-10 张输入图片
- 视频生成：jimeng-video-3.5-pro 等模型，支持首帧/尾帧控制
- Seedance 2.0：多模态智能视频生成，模型名 `jimeng-video-seedance-2.0`（兼容 `seedance-2.0`），支持图片/视频/音频混合上传，@1、@2 占位符引用素材，4-15 秒时长
- OpenAI 兼容：完全兼容 OpenAI API 格式，无缝对接现有客户端
- 多账号支持：支持多个 sessionid 轮询使用
## 构建和开发命令
```bash
# 安装依赖
npm install
# 安装 Chromium 浏览器（Seedance 模型需要）
npx playwright-core install chromium --with-deps
# 开发模式（热重载）
npm run dev
# 生产环境构建
npm run build
# 启动生产服务
npm start
```
## Docker 命令
```bash
# 构建 Docker 镜像
docker build -t jimeng-free-api-all:latest .
# 运行容器
docker run -it -d --init --name jimeng-free-api-all -p 8000:8000 -e TZ=Asia/Shanghai jimeng-free-api-all:latest
# 使用 Docker Hub 预构建镜像
docker pull wwwzhouhui569/jimeng-free-api-all:latest
docker run -it -d --init --name jimeng-free-api-all -p 8000:8000 -e TZ=Asia/Shanghai wwwzhouhui569/jimeng-free-api-all:latest
```
## 项目架构
```
src/
├── index.ts # 应用入口
├── daemon.ts # 守护进程管理
├── api/
│ ├── controllers/ # 业务逻辑控制器
│ │ ├── core.ts # 核心工具（Token处理、积分管理、请求封装）
│ │ ├── images.ts # 图像生成逻辑（文生图、图生图）
│ │ ├── videos.ts # 视频生成逻辑（含 Seedance 2.0）
│ │ └── chat.ts # 对话补全逻辑
│ ├── routes/ # API 路由定义
│ │ ├── index.ts # 路由聚合器
│ │ ├── images.ts # /v1/images/* 端点
│ │ ├── videos.ts # /v1/videos/* 端点
│ │ ├── video.ts # /v1/video/* 端点（videos 的包装路由）
│ │ ├── chat.ts # /v1/chat/* 端点
│ │ ├── models.ts # /v1/models 端点
│ │ ├── ping.ts # /ping 健康检查端点
│ │ └── token.ts # /token/* Token管理端点
│ └── consts/
│ └── exceptions.ts # API 异常定义
└── lib/
├── server.ts # Koa 服务器配置（含中间件栈）
├── browser-service.ts # 浏览器代理服务（Seedance shark 反爬绕过）
├── config.ts # 配置管理
├── logger.ts # 日志工具
├── util.ts # 辅助工具函数
├── environment.ts # 环境变量
├── initialize.ts # 初始化逻辑
├── http-status-codes.ts # HTTP 状态码
├── request/
│ └── Request.ts # 请求解析与验证（含文件上传规范化）
├── response/
│ ├── Response.ts # 响应包装器
│ ├── Body.ts # 响应体
│ └── FailureBody.ts # 错误响应体
├── exceptions/
│ ├── Exception.ts # 基础异常类
│ └── APIException.ts # API 异常类
├── interfaces/
│ └── ICompletionMessage.ts # 对话消息接口
└── configs/ # 配置模式
├── model-config.ts # 模型配置（模型参数、分辨率映射等）
├── service-config.ts # 服务配置
└── system-config.ts # 系统配置
```
## API 端点
| 端点 | 方法 | 说明 |
|------|------|------|
| `/v1/chat/completions` | POST | OpenAI 兼容的对话接口（用于图像/视频生成） |
| `/v1/images/generations` | POST | 文生图/图生图接口（支持 images 可选参数） |
| `/v1/images/compositions` | POST | 图生图接口（支持文件上传，向后兼容） |
| `/v1/videos/generations` | POST | 视频生成接口（含 Seedance 2.0 / 2.0-fast） |
| `/v1/video/generations` | POST | 视频生成接口（别名路由） |
| `/v1/models` | GET | 获取可用模型列表 |
| `/token/check` | POST | 检查 Token 有效性 |
| `/token/points` | POST | 查询账户积分 |
| `/ping` | GET | 健康检查端点 |
## 关键技术细节
### 认证方式
- 使用即梦网站的 `sessionid` Cookie 作为 Bearer Token
- 多账号支持：逗号分隔多个 sessionid：`Authorization: Bearer sessionid1,sessionid2`
- 每次请求随机选择一个 sessionid 使用
### 模型映射
#### 图像模型
| 用户模型名 | 内部模型名 | Draft 版本 | 说明 |
|-----------|-----------|-----------|------|
| `jimeng-5.0` | `high_aes_general_v50` | 3.3.9 | 5.0 正式版（原 jimeng-5.0-preview），最新模型 |
| `jimeng-4.6` | `high_aes_general_v42` | 3.3.9 | 推荐使用 |
| `jimeng-4.5` | `high_aes_general_v40l` | 3.3.4 | 高质量模型 |
| `jimeng-4.1` | `high_aes_general_v41` | 3.3.4 | 高质量模型 |
| `jimeng-4.0` | `high_aes_general_v40` | 3.3.4 | 稳定版本 |
| `jimeng-3.1` | `high_aes_general_v30l_art_fangzhou` | - | 艺术风格 |
| `jimeng-3.0` | `high_aes_general_v30l` | - | 通用模型 |
| `jimeng-2.1` | - | - | 旧版模型 |
| `jimeng-2.0-pro` | - | - | 旧版专业模型 |
| `jimeng-2.0` | - | - | 旧版模型 |
| `jimeng-1.4` | - | - | 早期模型 |
| `jimeng-xl-pro` | - | - | XL 专业模型 |
#### 视频模型
| 用户模型名 | 内部模型名 | 说明 |
|-----------|-----------|------|
| `jimeng-video-3.5-pro` | `dreamina_ic_generate_video_model_vgfm_3.5_pro` | 最新视频模型 |
| `jimeng-video-3.0` | - | 视频生成 3.0 |
| `jimeng-video-3.0-pro` | - | 视频生成 3.0 专业版 |
| `jimeng-video-2.0` | - | 视频生成 2.0 |
| `jimeng-video-2.0-pro` | - | 视频生成 2.0 专业版 |
| `jimeng-video-seedance-2.0` | `dreamina_seedance_40_pro` | Seedance 2.0（上游标准名称，推荐） |
| `seedance-2.0` | `dreamina_seedance_40_pro` | 多图智能视频生成（向后兼容别名） |
| `seedance-2.0-pro` | `dreamina_seedance_40_pro` | 多图智能视频生成专业版（向后兼容别名） |
| `jimeng-video-seedance-2.0-fast` | `dreamina_seedance_40` | Seedance 2.0-fast 快速版（上游标准名称） |
| `seedance-2.0-fast` | `dreamina_seedance_40` | Seedance 2.0-fast 快速版（向后兼容别名） |
### 请求参数
#### 图像生成参数 (`/v1/images/generations`)
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| model | string | 否 | jimeng-4.5 | 模型名称 |
| prompt | string | 是 | - | 提示词，jimeng-4.x/5.x 支持多图生成 |
| images | array | 否 | - | 图片URL数组（1-10张），提供则走图生图模式，不提供则走文生图模式 |
| negative_prompt | string | 否 | "" | 反向提示词 |
| ratio | string | 否 | 1:1 | 宽高比：1:1, 4:3, 3:4, 16:9, 9:16, 3:2, 2:3, 21:9 |
| resolution | string | 否 | 2k | 分辨率：1k, 2k, 4k |
| sample_strength | float | 否 | 0.5 | 精细度 0.0-1.0 |
| response_format | string | 否 | url | url 或 b64_json |
**说明：**
- 当 `images` 参数为空或不提供时，接口执行文生图功能
- 当 `images` 参数提供（1-10张图片）时，接口执行图生图功能
- 支持 `application/json`（images 为 URL 数组）和 `multipart/form-data`（通过 images 字段上传文件）两种请求格式
- 图生图模式下，响应会额外包含 `input_images` 和 `composition_type` 字段
#### 图生图参数 (`/v1/images/compositions`) - 向后兼容
- 与 `/v1/images/generations` 相同的参数
- `images` 字段为必填（1-10张图片）
- 额外支持 multipart/form-data 文件上传
#### 视频生成参数 (`/v1/videos/generations`)
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| model | string | 否 | jimeng-video-3.0 | 模型名称 |
| prompt | string | 否 | - | 视频描述（图生视频时可选） |
| ratio | string | 否 | 1:1 | 宽高比：1:1, 4:3, 3:4, 16:9, 9:16 |
| resolution | string | 否 | 720p | 分辨率：480p, 720p, 1080p |
| duration | number | 否 | 5 | 时长：4-15秒（Seedance）、5 或 10 秒（普通） |
| file_paths / filePaths | array | 否 | [] | 首帧/尾帧图片 URL |
| files | file[] | 否 | - | 上传的素材文件（图片/视频/音频，multipart） |
#### Seedance 2.0 / 2.0-fast 专用参数
- 使用 `unified_edit_input` 结构，包含 `material_list` 和 `meta_list`
- 支持多模态素材混合上传：图片（ImageX）、视频/音频（VOD）
- 素材类型自动检测：通过 MIME 类型或文件扩展名判断（image/video/audio）
- 上游标准模型名：`jimeng-video-seedance-2.0`（兼容 `seedance-2.0`、`seedance-2.0-pro`）
- 快速版模型名：`jimeng-video-seedance-2.0-fast`（兼容 `seedance-2.0-fast`）
- 内部模型（标准版）：`dreamina_seedance_40_pro`，benefit_type：`dreamina_video_seedance_20_pro`
- 内部模型（快速版）：`dreamina_seedance_40`，benefit_type：`dreamina_seedance_20_fast`（注意：无 `video_` 前缀）
- Draft 版本：3.3.9
- 时长范围：4-15 秒（连续范围，与上游 iptag/jimeng-api 一致）
- 提示词占位符：`@1`、`@2`、`@图1`、`@图2`、`@image1`、`@image2` 引用上传的素材
- 支持的素材格式：图片（jpg/png/webp/gif/bmp）、视频（mp4/mov/m4v）、音频（mp3/wav）
### Shark 反爬与浏览器代理（v0.8.4）
- 即梦对 Seedance 的 `/mweb/v1/aigc_draft/generate` 接口启用了 shark 安全中间件，要求请求携带 `a_bogus` 签名
- `a_bogus` 由字节跳动 `bdms` SDK 在浏览器中生成，依赖真实浏览器环境（Canvas, WebGL, DOM），Node.js 无法直接运行
- 解决方案：通过 `BrowserService`（`src/lib/browser-service.ts`）使用 Playwright 启动 headless Chromium，`bdms` SDK 自动拦截 `fetch` 并注入 `a_bogus`
- 仅 Seedance 的 generate 请求走浏览器代理，其他请求继续用 Node.js `axios`
- 浏览器懒启动，首次 Seedance 请求时创建；每个 sessionId 独立会话；10 分钟空闲自动清理
- 资源拦截：屏蔽图片/字体/CSS，仅允许 bdms SDK 相关脚本（白名单域名：`vlabstatic.com`、`bytescm.com`、`jianying.com`、`byteimg.com`）
### 文件上传
- 支持 multipart/form-data 文件上传
- koa-body 配置最大文件大小 100MB
- files 字段可以是对象或数组格式（在 Request.ts 中自动规范化）
- 支持 formLimit/jsonLimit/textLimit：100mb
### 上传通道（v0.8.5）
- **ImageX 通道**（图片上传）：`get_upload_token(scene=2)` → `imagex.bytedanceapi.com` → `ApplyImageUpload` / `CommitImageUpload`，返回 URI 格式 `tos-cn-i-{service_id}/{uuid}`，service_id 为 `tb4s082cfz`
- **VOD 通道**（视频/音频上传）：`get_upload_token(scene=1)` → `vod.bytedanceapi.com` → `ApplyUploadInner` / `CommitUploadInner`，返回 vid 格式 `v028xxx`，SpaceName 为 `dreamina`
- AWS Signature V4 签名：ImageX 使用 service=`imagex`，VOD 使用 service=`vod`，region 均为 `cn-north-1`
- VOD 上传自动返回媒体元数据（Duration、Width、Height、Fps 等），音频时长 fallback 使用本地 WAV 头解析
### 分辨率支持
#### 图片分辨率
| 分辨率 | 1:1 | 4:3 | 3:4 | 16:9 | 9:16 | 3:2 | 2:3 | 21:9 |
|--------|-----|-----|-----|------|------|-----|-----|------|
| 1k | 1024×1024 | 768×1024 | 1024×768 | 1024×576 | 576×1024 | 1024×682 | 682×1024 | 1195×512 |
| 2k | 2048×2048 | 2304×1728 | 1728×2304 | 2560×1440 | 1440×2560 | 2496×1664 | 1664×2496 | 3024×1296 |
| 4k | 4096×4096 | 4608×3456 | 3456×4608 | 5120×2880 | 2880×5120 | 4992×3328 | 3328×4992 | 6048×2592 |
#### 视频分辨率
| 分辨率 | 1:1 | 4:3 | 3:4 | 16:9 | 9:16 |
|--------|-----|-----|-----|------|------|
| 480p | 480×480 | 640×480 | 480×640 | 854×480 | 480×854 |
| 720p | 720×720 | 960×720 | 720×960 | 1280×720 | 720×1280 |
| 1080p | 1080×1080 | 1440×1080 | 1080×1440 | 1920×1080 | 1080×1920 |
### 服务器中间件栈
1. **CORS 跨域支持**：`koa2-cors()`
2. **Range 请求**：`koaRange`（支持分段内容传输）
3. **自定义异常处理器**：捕获错误并返回 FailureBody 响应
4. **自定义 JSON 解析器**：处理 POST/PUT/PATCH 请求的 JSON（清理问题 Unicode 字符，跳过 multipart 请求）
5. **Body 解析器**：`koa-body`（multipart: true，maxFileSize: 100MB）
## 开发规范
1. **TypeScript**：项目使用 TypeScript + ESM 模块
2. **路径别名**：使用 `@/` 别名指向 `src/` 目录
3. **日志**：使用 `@/lib/logger.ts` 中的 logger 保持输出一致
4. **配置**：环境配置在 `configs/` 目录，通过 `@/lib/config.ts` 加载
5. **API 兼容性**：维护 OpenAI API 兼容性，确保客户端集成正常
6. **Node.js 版本**：≥16.0.0
## 测试 API 调用
```bash
# 文生图（使用最新模型）
curl -X POST http://localhost:8000/v1/images/generations \
-H "Content-Type: application/json" \
-H "Authorization: Bearer your_sessionid" \
-d '{"model": "jimeng-5.0", "prompt": "美丽的日落风景", "ratio": "16:9", "resolution": "2k"}'
# 图生图（通过 images 参数）
curl -X POST http://localhost:8000/v1/images/generations \
-H "Content-Type: application/json" \
-H "Authorization: Bearer your_sessionid" \
-d '{"model": "jimeng-4.5", "prompt": "将两张图融合成梦幻风格", "images": ["https://example.com/img1.jpg", "https://example.com/img2.jpg"], "ratio": "1:1", "resolution": "2k", "sample_strength": 0.5}'
# 图生图（multipart 文件上传）
curl -X POST http://localhost:8000/v1/images/generations \
-H "Authorization: Bearer your_sessionid" \
-F "model=jimeng-4.5" \
-F "prompt=将图片转换为油画风格" \
-F "images=@/path/to/image1.jpg" \
-F "ratio=1:1" \
-F "resolution=2k"
# 视频生成
curl -X POST http://localhost:8000/v1/videos/generations \
-H "Content-Type: application/json" \
-H "Authorization: Bearer your_sessionid" \
-d '{"model": "jimeng-video-3.5-pro", "prompt": "一只小猫在草地上玩耍", "ratio": "16:9", "resolution": "720p"}'
# Seedance 2.0 多图视频（文件上传）
curl -X POST http://localhost:8000/v1/videos/generations \
-H "Authorization: Bearer your_sessionid" \
-F "model=jimeng-video-seedance-2.0" \
-F "prompt=@1 和 @2 两人开始跳舞" \
-F "ratio=4:3" \
-F "duration=4" \
-F "files=@/path/to/image1.jpg" \
-F "files=@/path/to/image2.jpg"
# Seedance 2.0-fast 快速多图视频
curl -X POST http://localhost:8000/v1/videos/generations \
-H "Authorization: Bearer your_sessionid" \
-F "model=jimeng-video-seedance-2.0-fast" \
-F "prompt=@1 图片中的人物开始微笑" \
-F "ratio=4:3" \
-F "duration=5" \
-F "files=@/path/to/image1.jpg"
# Seedance 图片+音频混合视频
curl -X POST http://localhost:8000/v1/videos/generations \
-H "Authorization: Bearer your_sessionid" \
-F "model=jimeng-video-seedance-2.0-fast" \
-F "prompt=@1 图片中的人物随着音乐 @2 开始跳舞" \
-F "ratio=9:16" \
-F "duration=5" \
-F "files=@/path/to/image.png" \
-F "files=@/path/to/audio.wav"
# 健康检查
curl http://localhost:8000/ping
# Token 检查
curl -X POST http://localhost:8000/token/check \
-H "Content-Type: application/json" \
-d '{"token": "your_sessionid"}'
```
## 配置
默认端口：8000
配置文件在 `configs/` 目录，使用 YAML 格式。