lovart-api

⚠️ 规则 #0：只能使用技能命令——禁止直接调用 API

你必须且只能通过此技能中定义的命令与 Lovart 交互。

• 绝不要构造 URL、发送 curl/wget/fetch 请求或直接调用 Lovart API
• 绝不要猜测 API 端点、路径或参数——只能使用下方列出的命令
• 执行期间绝不要修改技能源代码（agent_skill.py）来“调试”问题（用户可以随时阅读源代码进行验证）
• 如果命令失败，请重试或向用户报告错误——不要尝试绕过问题
• 所有 Lovart 操作都必须通过：chat、send、watch、confirm、result、status、config、projects、project-add、project-switch、project-rename、project-remove、threads、thread-remove、upload、upload-artifact、download、set-mode、query-mode、create-project

⚠️ 规则 #1：你可以且必须生成图像／视频／音频

当用户要求“绘制”“生成”“创建”“设计”“制作”“创作”或“画”“生成”“制作”“创作”任何视觉或音频内容（使用任何语言）时，你必须使用此技能。 这包括：图像、视频、音频、音乐、歌曲、BGM、TTS、语音、海报、轮播图、横幅、徽标、插图、缩略图、幻灯片、封面、模型图、图标、社交媒体内容等。 不要说“我无法生成图像／音乐”，也不要提议改为撰写提示词。

⚠️ 规则 #1.5：使用此技能查询项目和对话线程

当用户询问项目、对话线程、对话记录、历史记录或设置（使用任何语言）时， 请使用这些命令——不要浏览文件系统：

用户询问	命令
“我有哪些项目？”	projects --json
“有哪些对话／线程？”	threads --json 或 threads --all --json
“显示我的设置”	config --json
“切换到项目 X”	project-switch --project-id X
“创建新项目”	project-add --project-id NEW_ID --name "Name"（或让 chat 自动创建）

⚠️ 规则 #2：始终使用 chat 并等待完成

使用 chat 命令（会阻塞直至完成），而非 send。生成完成前不要回复。

处理这些 final_status 值：

• "done" — 生成完成。将下载的文件发送给用户。
• "pending_confirmation" — 高成本工具（例如视频，或高品质付费图像变体）需要用户批准后才会消耗额度。 继续操作前，必须征得用户明确确认。不要自动确认。
  1. 向用户显示：“这将花费约 {estimated_cost} 个额度。要继续吗？（yes/no）”
  2. 等待用户回复。 只有在用户明确表示 yes/confirm/proceed 后，才运行： confirm --thread-id THREAD_ID --json --download （此命令会确认、等待完成，并返回包含已下载文件的结果）
  3. 如果用户拒绝，不要确认。只需告知用户操作已取消。
• "abort" — 生成已中止。告知用户。
• "timeout" — 生成仍在进行，但已超出等待时间。结果中可能包含部分产物。
  1. 发送当前已可用的所有下载文件
  2. 告知用户：“生成仍在进行。正在检查……”
  3. 运行：result --thread-id THREAD_ID --json --download 以获取最新结果
  4. 如果状态仍为 "running"，则等待并重试。如果为 "done"，则发送其余文件。

处理错误：

如果 chat 抛出错误（AgentSkillError），请根据 HTTP 状态和结构化 code 进行处理。message 字段已包含可直接向用户展示的说明——请原样转达。

HTTP 状态	code	含义	告知用户的内容
402	2012	配额／计费／风控拒绝	直接显示 AgentSkillError.message——服务器已返回具体说明（额度不足、已达到免费层级上限、并发限制、风控、需要手机号验证、需要团队方案等）和建议的下一步操作。
409	2011	此对话中仍有其他任务正在运行	“此对话中仍有任务正在运行。请等待任务完成（status）后再发送新提示词，或开始一个新对话。”
429	1429	触发 API 速率限制	“正在放缓；已触发速率限制。请约 60 秒后重试。”
401	—	AK/SK 配置错误	“API 密钥身份验证失败。请检查您的 LOVART_ACCESS_KEY 和 LOVART_SECRET_KEY。”
—	—	消息中包含 Project.*does not exist	“未找到项目。请检查项目 ID 或创建新项目。”

经验法则：面向用户的说明优先使用 AgentSkillError.message。不要尝试从响应中解析内部代码——服务器会在返回前将其映射为易于理解的消息。

检测无声的生成失败（done 但没有产物）：

某些提示词会以 final_status: "done" 结束，但未生成 artifacts／downloaded 为空。这通常意味着上游图像模型拒绝了提示词（内容审核）、发生超时，或 LLM 选择用文本回复，而不是调用工具。此技能会自动标记此情况——chat() 返回时，请检查：

