# 共享剪贴板 开放平台 API 参考

> Base URL: `https://www.jlike.com`
>
> 鉴权: `Authorization: Bearer sk-xxxxxxxxx`

---

## 目录

- [鉴权与计费](#鉴权与计费)
- [文本生成](#文本生成)
  - [Gemini 3](#gemini-3-文本生成)
  - [DeepSeek V4](#deepseek-v4-文本生成)
- [图片生成](#图片生成)
  - [Nano Banana](#nano-banana-图片生成)
  - [Wan 2.7 图片](#wan-27-图片生成)
- [视频生成](#视频生成)
  - [手势舞](#手势舞视频生成)
  - [手机自拍视频](#手机自拍视频生成)
  - [跳舞换装](#跳舞换装视频生成)
  - [官方首尾帧](#官方首尾帧视频生成)
  - [Wan 2.7 图生视频](#wan-27-图生视频)
  - [HappyHorse 图生视频](#happyhorse-图生视频)
  - [HappyHorse 参考生视频](#happyhorse-参考生视频)
  - [HappyHorse 视频编辑](#happyhorse-视频编辑)
  - [RunningHub 图生视频](#runninghub-图生视频)
- [音频生成](#音频生成)
  - [声音克隆 TTS](#声音克隆-tts)
  - [AI 音乐生成](#ai-音乐生成)
- [工具](#工具)
  - [临时文件上传](#临时文件上传)
  - [价格清单](#价格清单)
- [错误码](#错误码)
- [最佳实践](#最佳实践)

---

## 鉴权与计费

### 请求头

```
Authorization: Bearer sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Content-Type: application/json
```

| HTTP | 场景 |
|------|------|
| 401 | API Key 无效 / 已吊销 |
| 402 | 余额不足 |
| 429 | 速率限制 |

### 计费模型

- 定价基准：**USD**（上游原价以 USD 为基准存储），全局加价倍率 **MARKUP = 1.3**
- 结算货币：**账户结算货币**（默认 `CNY`，可选 `USD` / `EUR`），按最新汇率换算
- 响应字段始终返回 `service` + `tier`（不暴露上游 model 名）
- **文本**（`gemini3`）：按 `promptTokenCount` + `candidatesTokenCount` + `thoughtsTokenCount` 实际 token 计费
- **文本**（`deepseek`）：按 `usage.prompt_tokens` + `usage.completion_tokens` 计费，命中 `prompt_cache_hit_tokens` 部分按缓存命中价
- **图片**（`nanobanana` / `wan27`）：按实际成功返回的图片张数结算
- **视频**：按时长计费（向上取整：2.1 秒按 3 秒计）
- 提交时先**冻结**预估额度，结束后按实际用量**结算并返还差额**，失败或取消回滚

### 服务标识与档位（service + tier）

| tier | 含义 |
|------|------|
| `fast` | 速度优先（默认推荐） |
| `pro` | 质量优先（更慢、更贵） |
| `lite` | 最低成本（仅部分服务支持） |
| `hd` | 高清版（部分视频服务） |
| `std` | 标准版（部分视频服务） |

---

## 文本生成

### Gemini 3 文本生成

```
POST /api/v1/openapi/gemini3/generate
```

透传 `contents` / `generationConfig` / `tools` / `systemInstruction`，响应附加 `service` / `tier` / `_billing` 字段。

| tier | 说明 | 兼容旧 model 名 |
|------|------|------------------|
| `pro` | 最强推理，慢 | `gemini-3.1-pro-preview` |
| `fast` | 平衡（默认推荐） | `gemini-3-flash-preview` |
| `lite` | 最便宜，最快 | `gemini-3.1-flash-lite-preview` |

**示例**

```bash
curl -X POST https://www.jlike.com/api/v1/openapi/gemini3/generate \
  -H "Authorization: Bearer sk-xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "tier": "fast",
    "contents": [{"role":"user","parts":[{"text":"用一句话解释相对论"}]}]
  }'
```

---

### DeepSeek V4 文本生成

```
POST /api/v1/openapi/deepseek/generate          (jlike 原生端点)
POST /api/v1/openapi/deepseek/chat/completions   (OpenAI 兼容端点)
```

原生路径使用 `tier` 并包一层平台 `success` 包装；OpenAI 兼容路径使用 `model` 字段、响应保持 OpenAI Chat Completions 同形。两条路径走同一套鉴权和计费。**本轮不支持流式**。

| tier | 说明 | 对应模型（兼容端点 `model`） |
|------|------|------|
| `fast` | 速度优先，性价比 | `deepseek-v4-flash` |
| `pro` | 强推理，质量优先 | `deepseek-v4-pro` |

**仅**这两个 model 名可用；`deepseek-chat` / `deepseek-reasoner` / `deepseek-coder` 等旧别名均返回 400。

**示例（原生端点）**

```bash
curl -X POST https://www.jlike.com/api/v1/openapi/deepseek/generate \
  -H "Authorization: Bearer sk-xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "tier": "fast",
    "messages": [{"role":"user","content":"用一句话解释相对论"}],
    "max_tokens": 512
  }'
```

**示例（OpenAI 兼容端点）**

```bash
curl -X POST https://www.jlike.com/api/v1/openapi/deepseek/chat/completions \
  -H "Authorization: Bearer sk-xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-v4-flash",
    "messages": [{"role":"user","content":"Reply with: pong"}],
    "max_tokens": 64
  }'
```

> **注意**：`pro` 档当前处于上游 75% 折扣促销期（至 2026-05-31 15:59 UTC），到期后回归基础价。

---

## 图片生成

### Nano Banana 图片生成

```
POST /api/v1/openapi/nanobanana/generate
```

同步返回结果图片（base64 PNG）。

| tier | 说明 | 兼容旧 model 别名 |
|------|------|------|
| `fast` | 高效率版（默认推荐） | `nano-banana-2` |
| `pro` | 专业版（更强推理） | `nano-banana-pro` |
| `lite` | 最低成本 | `nano-banana` |

参考图三选一（均可选）：`image_file_ids`（推荐）/ `image_urls` / `images`（base64，legacy）。

**示例**

```bash
curl -X POST https://www.jlike.com/api/v1/openapi/nanobanana/generate \
  -H "Authorization: Bearer sk-xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "tier": "pro",
    "prompt": "赛博朋克风格的猫，霓虹灯招牌下",
    "size": "2K",
    "aspect_ratio": "16:9",
    "n": 1
  }'
```

---

### Wan 2.7 图片生成

```
POST /api/v1/openapi/wan27/generate
GET  /api/v1/openapi/wan27/task/{task_uuid}
```

异步图片生成。提交后返回 `task_uuid`，建议每 3 秒轮询一次。

| tier | 说明 | 兼容旧 model 名 |
|------|------|------|
| `pro` | 专业版，文生图支持 4K | `wan2.7-image-pro` |
| `fast` | 标准版，速度更快 | `wan2.7-image` |

参考图三选一（均可选）：`image_file_ids`（推荐）/ `image_urls` / `images`（base64，legacy）。

**示例**

```bash
# 提交
curl -X POST https://www.jlike.com/api/v1/openapi/wan27/generate \
  -H "Authorization: Bearer sk-xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"tier":"pro","prompt":"astronaut on mars","size":"2K","aspect_ratio":"16:9","n":1}'

# 轮询
curl https://www.jlike.com/api/v1/openapi/wan27/task/<task_uuid> \
  -H "Authorization: Bearer sk-xxxxxxxx"
```

> `4K` 仅 `pro` tier 可用，且不能带参考图、不能开启顺序图。上游返回的图片 URL 通常约 24 小时有效。

---

### G2I2vQd 图生图（RunningHub）

```
POST /api/v1/openapi/g2i2v-qd/generate
GET  /api/v1/openapi/g2i2v-qd/task/{task_uuid}
```

输入提示词 + 1–10 张参考图，输出一张高质量编辑/合成图。上游 RunningHub 标准模型 `rhart-image-g-2/image-to-image`。提交后立即返回 `task_uuid`，建议每 5–10 秒轮询。终态结果缓存，**重复查询不会再次扣费**。

| tier | 分辨率 | 单价 |
|------|------|------|
| `std` | `2k` | ¥0.30 / 张 |
| `std` | `4k` | ¥0.60 / 张 |

| 字段 | 必填 | 默认 | 说明 |
|------|------|------|------|
| `prompt` | 是 | — | 文字描述，最长 20000 字符 |
| `image_urls` | 是* | — | 数组，1–10 项；每项可为 http(s) URL 或 `data:image/...;base64,...` |
| `image_file_ids` | 是* | — | 与 `image_urls` 二选一/可叠加；`/openapi/files/upload` 返回的 file_id 数组 |
| `resolution` | 否 | `2k` | `2k` / `4k`。本站当前开放 2k / 4k |
| `aspect_ratio` / `aspectRatio` | 否 | 自适应原图 | 不传时上游按输入图就近比例自适应；如显式传 4k 比例，仅支持 `16:9` / `9:16` / `21:9` / `9:21` |
| `tier` | 否 | `std` | 仅支持 `std` |

> \* `image_urls` 与 `image_file_ids` 至少给一组，合计 ≤ 10 张。单图 ≤ 30 MB。
>
> **aspectRatio 枚举**：`1:1` / `2:3` / `3:2` / `4:5` / `5:4` / `4:3` / `3:4` / `16:9` / `9:16` / `21:9` / `9:21`。

**示例**

```bash
curl -X POST https://www.jlike.com/api/v1/openapi/g2i2v-qd/generate \
  -H "Authorization: Bearer sk-xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "在马克杯的正中央，添加一个精致的几何风格狐狸 Logo，下方印着 Wild Fox。保留原图光影与陶瓷质感不变。",
    "image_urls": ["https://example.com/cup.png"],
    "resolution": "2k"
  }'
```

**轮询**

```bash
curl https://www.jlike.com/api/v1/openapi/g2i2v-qd/task/<task_uuid> \
  -H "Authorization: Bearer sk-xxxxxxxx"
```

**成功响应字段**

| 字段 | 说明 |
|------|------|
| `image_url` | 输出图片 URL（**约 24 小时有效，请尽快下载**） |
| `image_urls` | 同上，便于将来扩展为多图 |
| `resolution` | 实际使用的分辨率（`2k` / `4k`） |
| `aspect_ratio` | 实际使用的宽高比 |

> 上传 base64 时服务端会先调 `/openapi/v2/media/upload/binary` 转成 RunningHub 内部 URL 再交给上游；用 OSS file_id 的话服务端会签出有效期 30 分钟的预签 URL 给上游。

---

### I2vPro 图像编辑（RunningHub）

```
POST /api/v1/openapi/i2vpro/generate
GET  /api/v1/openapi/i2vpro/task/{task_uuid}
```

输入提示词 + 1–10 张参考图，输出一张精修编辑后的图片。上游 RunningHub 标准模型 `rhart-image-n-pro/edit`。提交后立即返回 `task_uuid`，建议每 5–10 秒轮询。终态结果缓存，**重复查询不会再次扣费**。

| tier | 分辨率 | 单价 |
|------|------|------|
| `std` | `2k` | ¥0.80 / 张 |
| `std` | `4k` | ¥1.00 / 张 |

| 字段 | 必填 | 默认 | 说明 |
|------|------|------|------|
| `prompt` | 是 | — | 文字描述，最长 20000 字符 |
| `image_urls` | 是* | — | 数组，1–10 项；每项可为 http(s) URL 或 `data:image/...;base64,...` |
| `image_file_ids` | 是* | — | 与 `image_urls` 二选一/可叠加；`/openapi/files/upload` 返回的 file_id 数组 |
| `resolution` | 否 | `2k` | `2k` / `4k` |
| `aspect_ratio` | 否 | 自适应原图 | 不传时上游按原图尺寸自适应；要锁定比例可传下方枚举 |
| `tier` | 否 | `std` | 仅支持 `std` |

> \* `image_urls` 与 `image_file_ids` 至少给一组，合计 ≤ 10 张。单图 ≤ 10 MB。
>
> **aspectRatio 枚举**：`1:1` / `16:9` / `9:16` / `4:3` / `3:4` / `3:2` / `2:3` / `5:4` / `4:5` / `21:9`。

**示例**

```bash
curl -X POST https://www.jlike.com/api/v1/openapi/i2vpro/generate \
  -H "Authorization: Bearer sk-xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "基于原图风格，将主角替换为一只年迈慈祥的猴子奶奶，穿着格子围裙做晚餐。厨房环境保持不变，整体氛围温馨。",
    "image_urls": ["https://example.com/grandma.jpg"],
    "aspect_ratio": "3:4",
    "resolution": "2k"
  }'
```

**轮询**

```bash
curl https://www.jlike.com/api/v1/openapi/i2vpro/task/<task_uuid> \
  -H "Authorization: Bearer sk-xxxxxxxx"
```

**成功响应字段**

| 字段 | 说明 |
|------|------|
| `image_url` | 输出图片 URL（**约 24 小时有效，请尽快下载**） |
| `image_urls` | 同上，便于将来扩展为多图 |
| `resolution` | 实际使用的分辨率（`2k` / `4k`） |
| `aspect_ratio` | 实际使用的宽高比 |

> 上传 base64 时服务端会先调 `/openapi/v2/media/upload/binary` 转成 RunningHub 内部 URL 再交给上游；用 OSS file_id 的话服务端会签出有效期 30 分钟的预签 URL 给上游。

---

### FlatLay 平铺拼图

```
POST /api/v1/openapi/flat-lay/generate
GET  /api/v1/openapi/flat-lay/task/{task_uuid}
```

输入**一张单品图**（如一条裙子），上游自动分析其品类/风格/颜色/季节，从自建商品库里配齐互补单品（鞋、包、配饰、项链等），生成一张「平铺拼图」效果图（俯拍 flat-lay，含诗意文案与可选品牌名）。异步：提交后立即返回 `task_uuid`，建议每 3–5 秒轮询（上游侧有 ~30 秒节流，终态最多延迟 ~30 秒可见）。终态结果缓存，**重复查询不会再次扣费**。

| tier | 说明 | 单价 |
|------|------|------|
| `std` | 标准平铺拼图（3:4，2K） | ¥1.00 / 张 |

| 字段 | 必填 | 默认 | 说明 |
|------|------|------|------|
| `image_url` | 是 | — | 单品图，必须为公网 https URL |
| `lang` | 否 | `zh` | 拼图文案语言：`zh` / `ja` / `en` |
| `brand_label` | 否 | 无 | 拼图左上角品牌名（≤40 字符）；不传则不显示品牌名 |
| `seed_category` | 否 | 自动推断 | 品类提示（如 `dress`）；缺省由上游模型推断 |
| `tier` | 否 | `std` | 仅支持 `std` |

**示例**

```bash
# 提交
curl -X POST https://www.jlike.com/api/v1/openapi/flat-lay/generate \
  -H "Authorization: Bearer sk-xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"image_url":"https://cdn.example.com/dress.jpg","lang":"zh","brand_label":"FaFa"}'

# 轮询
curl https://www.jlike.com/api/v1/openapi/flat-lay/task/<task_uuid> \
  -H "Authorization: Bearer sk-xxxxxxxx"
```

**成功响应字段**

| 字段 | 说明 |
|------|------|
| `image_url` | 拼图结果 URL（已转存至本平台 OSS，presigned，按 `files.download_url_ttl` 有效） |

**失败错误码（`error_code`）**

| 错误码 | 含义 |
|------|------|
| `UPSTREAM_ERROR` | 上游分析失败 / 配不齐互补单品（`no_catalog_match`）/ 渲染失败或超时 |
| `oss_copy_failed` | 上游出图成功，但本平台转存到 OSS 失败 |

> 返回的 `image_url` 是本平台 OSS 地址；上游临时托管 URL 不对外暴露。

---

## 视频生成

### 手势舞视频生成

```
POST /api/v1/openapi/gesture-dance/generate
GET  /api/v1/openapi/gesture-dance/task/{task_uuid}
```

输入人像图 + 驱动手势视频，输出手势驱动后的人像视频。建议每 5–10 秒轮询。

#### 模型选择（`model`）

| model | 后端 | tier | 输出分辨率 | 单价 |
|------|------|------|------|------|
| 缺省 | RunningHub | `pro`（唯一档位） | — | — |
| `happyhorse` | HappyHorse 1.0 | `hd` | 720P | ¥1.17 / 秒 |
| `happyhorse` | HappyHorse 1.0 | `pro` | 1080P | ¥2.08 / 秒 |

| 字段 | 必填 | 默认 | 说明 |
|------|------|------|------|
| `model` | 否 | — | 模型选择：缺省使用 RunningHub，传 `happyhorse` 切换到 HappyHorse 1.0 |
| `tier` | 否 | `pro` | RunningHub 固定 `pro`；HappyHorse 可选 `hd`（720P）/ `pro`（1080P） |
| `image_url` | 是 | — | 人像图 http(s) 公网 URL |
| `video_url` | 是 | — | 驱动手势视频 http(s) 公网 URL |
| `max_duration_sec` | 否 | `15` | 1–30，计费按此上限预冻结 |
| `node_overrides` | 否 | — | 可选节点参数覆盖（仅 RunningHub） |

**示例 — 默认模型**

```bash
curl -X POST https://www.jlike.com/api/v1/openapi/gesture-dance/generate \
  -H "Authorization: Bearer sk-xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "tier": "pro",
    "image_url": "https://example.com/portrait.png",
    "video_url": "https://example.com/gesture.mp4",
    "max_duration_sec": 10
  }'
```

**示例 — HappyHorse 模型（1080P）**

```bash
curl -X POST https://www.jlike.com/api/v1/openapi/gesture-dance/generate \
  -H "Authorization: Bearer sk-xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "happyhorse",
    "tier": "pro",
    "image_url": "https://example.com/portrait.png",
    "video_url": "https://example.com/gesture.mp4",
    "max_duration_sec": 10
  }'
```

---

### 手机自拍视频生成

```
POST /api/v1/openapi/selfie-video/generate
GET  /api/v1/openapi/selfie-video/task/{task_uuid}
```

输入人像图 + 中文提示词，上游 RunningHub AI App 输出一段 **固定 5 秒** 的自拍风格视频（手机始终遮住面部五官，按提示词做指定动作；保留原图衣服材质与色彩）。提交后立即返回 `task_uuid`，建议每 5–10 秒轮询。任务终态结果缓存，**重复查询不会再次扣费**。

| tier | 时长 | 单价 |
|------|------|------|
| `pro` | 固定 5 秒 | ¥0.30 / 秒（实际单次 ≈ ¥1.50；以 `/admin/pricing` 当前值为准） |

| 字段 | 必填 | 默认 | 说明 |
|------|------|------|------|
| `image_url` | 是 | — | 人像图 http(s) 公网 URL（≤ 30 MB，单图） |
| `prompt` | 是 | — | 中文动作描述，1–2000 字符；只描述动作，**不要写负向提示词**。例：「女子手持手机自拍，手机全程挡住脸和五官，先空闲手比耶；随后叉腰；最后从上到下摸身上的衣服。保持衣服材质、形状、色彩、细节不变。固定镜头。」 |
| `tier` | 否 | `pro` | 当前仅支持 `pro` |

> 上游 nodeInfoList 的其余参数（分辨率档位 / 长宽比 / 加密方式 / BGM 等）均由服务端按推荐默认值固定，不暴露给调用方。

**示例**

```bash
curl -X POST https://www.jlike.com/api/v1/openapi/selfie-video/generate \
  -H "Authorization: Bearer sk-xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "image_url": "https://example.com/portrait.png",
    "prompt": "女子手持手机自拍，手机全程挡住脸和五官，空闲手比耶；随后叉腰；最后从上到下摸身上的衣服。保持衣服材质、形状、色彩、细节不变。固定镜头。"
  }'
```

**轮询**

```bash
curl https://www.jlike.com/api/v1/openapi/selfie-video/task/<task_uuid> \
  -H "Authorization: Bearer sk-xxxxxxxx"
```

**成功响应字段**

| 字段 | 说明 |
|------|------|
| `video_url` | 输出视频 URL（**约 24 小时有效，请尽快下载或转存**） |
| `duration_sec` | 实际时长（固定 5） |
| `service` | `selfie-video` |
| `tier` | `pro` |
| `cost` / `currency` | 实际扣费金额与结算货币 |

> 任务遇到上游容量满会自动入队（公开状态保持 `processing`），不影响结果一致性，仅有约 30 秒级的延迟。

---

### 跳舞换装视频生成

```
POST /api/v1/openapi/outfit-dance/generate
GET  /api/v1/openapi/outfit-dance/task/{task_uuid}
```

输入人像图 + 驱动视频，输出换装后的舞蹈视频。建议每 5–10 秒轮询。

#### 模型选择（`model`）

| model | 后端 | tier | 输出分辨率 | 单价 |
|------|------|------|------|------|
| 缺省 | DashScope wan2.2 | `hd`（默认） | 720P | — |
| 缺省 | DashScope wan2.2 | `pro` | 1080P | — |
| `happyhorse` | HappyHorse 1.0 | `hd` | 720P | ¥1.17 / 秒 |
| `happyhorse` | HappyHorse 1.0 | `pro` | 1080P | ¥2.08 / 秒 |

| 字段 | 必填 | 默认 | 说明 |
|------|------|------|------|
| `model` | 否 | — | 模型选择：缺省使用 DashScope wan2.2，传 `happyhorse` 切换到 HappyHorse 1.0 |
| `tier` | 否 | `hd` | `hd`（720P）/ `pro`（1080P），两种模型均支持 |
| `image_url` | 是 | — | 人像图 http(s) 公网 URL |
| `video_url` | 是 | — | 驱动舞蹈视频 http(s) 公网 URL |
| `max_duration_sec` | 否 | `15` | 1–30，计费按此上限预冻结 |
| `mode` | 否 | `wan-std` | 输出模式（仅默认模型） |

**示例 — 默认模型**

```bash
curl -X POST https://www.jlike.com/api/v1/openapi/outfit-dance/generate \
  -H "Authorization: Bearer sk-xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "tier": "hd",
    "image_url": "https://example.com/portrait.png",
    "video_url": "https://example.com/dance.mp4",
    "max_duration_sec": 15
  }'
```

**示例 — HappyHorse 模型（720P）**

```bash
curl -X POST https://www.jlike.com/api/v1/openapi/outfit-dance/generate \
  -H "Authorization: Bearer sk-xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "happyhorse",
    "tier": "hd",
    "image_url": "https://example.com/portrait.png",
    "video_url": "https://example.com/dance.mp4",
    "max_duration_sec": 15
  }'
```

---

### 官方首尾帧视频生成

```
POST /api/v1/openapi/first-last-frame/generate
GET  /api/v1/openapi/first-last-frame/task/{task_uuid}
```

输入首帧图 + 尾帧图 + 动作文字描述，输出插值视频。建议每 5–10 秒轮询。

#### 模型选择（`model`）

| model | 后端 | tier | 输出分辨率 | 时长 | 单价 |
|------|------|------|------|------|------|
| 缺省 | RunningHub ComfyUI | `std`（唯一档位） | — | 固定 5 秒 | — |
| `happyhorse` | HappyHorse 1.0 | `hd` | 720P | 可选 | ¥1.17 / 秒 |
| `happyhorse` | HappyHorse 1.0 | `pro` | 1080P | 可选 | ¥2.08 / 秒 |

| 字段 | 必填 | 默认 | 说明 |
|------|------|------|------|
| `model` | 否 | — | 模型选择：缺省使用 RunningHub，传 `happyhorse` 切换到 HappyHorse 1.0 |
| `tier` | 否 | `std` | RunningHub 固定 `std`；HappyHorse 可选 `hd`（720P）/ `pro`（1080P） |
| `prompt` | 是 | — | 动作文字描述，例如「女生慢慢走来」 |
| `start_image_url` | 是 | — | 首帧图 http(s) 公网 URL |
| `end_image_url` | 是 | — | 尾帧图 http(s) 公网 URL |
| `duration` | 否 | `5` | 视频时长（秒），仅 HappyHorse 模型支持自定义（3–15 秒） |

**示例 — 默认模型**

```bash
curl -X POST https://www.jlike.com/api/v1/openapi/first-last-frame/generate \
  -H "Authorization: Bearer sk-xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "tier": "std",
    "prompt": "女生慢慢的走来",
    "start_image_url": "https://example.com/first_frame.png",
    "end_image_url": "https://example.com/last_frame.png"
  }'
```

**示例 — HappyHorse 模型（1080P，10 秒）**

```bash
curl -X POST https://www.jlike.com/api/v1/openapi/first-last-frame/generate \
  -H "Authorization: Bearer sk-xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "happyhorse",
    "tier": "pro",
    "prompt": "女生慢慢的走来",
    "start_image_url": "https://example.com/first_frame.png",
    "end_image_url": "https://example.com/last_frame.png",
    "duration": 10
  }'
```

> 默认模型输出时长固定 5 秒，计费按固定 5 秒预冻结；HappyHorse 模型按 `duration` 计费（向上取整）。视频 URL 约 24 小时有效。

---

### Wan 2.7 图生视频

```
POST /api/v1/openapi/wan27-video/generate
GET  /api/v1/openapi/wan27-video/task/{task_uuid}
```

支持**多模态输入**（文本 / 图像 / 音频 / 视频），可完成**首帧生视频、首尾帧生视频、视频续写**三大任务。上游 DashScope wan2.7-i2v。建议每 10–15 秒轮询。

| tier | 说明 | 输出分辨率 | 单价 |
|------|------|------|------|
| `hd` | 高清版（默认） | 720P | ¥0.8 / 秒 |
| `pro` | 超清版 | 1080P | ¥1.2 / 秒 |

#### 素材组合（`media` 数组）

仅支持以下组合，其他组合返回 400：

| 任务 | 组合 |
|------|------|
| 首帧生视频 | `first_frame` 或 `first_frame` + `driving_audio` |
| 首尾帧生视频 | `first_frame` + `last_frame` 或 + `driving_audio` |
| 视频续写 | `first_clip` 或 `first_clip` + `last_frame` |

#### 请求参数

| 字段 | 必填 | 默认 | 说明 |
|------|------|------|------|
| `media` | 是 | — | 素材数组，每项含 `type` 和 `url`（http(s) 公网 URL） |
| `prompt` | 否 | — | 文字描述（≤5000 字符） |
| `negative_prompt` | 否 | — | 反向提示词（≤500 字符） |
| `duration` | 否 | `5` | 2–15 秒，计费按此值预冻结（向上取整） |
| `prompt_extend` | 否 | `true` | 是否开启 prompt 智能改写 |
| `watermark` | 否 | `false` | 是否添加"AI 生成"水印 |
| `seed` | 否 | — | 随机种子 [0, 2147483647] |

**示例 — 首帧生视频**

```bash
curl -X POST https://www.jlike.com/api/v1/openapi/wan27-video/generate \
  -H "Authorization: Bearer sk-xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "tier": "hd",
    "prompt": "一只小猫在草地上奔跑",
    "media": [
      {"type": "first_frame", "url": "https://example.com/first.png"}
    ],
    "duration": 5
  }'
```

**示例 — 首尾帧生视频**

```bash
curl -X POST https://www.jlike.com/api/v1/openapi/wan27-video/generate \
  -H "Authorization: Bearer sk-xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "tier": "pro",
    "prompt": "女生慢慢地走来",
    "media": [
      {"type": "first_frame", "url": "https://example.com/first.png"},
      {"type": "last_frame", "url": "https://example.com/last.png"}
    ],
    "duration": 10
  }'
```

**示例 — 视频续写**

```bash
curl -X POST https://www.jlike.com/api/v1/openapi/wan27-video/generate \
  -H "Authorization: Bearer sk-xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "tier": "hd",
    "prompt": "女孩出门后背着书包走在街上",
    "media": [
      {"type": "first_clip", "url": "https://example.com/clip.mp4"}
    ],
    "duration": 15
  }'
```

**轮询**

```bash
curl https://www.jlike.com/api/v1/openapi/wan27-video/task/<task_uuid> \
  -H "Authorization: Bearer sk-xxxxxxxx"
```

> 建议先用 `/openapi/files/upload` 拿到 `public_url` 再填入 media[].url。视频 URL 约 24 小时有效，请尽快下载。时长向上取整计费（如 2.1 秒按 3 秒计）。

---

### HappyHorse 图生视频

```
POST /api/v1/openapi/happyhorse/generate
GET  /api/v1/openapi/happyhorse/task/{task_uuid}
```

输入首帧图 + 文本描述，输出物理真实、运动流畅的视频。上游 DashScope happyhorse-1.0-i2v。建议每 10–15 秒轮询。

| tier | 说明 | 输出分辨率 | 单价 |
|------|------|------|------|
| `hd` | 高清版 | 720P | ¥1.17 / 秒 |
| `pro` | 超清版（默认） | 1080P | ¥2.08 / 秒 |

| 字段 | 必填 | 默认 | 说明 |
|------|------|------|------|
| `image_url` | 是 | — | 首帧图 http(s) 公网 URL |
| `prompt` | 否 | — | 文字描述（≤5000 字符） |
| `duration` | 否 | `5` | 3–15 秒，计费按此值预冻结（向上取整） |
| `watermark` | 否 | `false` | 是否添加"AI 生成"水印 |
| `seed` | 否 | — | 随机种子 [0, 2147483647] |

**示例**

```bash
curl -X POST https://www.jlike.com/api/v1/openapi/happyhorse/generate \
  -H "Authorization: Bearer sk-xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "tier": "hd",
    "image_url": "https://example.com/first_frame.png",
    "prompt": "一只小猫在草地上奔跑",
    "duration": 5
  }'
```

**轮询**

```bash
curl https://www.jlike.com/api/v1/openapi/happyhorse/task/<task_uuid> \
  -H "Authorization: Bearer sk-xxxxxxxx"
```

> 视频 URL 约 24 小时有效，请尽快下载。时长向上取整计费（如 2.1 秒按 3 秒计）。

---

### HappyHorse 参考生视频

```
POST /api/v1/openapi/happyhorse-ref/generate
GET  /api/v1/openapi/happyhorse-ref/task/{task_uuid}
```

传入多张参考图像，通过文本描述将图像中的主体角色融合生成视频。上游 DashScope happyhorse-1.0-r2v。建议每 10–15 秒轮询。

| tier | 说明 | 输出分辨率 |
|------|------|------|
| `hd` | 高清版 | 720P |
| `pro` | 超清版（默认） | 1080P |

| 字段 | 必填 | 默认 | 说明 |
|------|------|------|------|
| `prompt` | 是 | — | 文字描述（≤5000 字符），使用 `[Image 1]`、`[Image 2]` 等引用参考图 |
| `image_urls` | 是 | — | 参考图 URL 数组，1–9 张，http(s) 公网 URL |
| `duration` | 否 | `5` | 3–15 秒，计费按此值预冻结（向上取整） |
| `ratio` | 否 | `16:9` | 画面比例，可选 `16:9` / `9:16` / `3:4` / `4:3` / `1:1` |
| `watermark` | 否 | `false` | 是否添加"AI 生成"水印 |
| `seed` | 否 | — | 随机种子 [0, 2147483647] |

**示例**

```bash
curl -X POST https://www.jlike.com/api/v1/openapi/happyhorse-ref/generate \
  -H "Authorization: Bearer sk-xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "tier": "hd",
    "prompt": "[Image 1] 正在海边散步",
    "image_urls": [
      "https://example.com/character.png"
    ],
    "duration": 5,
    "ratio": "16:9"
  }'
```

**轮询**

```bash
curl https://www.jlike.com/api/v1/openapi/happyhorse-ref/task/<task_uuid> \
  -H "Authorization: Bearer sk-xxxxxxxx"
```

> 视频 URL 约 24 小时有效，请尽快下载。时长向上取整计费。

---

### HappyHorse 视频编辑

```
POST /api/v1/openapi/happyhorse-edit/generate
GET  /api/v1/openapi/happyhorse-edit/task/{task_uuid}
```

输入视频 + 文本编辑指令 + 可选参考图，输出编辑后的视频（风格变换、局部替换等）。上游 DashScope happyhorse-1.0-video-edit。输出时长 = min(输入视频时长, 15 秒)。建议每 10–15 秒轮询。

| tier | 说明 | 输出分辨率 |
|------|------|------|
| `hd` | 高清版 | 720P |
| `pro` | 超清版（默认） | 1080P |

| 字段 | 必填 | 默认 | 说明 |
|------|------|------|------|
| `prompt` | 是 | — | 编辑指令（≤5000 字符） |
| `video_url` | 是 | — | 输入视频 http(s) 公网 URL，MP4/MOV，3–60 秒，≤100 MB |
| `image_urls` | 否 | — | 参考图 URL 数组，0–5 张，用于风格 / 角色参考 |
| `audio_setting` | 否 | `auto` | 音频处理方式：`auto`（自动）/ `origin`（保留原声） |
| `watermark` | 否 | `false` | 是否添加"AI 生成"水印 |
| `seed` | 否 | — | 随机种子 [0, 2147483647] |

**示例**

```bash
curl -X POST https://www.jlike.com/api/v1/openapi/happyhorse-edit/generate \
  -H "Authorization: Bearer sk-xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "tier": "hd",
    "prompt": "将视频中的背景替换为日落海滩",
    "video_url": "https://example.com/input.mp4",
    "audio_setting": "origin"
  }'
```

**轮询**

```bash
curl https://www.jlike.com/api/v1/openapi/happyhorse-edit/task/<task_uuid> \
  -H "Authorization: Bearer sk-xxxxxxxx"
```

> 计费 duration ≈ 输入视频时长 + 输出视频时长，预冻结按最大 30 秒，结算按实际用量返还差额。视频 URL 约 24 小时有效。

---

### RunningHub 图生视频

```
POST /api/v1/openapi/rh-i2v/generate
GET  /api/v1/openapi/rh-i2v/task/{task_uuid}
```

输入参考图 + 提示词，生成 3–5 秒短视频。上游 RunningHub ComfyUI 工作流。建议每 5–10 秒轮询。

| tier | 说明 | 单价 |
|------|------|------|
| `std`（唯一档位） | 标准版 | ¥0.3 / 秒 |

| 字段 | 必填 | 默认 | 说明 |
|------|------|------|------|
| `image_url` | 是 | — | 参考图 http(s) 公网 URL |
| `prompt` | 是 | — | 文字描述 |
| `duration` | 否 | `5` | 3–5 秒，计费按此值预冻结 |
| `tier` | 否 | `std` | 仅支持 `std` |

**示例**

```bash
curl -X POST https://www.jlike.com/api/v1/openapi/rh-i2v/generate \
  -H "Authorization: Bearer sk-xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "image_url": "https://example.com/photo.png",
    "prompt": "女生缓缓转头微笑",
    "duration": 5
  }'
```

**轮询**

```bash
curl https://www.jlike.com/api/v1/openapi/rh-i2v/task/<task_uuid> \
  -H "Authorization: Bearer sk-xxxxxxxx"
```

> 视频 URL 约 24 小时有效，请尽快下载。`cost` 优先按上游返回的真实时长结算；上游未返回时长字段时回退到入参 `duration` 预估值，差额自动 unfreeze。

---

### RhartVs 图生视频（RunningHub）

```
POST /api/v1/openapi/rhart-vs/generate
GET  /api/v1/openapi/rhart-vs/task/{task_uuid}
```

输入单张图 + 提示词，生成 10 秒或 15 秒动态视频。上游 RunningHub 标准模型 `rhart-video-s/image-to-video`。提交后立即返回 `task_uuid`，建议每 10–15 秒轮询。终态结果缓存，**重复查询不会再次扣费**。

| tier | 说明 | 单价 |
|------|------|------|
| `std`（唯一档位） | 标准版 | ¥0.20 / 秒（10s≈¥2.0 · 15s≈¥3.0） |

| 字段 | 必填 | 默认 | 说明 |
|------|------|------|------|
| `prompt` | 是 | — | 5–4000 字符 |
| `image_url` | 是* | — | 单张参考图，http(s) URL 或 `data:image/...;base64,...` |
| `image_file_id` | 是* | — | 与 `image_url` 二选一；`/openapi/files/upload` 返回的 file_id |
| `duration` | 否 | `10` | 仅支持 `10` / `15`（秒） |
| `aspect_ratio` | 否 | `9:16` | 仅支持 `9:16` / `16:9` |
| `storyboard` | 否 | `false` | 透传上游分镜模式开关 |
| `tier` | 否 | `std` | 仅支持 `std` |

> \* `image_url` 与 `image_file_id` 至少给一个。单张 ≤ 50 MB。

**示例**

```bash
curl -X POST https://www.jlike.com/api/v1/openapi/rhart-vs/generate \
  -H "Authorization: Bearer sk-xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "0–2秒：狸花猫翘着二郎腿斜眼笑；2–5秒：哈士奇一愣；5–10秒：哈士奇瞬间石化，全场爆笑收尾。",
    "image_url": "https://example.com/podcast.png",
    "duration": 10,
    "aspect_ratio": "9:16",
    "storyboard": false
  }'
```

**轮询**

```bash
curl https://www.jlike.com/api/v1/openapi/rhart-vs/task/<task_uuid> \
  -H "Authorization: Bearer sk-xxxxxxxx"
```

**成功响应字段**

| 字段 | 说明 |
|------|------|
| `video_url` | 输出视频 URL（**约 24 小时有效，请尽快下载**） |
| `duration_sec` | 实际计费的视频秒数（优先取上游真实时长，缺省时回退到入参 `duration`） |

> 上传 base64 时服务端会先调 `/openapi/v2/media/upload/binary` 转成 RunningHub 内部 URL 再交给上游；用 OSS file_id 的话服务端会签出有效期 30 分钟的预签 URL 给上游。`cost` 优先按上游真实时长结算，差额自动从冻结额度回滚。

---

## 音频生成

### 声音克隆 TTS

```
POST /api/v1/openapi/voice-clone/generate
GET  /api/v1/openapi/voice-clone/task/{task_uuid}
```

输入参考音频 + 要合成的文字，输出克隆参考音色朗读该文字的音频。上游 RunningHub ComfyUI 工作流。提交后立即返回 `task_uuid`，建议每 5–10 秒轮询一次。终态结果缓存，**重复查询不会再次扣费**。

| tier | 说明 | 单价 |
|------|------|------|
| `std`（唯一档位） | 标准版 | ¥0.01 / 秒（不足 1 秒按 1 秒计） |

| 字段 | 必填 | 默认 | 说明 |
|------|------|------|------|
| `audio_url` | 是 | — | 参考音频 http(s) 公网 URL，建议 m4a / mp3 / wav |
| `prompt` | 是 | — | 要合成的文字内容 |
| `tier` | 否 | `std` | 仅支持 `std` |

> **计费时长估算**：服务端以 `ceil(prompt 字符数 / 3)` 估算输出音频秒数（最低 1 秒），freeze 与 confirm 用同一估算值，所以你可以从 `prompt` 长度直接预估费用。如：100 字 ≈ 34 秒 ≈ ¥0.34。

**示例**

```bash
curl -X POST https://www.jlike.com/api/v1/openapi/voice-clone/generate \
  -H "Authorization: Bearer sk-xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "audio_url": "https://example.com/ref.m4a",
    "prompt": "大家好啊，欢迎使用共享剪贴板的声音克隆能力。"
  }'
```

**轮询**

```bash
curl https://www.jlike.com/api/v1/openapi/voice-clone/task/<task_uuid> \
  -H "Authorization: Bearer sk-xxxxxxxx"
```

**成功响应字段**

| 字段 | 说明 |
|------|------|
| `audio_url` | 输出音频 URL（**约 24 小时有效，请尽快下载**） |
| `estimated_duration_sec` | 计费用的估算时长（秒）|
| `cost` / `currency` | 实际扣费金额与币种 |

> 若没有公网可达的参考音频，可先用 `/openapi/files/upload`（`purpose=audio`）拿到临时 `public_url` 再传入。`cost` 优先按上游返回的真实合成时长结算；上游未返回时长字段时回退到 `prompt` 长度估算（3 字/秒、向上取整、最低 1 秒），差额自动 unfreeze。

---

### AI 音乐生成

```
POST /api/v1/openapi/music-gen/generate
GET  /api/v1/openapi/music-gen/task/{task_uuid}
```

输入歌曲标题 + 歌词/描述 + 风格标签，生成一首完整的 AI 音乐。上游 RunningHub Suno v5.5。提交后立即返回 `task_uuid`，建议每 5–10 秒轮询一次。终态结果缓存，**重复查询不会再次扣费**。

| tier | 说明 | 单价 |
|------|------|------|
| `std`（唯一档位） | 标准版 | 按曲计费（固定价格，见 `/openapi/pricing`） |

| 字段 | 必填 | 默认 | 说明 |
|------|------|------|------|
| `title` | 是 | — | 歌曲标题，1–80 字符 |
| `prompt` | 是 | — | 歌词或描述，1–5000 字符 |
| `tags` | 是 | — | 风格标签，英文逗号分隔，1–1000 字符（如 `pop,electronic,female vocal`） |
| `tier` | 否 | `std` | 仅支持 `std` |

**示例**

```bash
curl -X POST https://www.jlike.com/api/v1/openapi/music-gen/generate \
  -H "Authorization: Bearer sk-xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "夏日微风",
    "prompt": "温柔的夏天午后，阳光洒在窗台上，微风轻轻吹过白色窗帘。",
    "tags": "pop,chill,acoustic,female vocal"
  }'
```

**轮询**

```bash
curl https://www.jlike.com/api/v1/openapi/music-gen/task/<task_uuid> \
  -H "Authorization: Bearer sk-xxxxxxxx"
```

**成功响应字段**

| 字段 | 说明 |
|------|------|
| `audio_url` | 输出音频 URL（**约 24 小时有效，请尽快下载**） |
| `cost` / `currency` | 实际扣费金额与币种 |

> 本接口按曲计费，每次生成固定扣费一次，不按时长结算。具体单价请查询 `/openapi/pricing?service=music-gen`。

---

## 工具

### 临时文件上传

```
POST   /api/v1/openapi/files/upload
GET    /api/v1/openapi/files/{file_id}/url
DELETE /api/v1/openapi/files/{file_id}
```

将本地图片/视频/音频上传到 OSS，返回 presigned 公网 URL（默认有效期 2 小时），供手势舞 / 跳舞换装 / 首尾帧 / 图生视频等需要公网 URL 入参的端点使用。上传与重新获取下载 URL 都会按文件大小计费，响应中返回 `cost` 和 `currency`。

| 字段 | 必填 | 说明 |
|------|------|------|
| `file` | 是 | 二进制文件（multipart/form-data），上限 200 MB |
| `purpose` | 否 | `image` / `video` / `audio` / `other`（默认 `other`） |

**成功响应**

```json
{
  "success": true,
  "file_id": 123,
  "public_url": "https://oss.../openapi/temp/...",
  "expires_at": 1714920000,
  "size_bytes": 1048576,
  "mime_type": "image/png",
  "purpose": "image",
  "cost": 0.02,
  "currency": "CNY",
  "upload_mode": "created",
  "sha256": "e3b0c44298fc1c149afbf4c8996fb924..."
}
```

> NanoBanana / Wan 2.7 的 `image_file_ids` 字段可直接传此处返回的 `file_id`。若 `public_url` 过期，可调用 `GET /api/v1/openapi/files/{file_id}/url` 重新获取；该操作同样按文件大小计费。OSS 设有 `openapi/temp/` 前缀 1 天生命周期自动清理。
>
> **SHA 去重**：服务端先按 `(user_id, sha256)` 查同名文件，命中已有未删除记录时返回 `upload_mode: "exists"` + 已有 `file_id`，**不计费、不重新上传 OSS**。客户端无需感知此差异，但循环上传同一份图（典型场景：dance 系列任务反复用同一首帧图）会显著省钱。`upload_mode` 仅有 `"created"` / `"exists"` 两种取值。

---

### 价格清单

```
GET /api/v1/openapi/pricing
```

实时返回当前所有 service / model / metric 的销售单价（即按此扣减用户余额的单价）。后台改价后立即生效。

**查询参数**

| 字段 | 必填 | 说明 |
|------|------|------|
| `service` | 否 | 仅返回指定 service，如 `gemini3` / `nanobanana` / `wan27-video` / `happyhorse` 等 |
| `currency` | 否 | 强制返回币种（`CNY` / `USD` / `EUR`），缺省走调用方账户结算货币 |

**成功响应**

```json
{
  "success": true,
  "currency": "CNY",
  "rate_from_cny": 1.0,
  "generated_at": "2026-05-08T12:00:00Z",
  "services": {
    "nanobanana": [
      { "model_id": "gemini-2.5-flash-image", "tier": "fast", "metric": "per_image_2K", "unit": "image", "price": 0.36 }
    ],
    "gemini3": [
      { "model_id": "gemini-3.1-pro-preview", "tier": "pro", "metric": "input_lt_200k",  "unit": "million_tokens", "price": 14.40 },
      { "model_id": "gemini-3.1-pro-preview", "tier": "pro", "metric": "output_lt_200k", "unit": "million_tokens", "price": 86.40 }
    ]
  }
}
```

字段说明：
- `services.<service>[].metric`：计费维度，常见值 `per_image_512` / `per_image_1K` / `per_image_2K` / `per_image_4K` / `input_lt_200k` / `input_gte_200k` / `output_lt_200k` / `output_gte_200k` / `cache_hit_input` / `cache_miss_input` / `output` / `per_second` / `per_mb`。
- `services.<service>[].unit`：单价对应的计量单位（`image` / `million_tokens` / `second` / `mb`），与 `price` 配合解读。
- `services.<service>[].price`：按 `unit` 的单价；外币响应已按 `rate_from_cny` 换算。

> 本接口仅返回销售价，不暴露成本价、毛利率等内部字段。响应未做 ETag/HTTP 缓存，建议客户端按需轮询（如每 5–15 分钟）或在调用计费接口失败前重新拉取。

---

## 错误码

| HTTP | 场景 |
|------|------|
| `400` | 请求体非法（tier/model 不支持、字段超范围、必填字段缺失，或 DeepSeek 端点显式 `stream=true`） |
| `401` | API Key 无效 / 已吊销 |
| `402` | 余额不足 |
| `422` | 上游成功但未返回任何图片（如内容被安全策略拦截） |
| `429` | 速率限制 |
| `502` | 上游返回错误 |
| `503` | 服务未开放 / 上游 Key 未配置 |
| `504` | 上游超时 |

**失败响应统一格式**

```json
{
  "success": false,
  "error": "错误描述",
  "error_code": "INVALID_PARAMS"
}
```

---

## 最佳实践

- 务必把 `sk-` 明文保存到**服务端**安全存储，不要嵌入浏览器 JS / 客户端二进制
- 上线前为每个环境创建独立 Key（dev / staging / prod），方便吊销和审计
- 监控响应中的 `_billing.cost` / `cost` / `actual_cost`
- Wan 2.7 图片轮询间隔以 3 秒为宜；Wan 2.7 图生视频建议 10–15 秒一次；手势舞 / 跳舞换装 / 首尾帧 / RunningHub 图生视频 / 声音克隆 TTS 建议 5–10 秒一次；终态缓存，重复查询不会再次扣费
- Key 泄漏后立即在账户中心**吊销**，然后创建新 Key 替换