Lovart Api

<p align="center">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="assets/lovart-icon.svg" />
    <source media="(prefers-color-scheme: light)" srcset="assets/lovart-icon-dark.svg" />
    <img src="assets/lovart-icon-dark.svg" width="96" height="96" alt="Lovart" />
  </picture><br/>
  <strong>lovart-skill</strong><br/><br/>
  <a href="https://github.com/lovartai/lovart-skill/releases"><img src="https://img.shields.io/github/v/release/lovartai/lovart-skill" alt="Release" /></a>
  <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="License: MIT" /></a>
  <a href="https://python.org"><img src="https://img.shields.io/badge/Python-3.6+-green.svg" alt="Python 3.6+" /></a><br/>
  <a href="README.md">English</a> | <strong>简体中文</strong> | <a href="README_TW.md">繁體中文</a> | <a href="README_JA.md">日本語</a>
</p>
<br/>

> [Lovart](https://lovart.ai) 的 AI Agent Skills — 让你的 AI 编程助手轻松生成图片、视频和音频。

## ✨ 功能

将 [OpenClaw](https://openclaw.com)（及其他 AI 编程助手）连接到 Lovart Agent OpenAPI：

- 🖼️ **图片生成** — 海报、Logo、插画、Banner、Mockup 等
- 🎬 **视频生成** — 短片、动画、产品视频
- 🎵 **音频生成** — BGM、歌曲、音效
- ✂️ **图片/视频编辑** — 超分辨率、重构图、风格迁移
- 🧊 **3D 生成** — 从文本或图片生成 3D 模型
- 📁 **项目与会话管理** — 多项目支持，本地状态持久化

## 📦 安装

```bash
npx skills add lovartai/lovart-skill
```

然后设置环境变量：

```bash
export LOVART_ACCESS_KEY="ak_xxx"
export LOVART_SECRET_KEY="sk_xxx"
```

在 Lovart 平台获取 AK/SK（头像菜单 -> AK/SK 管理）。

> 🎉 **就这么简单！** Skill 文件会被添加到你的项目中，AI Agent 将自动识别并调用，无需手动执行任何脚本。

## 🚀 快速开始

```bash
# 生成图片
python3 agent_skill.py chat --prompt "赛博朋克风格的猫，霓虹城市背景" --json --download

# 生成视频
python3 agent_skill.py chat --prompt "海浪拍打岩石，电影感" --json --download

# 生成 BGM
python3 agent_skill.py chat --prompt "lofi hip-hop, chill, study vibes" --json --download
```

## 🛠️ 命令一览

### 生成

| 命令 | 说明 |
|------|------|
| `chat` | 发送 prompt，等待全部完成后一次性返回结果。主命令。 |
| `watch` | 发送 prompt 并流式返回 artifacts（NDJSON，生成一张交付一张） |
| `send` | 发送 prompt，不等待（立即返回 thread_id） |
| `confirm` | 确认高消耗操作（如视频生成），然后等待完成 |
| `result` | 获取会话结果 |
| `status` | 查询会话状态 |

### 项目管理

| 命令 | 说明 |
|------|------|
| `projects` | 列出所有项目 |
| `project-add` | 添加并切换到一个项目 |
| `project-switch` | 切换当前项目（支持前缀匹配） |
| `project-rename` | 重命名项目 |
| `project-remove` | 删除项目及其会话 |
| `create-project` | 在服务端创建新空项目 |

### 配置

| 命令 | 说明 |
|------|------|
| `config` | 查看/更新本地配置（`~/.lovart/state.json`） |
| `threads` | 列出保存的会话历史 |
| `set-mode` | 切换快速（消耗积分）/ 无限（排队）模式 |
| `query-mode` | 查询当前生成模式 |

### 文件操作

| 命令 | 说明 |
|------|------|
| `upload` | 上传本地文件到 CDN（返回 URL） |
| `upload-artifact` | 上传 URL 资产到项目 |
| `download` | 从 URL 下载资产 |

## 💡 使用示例

```bash
# 使用已有项目
python3 agent_skill.py chat --project-id PROJECT_ID --prompt "画一只猫" --json --download

# 继续对话（复用 thread 保留上下文）
python3 agent_skill.py chat --thread-id THREAD_ID --prompt "把背景换成蓝色" --json --download

# 流式返回（生成一张就交付一张，NDJSON 输出）
python3 agent_skill.py watch --prompt "生成 4 张赛博朋克猫的变体"

# 带参考图编辑
python3 agent_skill.py upload --file photo.jpg
python3 agent_skill.py chat --prompt "改成水彩画风格" --attachments "CDN_URL" --json --download

# 指定模型
python3 agent_skill.py chat --prompt "画一只猫" \
  --prefer-models '{"IMAGE":["generate_image_midjourney"]}' --json --download

# 强制使用特定工具（如超分而非重新生成）
python3 agent_skill.py chat --prompt "放大这张图" \
  --include-tools upscale_image --attachments "IMAGE_URL" --json --download

# Thinking 模式 — 面向复杂任务的深度结构化推理
python3 agent_skill.py chat --prompt "为咖啡品牌设计一套完整 VI" \
  --mode thinking --json --download

# 项目管理
python3 agent_skill.py projects
python3 agent_skill.py project-add --project-id NEW_ID --name "我的品牌套件"
python3 agent_skill.py project-switch --project-id NEW_ID
python3 agent_skill.py threads
```

## 🎯 模型选择

三种方式控制 Agent 使用的模型：

1. **在 prompt 中提及**（最简单）— `"用 kling 生成海浪视频"`
2. **`--prefer-models`**（软偏好）— `'{"IMAGE":["generate_image_midjourney"]}'`
3. **`--include-tools`**（硬约束）— `upscale_image`

可用模型：

<!-- AUTOGEN:models:start -->
<!-- AUTOGEN:models:end -->

## 🧠 推理模式

通过 `--mode` 控制每次请求的 agent 推理方式：

- **`fast`**（默认）— 轻量单轮响应。更快、更省，适合简单的一次性生成