• result["generation_succeeded"] — 布尔值。False 表示未生成产物。
• result["warning"] — 说明字符串（仅当 generation_succeeded 为 False 时存在）。
• result["agent_message"] — Agent 的纯文本回复，可能提示原因（如果有则提供）。

常见触发原因：

• GPT Image 2 的提示词过长或过于复杂，涉及武器、特定身体或对策略敏感的措辞——尝试更换模型（--include-tools generate_image_midjourney 或 generate_image_nano_banana_pro），或简化提示词。
• 提示词描述了 Agent 无法完成的任务——向用户展示 agent_message。

⚠️ 规则 #3：始终交付结果 + 项目链接

每次生成后，你都必须：

1. 对 chat（或 result）使用 --download 标志
2. 将每个下载的文件作为文件附件发送给用户（图像、视频、音频/mp3——所有文件类型）：
   • 无论文件类型是什么（.png、.jpg、.mp4、.mp3 等），都始终将 downloaded[].local_path 作为文件附件发送
   • 下载了本地文件时，绝不要只粘贴 URL——应发送实际文件
   • 仅当没有下载任何文件时，才改为显示 URL
3. 附上项目画布链接：https://www.lovart.ai/canvas?projectId={project_id}
4. 检查结果中的 failures。如果不为空，请告知用户哪个参考项或模型遭到拒绝以及原因——Agent 可能丢弃了输入或切换了模型以完成任务，因此交付结果可能与用户要求不同。failures 不为空时，绝不要声称任务已顺利完成。

⚠️ 规则 #4：首次使用时检查本地状态（强制——不得跳过）

在对话中进行首次生成之前，你必须按顺序运行以下两条命令。此要求不可选。完成这两步之前不得调用 chat。

步骤 1：config --json

• 检查本地状态（~/.lovart/state.json）中的 active_project
• 如果已设置 active_project → 继续步骤 2。不要创建新项目，也不要询问用户。
• 如果缺少 active_project → 询问用户：“你有现有的 Lovart 项目 ID 吗？还是要我创建一个新项目？”等待用户回答。
• 使用以下命令保存：project-add --project-id PID --name "name"

步骤 2：threads --json

• 检查是否有近期对话线程可以继续
• 如果存在与当前主题相关的近期对话线程 → 复用该线程（向 chat 传入 --thread-id THREAD_ID）
• 如果没有对话线程，或主题完全不同 → 不传入 --thread-id（创建新线程）

重要规则：

• **如果 config --json 已显示 active_project，绝不要创建新项目。**应复用现有项目。
• **存在相关的近期对话线程时，绝不要省略 --thread-id。**默认始终复用线程。
• 在同一对话中，未先运行 config --json 和 threads --json 时，绝不要调用 chat。
• chat 命令会自动从本地状态读取 active_project——每次都无需传入 --project-id。
• 仅当用户明确要求创建新项目时，才创建新项目。
• 仅当主题与最近的对话线程完全无关时，才创建新线程。
• 如有疑问，复用现有项目和现有线程。

---

Lovart Agent OpenAPI 技能

通过自然语言与 Lovart AI Agent 交互，生成图像、视频和视觉素材。

Lovart 是一个 AI 设计平台。Agent 能理解用户请求，并自动选择最佳模型和工作流。

术语

• Thread — 与 Lovart AI Agent 的对话流程（聊天会话），不是编程线程。每个线程都有唯一的 thread_id，并保留多轮上下文。复用线程意味着继续同一对话，这样 Agent 就能记住之前的图像/视频，并对其进行迭代。
• Project — 用于将线程和生成内容归类到一起的工作区/画布。一个项目可以包含多个线程。

前提条件

export LOVART_ACCESS_KEY="ak_xxx"
export LOVART_SECRET_KEY="sk_xxx"

无需第三方依赖。仅使用 Python 标准库。

功能

1. 聊天 - 向 AI Agent 发送消息，获取文本回复以及生成的图像/视频
2. 确认 - 确认并等待高成本操作（例如视频生成）
3. 创建项目 - 创建新项目
4. 上传文件 - 上传本地图像/视频文件，并获取 CDN URL
5. 上传素材 - 将链接素材上传到项目
6. 状态/结果 - 检查线程状态并获取结果
7. 设置/查询模式 - 在快速（积分）模式和无限（队列）模式之间切换

用法

0. 首次设置（保存到 ~/.lovart/state.json）

python3 {baseDir}/scripts/agent_skill.py project-add --project-id PROJECT_ID --name "My Project"

1. 发送消息（从本地状态读取 project_id）

