/lovart-skill

name: lovart-api
description: >-
  Generate images, videos, and audio/music via Lovart AI. Also manages Lovart projects,
  threads (conversation history), and user settings. Trigger on: (1) any visual or audio
  creation request in any language — draw, generate, create, design, make, 画, 生成,
  制作, 创作, 设计 combined with image, video, audio, music, song, BGM, poster, etc.
  (2) Lovart project/thread management — 项目, 对话, project, thread, conversation,
  history, 历史, 切换, switch. You CAN generate directly - never say you cannot.
user-invocable: true
version: 1.1.0
author: Lovart (lovartai)
license: MIT
homepage: https://github.com/lovartai/lovart-skill
platforms: [linux, macos, windows]
metadata:
  hermes:
    tags:
      - image-generation
      - video-generation
      - audio-generation
      - 3d
      - design
      - poster
      - logo
      - ai-art
    related_skills: []
  openclaw:
    emoji: 🎨
    requires:
      bins: [python3]
      env: [LOVART_ACCESS_KEY, LOVART_SECRET_KEY]
    primaryEnv: LOVART_ACCESS_KEY
prerequisites:
  commands: [python3]
  env: [LOVART_ACCESS_KEY, LOVART_SECRET_KEY]
  python: []

⚠️ RULE #0: ONLY USE SKILL COMMANDS — NO DIRECT API CALLS

**You MUST interact with Lovart EXCLUSIVELY through the commands defined in this skill.**

• NEVER construct URLs, make curl/wget/fetch requests, or call Lovart APIs directly
• NEVER guess API endpoints, paths, or parameters — only use the commands listed below
• NEVER modify the skill's source code (agent_skill.py) during execution to "debug" issues (users may freely read the source to verify it)
• If a command fails, retry it or report the error to the user — do NOT try to work around it
• ALL Lovart operations go through: `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`

⚠️ RULE #1: YOU CAN AND MUST GENERATE IMAGES/VIDEOS/AUDIO

When a user asks to "draw", "generate", "create", "design", "make", "画", "生成", "制作", "创作" any visual or audio content (in any language), you MUST use this skill. This includes: images, videos, audio, music, songs, BGM, TTS, voice, posters, carousels, banners, logos, illustrations, thumbnails, slides, covers, mockups, icons, social media content, etc. Do NOT say "I can't generate images/music" or offer to write prompts instead.

⚠️ RULE #1.5: PROJECT & THREAD QUERIES USE THIS SKILL

When the user asks about projects, threads, conversations, history, or settings (in any language), use these commands — do NOT browse the filesystem:

| User asks | Command | |-----------|---------| | "What projects do I have?" / "我有哪些项目" | `projects --json` | | "What conversations/threads?" / "有哪些对话" | `threads --json` or `threads --all --json` | | "Show my settings" / "我的配置" | `config --json` | | "Switch to project X" | `project-switch --project-id X` | | "Create a new project" | `project-add --project-id NEW_ID --name "Name"` (or let `chat` auto-create) |

⚠️ RULE #2: ALWAYS USE `chat` AND WAIT FOR COMPLETION

Use the `chat` command (blocks until done), NOT `send`. Do NOT reply before generation completes.

**Handle these `final_status` values:**

• `"done"` — Generation complete. Send the downloaded files to the user.
• `"pending_confirmation"` — A high-cost tool (e.g. video, or a premium-quality image variant) needs user approval before credits are consumed.

**You MUST ask the user for explicit confirmation before proceeding. Do NOT auto-confirm.** 1. Show the user: "This will cost approximately {estimated_cost} credits. Shall I proceed? (yes/no)" 2. **WAIT for user response.** Only if user explicitly says yes/confirm/proceed, run: `confirm --thread-id THREAD_ID --json --download` (This confirms, waits for completion, and returns the result with downloaded files) 3. If user declines, do NOT confirm. Just inform them the operation was cancelled.

• `"abort"` — Generation was aborted. Inform the user.
• `"timeout"` — Generation is still running but exceeded the wait time. The result may contain partial artifacts.

1. Send any downloaded files that are already available 2. Tell the user: "Generation is still in progress. Checking again..." 3. Run: `result --thread-id THREAD_ID --json --download` to get the latest results 4. If status is still "running", wait and retry. If "done", send remaining files.

**Handle errors:**

If `chat` throws an error (`AgentSkillError`), handle it by HTTP status and structured `code`. The `message` field already contains a user-ready explanation — surface it to the user as-is.

| HTTP status | `code` | What it means | What to tell the user | |---|---|---|---| | **`402`** | `2012` | Quota / billing / risk-control rejection | Show `AgentSkillError.message` directly — the server already returns a specific message (insufficient credits, free-tier reached, concurrent limit, risk control, phone verification, team plan required, etc.) and a suggested next step. | | **`409`** | `2011` | Another task is still running on this thread | "A task is still running on this conversation. Wait for it to finish (`status`) before sending a new prompt, or start a new thread." | | **`429`** | `1429` | API rate limit hit | "Slowing down; rate limit hit. Retry in ~60s." | | **`401`** | — | AK/SK misconfigured | "API key authentication failed. Please check your LOVART_ACCESS_KEY and LOVART_SECRET_KEY." | | — | — | `Project.*does not exist` in message | "Project not found. Please check the project ID or create a new one." |

Rule of thumb: prefer `AgentSkillError.message` for user-facing copy. Do not try to parse internal codes out of the response — the server already maps them to human-readable messages before returning.

**Detect silent generation failures (`done` with no artifact):**

Some prompts end with `final_status: "done"` but produce no `artifacts` / empty