lovart-skill

Lovart AI Agent Skills — generate images, video, and audio from any AI coding assistant. One SKILL.md, two install paths.

✨ What it does

This skill connects your AI coding assistant to Lovart's Agent OpenAPI. It works with both the OpenClaw and Hermes Agent ecosystems out of the box, and also runs from any assistant that can invoke Python scripts. Capabilities:

• 🖼️ Image generation — posters, logos, illustrations, banners, mockups, etc.
• 🎬 Video generation — clips, animations, product videos
• 🎵 Audio generation — BGM, songs, sound effects
• ✂️ Image/video editing — upscale, reframe, style transfer
• 🧊 3D generation — 3D models from text or images
• 📁 Project & thread management — multi-project support with local state persistence

📦 Install

Choose the path that matches your agent ecosystem. OpenClaw is the officially published distribution (npx skills add pulls the latest release from ClawHub); Hermes Agent is a manual install you copy into your skills tree. Both paths install the same skill files; the difference is only in how the agent discovers and invokes them.

Set your credentials once either way — they are the same in both ecosystems:

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

Get your AK/SK from the Lovart platform (Avatar menu -> AK/SK Management).

OpenClaw

npx skills add lovartai/lovart-skill

Pulls the latest published release from ClawHub. OpenClaw installs the skill into your project and auto-discovers it through its metadata.openclaw block.

Hermes Agent

Hermes Agent discovers skills from ~/.hermes/skills/<category>/<skill-name>/SKILL.md. This is a manual / community install — there is no automated publish target in this repo yet.

git clone https://github.com/lovartai/lovart-skill.git
cd lovart-skill
cp -r skills/lovart-skill ~/.hermes/skills/design/lovart-api

Hermes auto-triggers on any visual / audio creation request through its metadata.hermes.tags block. From your Hermes chat:

/lovart-api draw a cyberpunk cat in neon city

💡 The two paths install identical skill files — the SKILL.md ships dual-format frontmatter, so the same artifact serves both ecosystems without modification.

🚀 Quick start

# Generate an image
python3 scripts/agent_skill.py chat --prompt "a cyberpunk cat in neon city" --json --download

# Generate a video
python3 scripts/agent_skill.py chat --prompt "ocean waves crashing on rocks, cinematic" --json --download

# Generate BGM
python3 scripts/agent_skill.py chat --prompt "lofi hip-hop, chill, study vibes" --json --download

🛠️ Commands

Generation

Project management

Configuration

File operations

💡 Usage examples

# Use an existing project
python3 scripts/agent_skill.py chat --project-id PROJECT_ID --prompt "draw a cat" --json --download

# Continue a conversation (thread reuse preserves context)
python3 scripts/agent_skill.py chat --thread-id THREAD_ID --prompt "make it blue" --json --download

# Stream artifacts as they complete (NDJSON, for multi-image/video requests)
python3 scripts/agent_skill.py watch --prompt "generate 4 variations of a cyberpunk cat"

# Edit with reference image
python3 scripts/agent_skill.py upload --file photo.jpg
python3 scripts/agent_skill.py chat --prompt "change the style to watercolor" --attachments "CDN_URL" --json --download

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

# Force a specific tool (e.g. upscale instead of re-generate)
python3 scripts/agent_skill.py chat --prompt "upscale this image" \
  --include-tools upscale_image --attachments "IMAGE_URL" --json --download

# Thinking mode — deep structured reasoning for complex requests
python3 scripts/agent_skill.py chat --prompt "design a brand identity for a coffee startup" \
  --mode thinking --json --download

# Project management
python3 scripts/agent_skill.py projects
python3 scripts/agent_skill.py project-add --project-id NEW_ID --name "My Brand Kit"
python3 scripts/agent_skill.py project-switch --project-id NEW_ID
python3 scripts/agent_skill.py threads

🎯 Model selection

You can control which model the Agent uses in three ways:

1. In the prompt (simple) — "generate ocean waves video using kling"
2. --prefer-models (soft preference) — '{"IMAGE":["generate_image_midjourney"]}'
3. --include-tools (strongest steer, not an enforced whitelist) — upscale_image

--include-tools is a strong instruction the Agent normally follows, but it may still pick another tool — for example after the requested one rejects the input. --exclude-tools is accepted for forward compatibility and currently has no effect on tool selection.

🖼️ Reference subjects

--attachments takes any image URL and each new URL is reviewed again. For a reference that already lives in the asset library, pass its library URL with --subjects so the existing review is reused and the Agent knows the subject is approved:

python3 scripts/agent_skill.py chat --prompt "put these characters in one scene" \
  --subjects '[{"url":"LIBRARY_URL","asset_id":"asset_xxx","display_name":"Hero"}]' \
  --json --download

⚠️ Rejected tool calls

A run can finish done and still have had tool calls rejected — the Agent may drop a reference or switch models and carry on. The result carries a failures array plus a one-line warning. Read it before reporting success; retrying a rejected reference with the same input will fail again and still costs credits.

Available models:

🧠 Reasoning modes

Control how the agent thinks per request via --mode:

• fast (default) — lightweight single-pass response. Faster, cheaper, suitable for simple one-shot generations.