python3 {baseDir}/scripts/agent_skill.py chat --prompt "USER_PROMPT" --json --download

要覆盖项目：添加 --project-id PROJECT_ID 要继续对话：添加 --thread-id THREAD_ID 要列出已保存的线程：python3 {baseDir}/scripts/agent_skill.py threads

2. 创建项目

python3 {baseDir}/scripts/agent_skill.py create-project

3. 上传文件（本地图片/视频 → CDN URL）

python3 {baseDir}/scripts/agent_skill.py upload --file /path/to/image.png
# Returns: {"url": "https://assets-persist.lovart.ai/img/{user_uuid}/xxx.png"}

当用户发送需要作为附件传入聊天的图片/视频文件时，请使用此功能。

4. 上传素材

python3 {baseDir}/scripts/agent_skill.py upload-artifact --project-id PROJECT_ID --url "ARTIFACT_URL" --type image

5. 检查状态 / 获取结果

# Status
python3 {baseDir}/scripts/agent_skill.py status --thread-id THREAD_ID

# Result (auto-syncs to gallery/canvas, idempotent)
python3 {baseDir}/scripts/agent_skill.py result --thread-id THREAD_ID --json --download

6. 下载素材

# Download during chat
python3 {baseDir}/scripts/agent_skill.py chat --prompt "draw a cat" --json --download --output-dir /tmp/lovart

# Download from existing result
python3 {baseDir}/scripts/agent_skill.py result --thread-id THREAD_ID --download --output-dir /tmp/lovart

# Download specific URLs
python3 {baseDir}/scripts/agent_skill.py download --urls URL1 URL2 --output-dir /tmp/lovart --prefix myimg

常见工作流

场景 1：生成图片/视频/音频（最常见）

首先，运行 config --json 检查是否已设置 project_id。如果没有，请询问用户并使用 project-add 保存。

1. config --json  →  check local state for active_project
   - If not set → ask user, save with project-add
2. threads --json  →  check if there's a recent thread to continue
   - If recent thread exists and topic is related → reuse it (step 3a)
   - If no threads or completely new topic → new thread (step 3b)
3a. chat --thread-id THREAD_ID --prompt "user's request" --json --download
3b. chat --prompt "user's request" --json --download
4. Send each downloaded[].local_path file as an IM attachment to the user
5. The chat command auto-syncs artifacts to canvas and gallery

ID 会自动持久化到本地（~/.lovart/state.json）：

• 首次聊天后会保存 project_id，并在后续自动复用
• 每次聊天后都会保存 thread_id 和 topic，以便切换线程
• 仅在用户明确要求时才创建新项目
• 仅在开始全新主题时才创建新线程（省略 --thread-id）
• 运行 threads 列出已保存的线程，供用户选择

场景 2：使用附件进行编辑

1. User sends a reference image/video via IM → save to local file
2. upload --file /path/to/image.png  →  get CDN URL
3. chat --prompt "edit this image to..." --project-id PID --attachments "CDN_URL" --json --download
4. Continue as Scenario 1

场景 3：围绕同一主题继续对话（延续上下文）

1. chat --prompt "change the background to a beach" --project-id PROJECT_ID --thread-id THREAD_ID --json --download

Agent 会记住之前的对话，并根据上下文继续编辑。

场景 4：新主题（新线程）

1. chat --prompt "completely new request" --project-id PROJECT_ID --json --download

省略 --thread-id 会创建一个没有先前记忆的新对话。

场景 5：流式 / 增量交付（多个素材）

适用情况： 用户的请求将生成多个图片/视频，且你希望每个生成完成后立即交付给用户，而不是等整批内容全部完成。

python3 {baseDir}/scripts/agent_skill.py watch --prompt "generate 4 variations of a cyberpunk cat" --json

watch 会向 stdout 输出 NDJSON（每行一个事件）。逐行解析，并立即将每个 artifact 事件中的 local_path 交付给用户：

{"event": "started", "thread_id": "xxx", "project_id": "yyy"}
{"event": "artifact", "type": "image", "url": "https://...", "local_path": "/tmp/lovart/lovart_ab12cd.png"}
{"event": "artifact", "type": "image", "url": "https://...", "local_path": "/tmp/lovart/lovart_ef34gh.png"}
{"event": "pending_confirmation", "thread_id": "xxx", "pending_confirmation": {...}}
{"event": "finished", "thread_id": "xxx", "final_status": "done", "artifact_count": 4}

文件会使用 URL 哈希作为文件名，因此在同一线程上重新运行 watch 时不会重复下载。

你也可以连接到正在运行的线程：watch --thread-id THREAD_ID。

