README.md

---
title: JiMeng Intl API
emoji: 🎨
colorFrom: blue
colorTo: indigo
sdk: docker
app_port: 7860
pinned: false
license: mit
---

# JiMeng Intl API on Hugging Face

这个目录用于把 `jimeng-free-api-intl` 以**源码构建**方式部署到 Hugging Face Docker Spaces。

当前国际版已经包含大量 Dreamina 专属改动，因此**不再适合继续拉取官方现成镜像**，而是应该由 HF 直接基于你的国际版源码构建镜像。

## 方案说明

- 构建方式：HF 基于当前目录源码构建镜像
- HF Spaces 对外端口：`7860`
- 项目实际读取端口环境变量：`SERVER_PORT`
- 兼容方式：通过 `CMD` 把 HF 注入的 `PORT` 转成项目使用的 `SERVER_PORT`
- 国际版上游：`dreamina.capcut.com` / `mweb-api-sg.capcut.com` / `commerce-api-sg.capcut.com`
- 调用方式：OpenAI 兼容，调用端只需要 `BASE_URL + API_KEY`

HF Space 实际会收到项目根目录源码，然后再用当前目录提供的 `Dockerfile`、`.dockerignore` 和 `README.md` 覆盖 Space 根目录对应文件，最后在 Space 中执行源码构建。

## 为什么这样能跑

项目默认配置端口是 `8000`，但代码里也支持通过环境变量覆盖：

- `src/lib/environment.ts`：读取 `SERVER_PORT`
- `configs/dev/service.yml`：默认端口是 `8000`
- `huggingface-HF-JiMeng/Dockerfile`：会在 HF 上直接构建国际版源码并安装 Playwright Chromium

所以 HF Spaces 只需要：

1. 使用 Docker SDK
2. 构建本目录中的源码镜像
3. 在启动时把 `PORT` 映射为 `SERVER_PORT`

## 部署步骤

### 方案一：GitHub 自动推送到 HF Space

适合你当前的目标：代码先推到 GitHub，再由 GitHub Actions 同步项目根目录源码到 Hugging Face Space，并用本目录中的 Space 专用文件覆盖根目录文件，最后由 HF 基于这些文件构建。

1. 在 Hugging Face 新建一个 `Docker` 类型的 Space。
2. 在 GitHub 仓库中添加以下 Secrets：
   - `HF_TOKEN`：你的 Hugging Face Access Token，至少需要对目标 Space 有写权限
   - `HF_SPACE_REPO`：你的 Space 仓库名，格式为 `username/space_name`
3. 将本仓库推送到你的 GitHub 仓库：`https://github.com/Viciy2023/JiMengIntl.git`
4. 推送 `main` 分支后，GitHub Actions 会自动把项目源码同步到 HF Space，并用 `huggingface-HF-JiMeng` 目录中的 Space 专用文件覆盖根目录对应文件。
5. HF Space 收到更新后会自动开始构建。
6. 构建完成后访问：`https://<你的-space>.hf.space/ping`

对应工作流文件：

```text
.github/workflows/deploy-hf-space.yml
```

### 方案二：手动上传到 HF Space

1. 在 Hugging Face 新建一个 `Docker` 类型的 Space。
2. 把本目录中的文件上传到 Space 根目录。
3. 等待构建完成。
4. 构建完成后访问：`https://<你的-space>.hf.space/ping`

## 建议的 Space Secrets / Variables

国际版建议通过完整 Cookie Header 注入账号，并使用固定 API Key 对外提供服务。

### HF Secrets（敏感信息）

- `DREAMINA_API_KEY`
中文注释：对外提供给调用方的统一 API Key，例如 `sk-51205420185fadfaf`

- `DREAMINA_COOKIE_HEADER`
中文注释：单账号完整国际版 Cookie Header

- `DREAMINA_COOKIE_HEADERS`
中文注释：多账号完整国际版 Cookie Header 数组，推荐使用这个字段做随机轮询

### HF Variables（普通运行配置）

- `UPSTREAM_PROVIDER=dreamina-intl`
中文注释：强制使用国际版 Dreamina 上游

- `SERVER_HOST=0.0.0.0`
中文注释：让容器监听外部地址

- `TZ=Asia/Shanghai`
中文注释：服务日志时区

- `DREAMINA_PAGE_BASE_URL=https://dreamina.capcut.com`
中文注释：Dreamina 页面域名

- `DREAMINA_MWEB_API_BASE_URL=https://mweb-api-sg.capcut.com`
中文注释：Dreamina 图片/视频生成与历史查询域名

- `DREAMINA_COMMERCE_API_BASE_URL=https://commerce-api-sg.capcut.com`
中文注释：Dreamina 积分/权益域名

- `DREAMINA_REGION=HK`
中文注释：当前抓包验证可用的区域代码

- `DREAMINA_LAN=en`
中文注释：接口头中的语言标识

- `DREAMINA_LOC=HK`
中文注释：接口头中的位置标识

- `DREAMINA_ACCEPT_LANGUAGE=en-US`
中文注释：接口头中的 Accept-Language

注意：不要把真实 Cookie Header 或 sessionid 直接写进公开仓库文件。

## GitHub Secrets 说明

GitHub Actions 自动部署需要这两个 Secrets：

- `HF_TOKEN`
- `HF_SPACE_REPO`

示例：

```text
HF_SPACE_REPO=DanielleNguyen/JiMengIntl
```

`HF_TOKEN` 建议在 Hugging Face 的 Settings -> Access Tokens 中创建，并授予可写 Space 的权限。

## 调用方式

部署成功后，调用方只需要：

```text
BASE_URL=https://<your-intl-space>.hf.space/v1
API_KEY=sk-51205420185fadfaf
```

服务端会在每次请求时随机选择一条完整国际版 Cookie Header 使用。

## 验证接口

健康检查：

```bash
curl https://<你的-space>.hf.space/ping
```

国际版文生图示例：

```bash
curl -X POST "https://<你的-space>.hf.space/v1/images/generations" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-51205420185fadfaf" \
  -d '{
    "model": "jimeng-4.6",
    "prompt": "a beautiful sunset by a lake house",
    "ratio": "16:9",
    "resolution": "2k"
  }'
```

国际版文生视频示例：

```bash
curl -X POST "https://<your-intl-space>.hf.space/v1/videos/generations" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-51205420185fadfaf" \
  -d '{
    "model": "dreamina_ic_generate_video_model_vgfm_3.0_fast",
    "prompt": "a cat dancing",
    "ratio": "16:9",
    "resolution": "720p",
    "duration": 5
  }'
```

## 已知风险

- 上游镜像标签使用 `latest`，后续上游更新可能改变行为。
- 项目包含 Playwright/Chromium，HF Space 构建时间会比纯 Node 服务更长。
- 国际版视频/Seedance 仍依赖浏览器代理和前端签名链，HF 环境稳定性取决于运行资源和上游反爬策略。
- 源码构建时间会比拉现成镜像更长，但这是国际版保持最新逻辑的必要代价。

## 回滚方式

如果国际版新改动有问题，最稳妥的回滚方式是：

1. 回滚 GitHub 仓库 `JiMengIntl` 中的源码提交
2. 重新 push 到 `main`
3. GitHub Actions 会再次同步到 HF Space 并触发重建