16 KiB

Raw Blame History

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 轮询使用

构建和开发命令

# 安装依赖
npm install

# 安装 Chromium 浏览器（Seedance 模型需要）
npx playwright-core install chromium --with-deps

# 开发模式（热重载）
npm run dev

# 生产环境构建
npm run build

# 启动生产服务
npm start

Docker 命令

# 构建 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

服务器中间件栈

CORS 跨域支持：koa2-cors()
Range 请求：koaRange（支持分段内容传输）
自定义异常处理器：捕获错误并返回 FailureBody 响应
自定义 JSON 解析器：处理 POST/PUT/PATCH 请求的 JSON（清理问题 Unicode 字符，跳过 multipart 请求）
Body 解析器：koa-body（multipart: true，maxFileSize: 100MB）

开发规范

TypeScript：项目使用 TypeScript + ESM 模块
路径别名：使用 @/ 别名指向 src/ 目录
日志：使用 @/lib/logger.ts 中的 logger 保持输出一致
配置：环境配置在 configs/ 目录，通过 @/lib/config.ts 加载
API 兼容性：维护 OpenAI API 兼容性，确保客户端集成正常
Node.js 版本：≥16.0.0

测试 API 调用

# 文生图（使用最新模型）
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 格式。

16 KiB Raw Blame History Unescape Escape

CLAUDE.md

项目概述

构建和开发命令

Docker 命令

项目架构

API 端点

关键技术细节

认证方式

模型映射

图像模型

视频模型

请求参数

图像生成参数 (/v1/images/generations)

图生图参数 (/v1/images/compositions) - 向后兼容

视频生成参数 (/v1/videos/generations)

Seedance 2.0 / 2.0-fast 专用参数

Shark 反爬与浏览器代理（v0.8.4）

文件上传

上传通道（v0.8.5）

分辨率支持

图片分辨率

视频分辨率

服务器中间件栈

开发规范

测试 API 调用

配置

16 KiB

Raw Blame History

图像生成参数 (`/v1/images/generations`)

图生图参数 (`/v1/images/compositions`) - 向后兼容

视频生成参数 (`/v1/videos/generations`)