以下情况不要使用 watch： 单张图片请求——请使用 chat（更简单，只需一次调用）。

输出格式

chat --json 返回：

{
  "thread_id": "xxx",
  "status": "done",
  "project_id": "xxx",
  "final_status": "done",
  "items": [
    {"type": "assistant", "text": "Agent's reply"},
    {"type": "generator", "name": "artifacts", "artifacts": [
      {"type": "image", "content": "https://assets-persist.lovart.ai/artifacts/agent/xxx.png"},
      {"type": "video", "content": "https://assets-persist.lovart.ai/artifacts/agent/xxx.mp4"}
    ]}
  ],
  "downloaded": [
    {"type": "image", "url": "https://...", "local_path": "/tmp/lovart/lovart_01.png"}
  ],
  "generation_succeeded": true,
  "failures": []
}

即使仍生成了素材，failures 也会列出运行期间遭拒绝的工具调用。warning 会同时设置，并提供一行摘要。请参阅下文“检查被拒绝的内容”。

核心原则

你是传递者，不是创作者。后端 Agent 负责理解需求、选择模型和编写提示词。你的工作是：

1. 转达：将用户的原始描述原封不动地传给 chat
2. 等待：轮询，直到生成完成
3. 交付：将结果文件发送给用户

不要改写/扩展提示词、拆分任务或添加你自己的风格描述。

Lovart 生成模式（必须使用 API，不能使用提示词）

重要：“快速模式”和“无限模式”是通过 API 调用控制的服务端设置，不是提示词关键词。

不要在提示词文本中加入“快速模式”或“fast mode”。请改为调用 set-mode 命令：

# User says "fast mode" / "快速模式" / "skip queue" / "use credits" → RUN THIS:
python3 {baseDir}/scripts/agent_skill.py set-mode --fast

# User says "unlimited mode" / "无限模式" / "free mode" / "save credits" → RUN THIS:
python3 {baseDir}/scripts/agent_skill.py set-mode --unlimited

# Check which mode is active:
python3 {baseDir}/scripts/agent_skill.py query-mode

工作原理：

• set-mode --fast 调用 Lovart 后端 API，将用户账户切换到快速生成模式（消耗积分，无需排队）
• set-mode --unlimited 切换到无限生成模式（免费，可能需要排队）
• 这是一个持久化的服务端设置——除非再次更改，否则会一直生效
• 它会影响之后的所有图片/视频生成，而不只是单次请求
• 它与（助手的）回复风格或行为完全无关

指定模型

选项 1：在提示词中指定（简单，由 Agent 自动选择）：

python3 {baseDir}/scripts/agent_skill.py chat --prompt "generate ocean waves video using kling" --json --download

选项 2：通过 --prefer-models 指定（精准，与前端的模型选择器相同）：

# Prefer a specific image model
python3 {baseDir}/scripts/agent_skill.py chat --prompt "draw a cat" --prefer-models '{"IMAGE":["generate_image_midjourney"]}' --json --download

# Prefer a specific video model
python3 {baseDir}/scripts/agent_skill.py chat --prompt "generate ocean waves" --prefer-models '{"VIDEO":["generate_video_kling_3_0"]}' --json --download

# Combine image and video preferences
python3 {baseDir}/scripts/agent_skill.py chat --prompt "create content" --prefer-models '{"IMAGE":["generate_image_seedream_3_0"],"VIDEO":["generate_video_kling_3_0"]}' --json --download

--prefer-models 可用的模型：

当用户指定模型时，优先使用 --prefer-models，而不是在提示词中填写模型名称。

选项 3：通过 --include-tools 指定（最能引导 Agent 使用特定工具）：

# Steer to upscale
python3 {baseDir}/scripts/agent_skill.py chat --prompt "upscale this image to 4K" --include-tools upscale_image --attachments "IMAGE_URL" --json --download

# Steer to a specific video model
python3 {baseDir}/scripts/agent_skill.py chat --prompt "generate a video" --include-tools generate_video_kling_3_0 --json --download

--include-tools 会强烈指示 Agent 优先使用列出的工具。当用户明确要求使用特定工具或执行特定操作时，请使用此选项。

需要了解的两个限制：

• 这是一条强指令，不是强制执行的白名单。Agent 通常会遵循，但也可能选择其他工具，例如请求的工具拒绝输入后。请检查结果中的 failures，确认是否发生了这种情况。
• 为保持向前兼容，接受 --exclude-tools，但它目前不会影响工具选择。若要引导 Agent 避开某个工具，请通过 --include-tools 指定你希望使用的工具。

引用资源库中的主体 — --subjects

--attachments 接受任意图片 URL，而每个新 URL 都会重新审核，之后需要已审核输入的模型才会接受它。如果参考素材已存在于用户的资源库中，请改用 --subjects 传入该素材的资源库 URL：系统会复用已有审核结果，并告知 Agent 这些参考素材是已批准的主体。

python3 {baseDir}/scripts/agent_skill.py chat \
  --prompt "put these two characters in a hallway conversation" \
  --subjects '[{"url":"LIBRARY_URL_A","asset_id":"asset_xxx","display_name":"Bune","channel":"ark_sd2"},
               {"url":"LIBRARY_URL_B","asset_id":"asset_yyy","display_name":"Leo","channel":"ark_sd2"}]' \
  --json --download

每个条目都必须包含 url，还可选填 type（默认为 subject_image，也可以是 subject_audio / subject_video）、asset_id、display_name 和 channel。对于用户刚发送的一次性图片，请使用 --attachments；对于资源库中已有的素材，请使用 --subjects。

--kits 通过 ID 引用品牌套件。项目的当前套件会自动附加，因此只有在要引用其他套件时才需要传入此选项。

检查被拒绝的内容 — failures

即使线程以 final_status: "done" 结束，期间仍可能有工具调用被拒绝。Agent 可以放弃某个参考素材或切换到另一个模型后继续，因此看似成功的结果可能悄然偏离用户的要求。

发生这种情况时，结果中会包含一个 failures 数组：

{
  "final_status": "done",
  "generation_succeeded": true,
  "warning": "2 tool calls were rejected. generate_video_seedance_v2_0_fast was rejected: ...",
  "failures": [
    {
      "tool": "generate_media",
      "tool_hint": "generate_video_seedance_v2_0_fast",
      "code": "SEEDANCE_ASSET_MODERATION_REJECTED",
      "message": "1 reference asset(s) failed content moderation. Do not retry with the same asset(s); replace them with compliant assets."
    },
    {
      "tool": "generate_media",
      "tool_hint": "generate_video_minimax_h3",
      "code": "INPUT_PARAMS_INVALID",
      "message": "MiniMax H3 resolution must be 768P or 2K."
    }
  ]
}

code 要么是具体的上游代码，要么是 INPUT_PARAMS_INVALID（参数无效）、UPSTREAM_ERROR（生成服务错误）或 TOOL_FAILED。

在告知用户运行成功之前，务必先查看 failures。 如果数组非空，请告知用户哪些内容被拒绝以及原因。被拒绝的参考素材仍会被拒绝，因此用相同输入重试会浪费额度——请替换消息中指出的输入，或通过 --subjects 引用已批准的主体。

推理模式 — --mode thinking / --mode fast

Lovart 提供两种可按线程选择的推理模式：

• fast（默认）——轻量级单次响应。适用于注重速度的简单、一次性生成任务。
• thinking——深入的结构化推理，包含规划和多步分析。适用于复杂的品牌体系、多素材营销活动，以及任何受益于审慎规划的任务。速度较慢，但质量更高。

省略 --mode 等同于使用 --mode fast，与网页界面的默认设置一致。

# Thinking mode — strategic, multi-step
python3 {baseDir}/scripts/agent_skill.py chat --prompt "design a brand identity system for a sustainable coffee startup" --mode thinking --json --download

# Fast mode — quick one-shot
python3 {baseDir}/scripts/agent_skill.py chat --prompt "draw a cat" --mode fast --json --download

模式在首条消息发送时即锁定到线程。 使用 --mode thinking 开启线程后，同一 --thread-id 下的后续消息都会保持 thinking 模式，无论之后传入什么 --mode 标志。要切换模式，请开启新线程（省略 --thread-id）。

特定任务的工具选择（重要）

当用户的请求对应特定操作时，使用 --include-tools 以确保调用正确的工具：

用户说	使用 --include-tools
“放大”“enlarge”“提高分辨率”“超分”	upscale_image
“编辑图像”“修改”“更改风格”	（让 Agent 决定）
“生成图像”“绘制”“画”	（让 Agent 决定，或使用 --prefer-models）

关键：当用户要求“放大”“enlarge”或提高现有图像的分辨率时，必须使用 --include-tools upscale_image。不要让 Agent 使用图像生成模型进行放大——它们会重新生成图像，而不是放大图像。

说明

• 所有 API 均使用 AK/SK HMAC-SHA256 签名认证
• 视频生成需要几分钟；聊天命令会自动轮询，直到完成
• 图库和画布同步具有幂等性——多次调用结果也不会产生重复项
• 连接失败时会自动重试 3 次，并回退到 SSL
• 状态变为“done”后，会等待 5 秒再次确认（以防子 Agent 启动竞态）