{
  "markdown": "<p align=\"center\">\n  <picture>\n    <source media=\"(prefers-color-scheme: dark)\" srcset=\"assets/lovart-icon.svg\" />\n    <source media=\"(prefers-color-scheme: light)\" srcset=\"assets/lovart-icon-dark.svg\" />\n    <img src=\"assets/lovart-icon-dark.svg\" width=\"96\" height=\"96\" alt=\"Lovart\" />\n  </picture><br/>\n  <strong>lovart-skill</strong><br/><br/>\n  <a href=\"https://github.com/lovartai/lovart-skill/releases\"><img src=\"https://img.shields.io/github/v/release/lovartai/lovart-skill\" alt=\"Release\" /></a>\n  <a href=\"LICENSE\"><img src=\"https://img.shields.io/badge/License-MIT-blue.svg\" alt=\"License: MIT\" /></a>\n  <a href=\"https://python.org\"><img src=\"https://img.shields.io/badge/Python-3.6+-green.svg\" alt=\"Python 3.6+\" /></a><br/>\n  <strong>English</strong> | <a href=\"README_CN.md\">简体中文</a> | <a href=\"README_TW.md\">繁體中文</a> | <a href=\"README_JA.md\">日本語</a>\n</p>\n<br/>\n\n> Lovart AI Agent Skills — generate images, video, and audio from any\n> AI coding assistant. One `SKILL.md`, two install paths.\n\n## ✨ What it does\n\nThis skill connects your AI coding assistant to Lovart's Agent OpenAPI.\nIt works with both the [OpenClaw](https://openclaw.com) and [Hermes Agent](https://github.com/l3ad3r1/Hermes-skills) ecosystems out of the box, and also runs from any assistant that can invoke Python scripts. Capabilities:\n\n- 🖼️ **Image generation** — posters, logos, illustrations, banners, mockups, etc.\n- 🎬 **Video generation** — clips, animations, product videos\n- 🎵 **Audio generation** — BGM, songs, sound effects\n- ✂️ **Image/video editing** — upscale, reframe, style transfer\n- 🧊 **3D generation** — 3D models from text or images\n- 📁 **Project & thread management** — multi-project support with local state persistence\n\n## 📦 Install\n\nChoose the path that matches your agent ecosystem. **OpenClaw is the\nofficially published distribution** (`npx skills add` pulls the\nlatest release from ClawHub); **Hermes Agent is a manual install**\nyou copy into your skills tree. Both paths install the same skill\nfiles; the difference is only in how the agent discovers and invokes\nthem.\n\nSet your credentials once either way — they are the same in both\necosystems:\n\n```bash\nexport LOVART_ACCESS_KEY=\"ak_xxx\"\nexport LOVART_SECRET_KEY=\"sk_xxx\"\n```\n\nGet your AK/SK from the Lovart platform (Avatar menu -> AK/SK Management).\n\n### OpenClaw\n\n```bash\nnpx skills add lovartai/lovart-skill\n```\n\nPulls the latest published release from ClawHub. OpenClaw installs\nthe skill into your project and auto-discovers it through its\n`metadata.openclaw` block.\n\n### Hermes Agent\n\nHermes Agent discovers skills from `~/.hermes/skills/<category>/<skill-name>/SKILL.md`.\nThis is a **manual / community install** — there is no automated\npublish target in this repo yet.\n\n```bash\ngit clone https://github.com/lovartai/lovart-skill.git\ncd lovart-skill\ncp -r skills/lovart-skill ~/.hermes/skills/design/lovart-api\n```\n\nHermes auto-triggers on any visual / audio creation request through\nits `metadata.hermes.tags` block. From your Hermes chat:\n\n```\n/lovart-api draw a cyberpunk cat in neon city\n```\n\n> 💡 The two paths install identical skill files — the `SKILL.md`\n> ships dual-format frontmatter, so the same artifact serves both\n> ecosystems without modification.\n\n## 🚀 Quick start\n\n```bash\n# Generate an image\npython3 scripts/agent_skill.py chat --prompt \"a cyberpunk cat in neon city\" --json --download\n\n# Generate a video\npython3 scripts/agent_skill.py chat --prompt \"ocean waves crashing on rocks, cinematic\" --json --download\n\n# Generate BGM\npython3 scripts/agent_skill.py chat --prompt \"lofi hip-hop, chill, study vibes\" --json --download\n```\n\n## 🛠️ Commands\n\n### Generation\n\n| Command | Description |\n|---------|-------------|\n| `chat` | Send prompt, wait for completion, return all results at once. Main command. |\n| `watch` | Send prompt and stream artifacts as they complete (NDJSON, incremental delivery) |\n| `send` | Send prompt without waiting (returns thread_id immediately) |\n| `confirm` | Confirm a pending high-cost operation (e.g. video), then wait |\n| `result` | Get results for a thread |\n| `status` | Check thread status |\n\n### Project management\n\n| Command | Description |\n|---------|-------------|\n| `projects` | List all projects |\n| `project-add` | Add and switch to a project |\n| `project-switch` | Switch active project (supports prefix match) |\n| `project-rename` | Rename a project |\n| `project-remove` | Remove a project and its threads |\n| `create-project` | Create a new empty project on the server |\n\n### Configuration\n\n| Command | Description |\n|---------|-------------|\n| `config` | View/update local settings (`~/.lovart/state.json`) |\n| `threads` | List saved conversation threads |\n| `set-mode` | Switch between fast (credits) / unlimited (queue) mode |\n| `query-mode` | Check current generation mode |\n\n### File operations\n\n| Command | Description |\n|---------|-------------|\n| `upload` | Upload a local file to CDN (returns URL) |\n| `upload-artifact` | Upload a URL artifact to a project |\n| `download` | Download artifacts from URLs |\n\n## 💡 Usage examples\n\n```bash\n# Use an existing project\npython3 scripts/agent_skill.py chat --project-id PROJECT_ID --prompt \"draw a cat\" --json --download\n\n# Continue a conversation (thread reuse preserves context)\npython3 scripts/agent_skill.py chat --thread-id THREAD_ID --prompt \"make it blue\" --json --download\n\n# Stream artifacts as they complete (NDJSON, for multi-image/video requests)\npython3 scripts/agent_skill.py watch --prompt \"generate 4 variations of a cyberpunk cat\"\n\n# Edit with reference image\npython3 scripts/agent_skill.py upload --file photo.jpg\npython3 scripts/agent_skill.py chat --prompt \"change the style to watercolor\" --attachments \"CDN_URL\" --json --download\n\n# Prefer a specific model\npython3 scripts/agent_skill.py chat --prompt \"draw a cat\" \\\n  --prefer-models '{\"IMAGE\":[\"generate_image_midjourney\"]}' --json --download\n\n# Force a specific tool (e.g. upscale instead of re-generate)\npython3 scripts/agent_skill.py chat --prompt \"upscale this image\" \\\n  --include-tools upscale_image --attachments \"IMAGE_URL\" --json --download\n\n# Thinking mode — deep structured reasoning for complex requests\npython3 scripts/agent_skill.py chat --prompt \"design a brand identity for a coffee startup\" \\\n  --mode thinking --json --download\n\n# Project management\npython3 scripts/agent_skill.py projects\npython3 scripts/agent_skill.py project-add --project-id NEW_ID --name \"My Brand Kit\"\npython3 scripts/agent_skill.py project-switch --project-id NEW_ID\npython3 scripts/agent_skill.py threads\n```\n\n## 🎯 Model selection\n\nYou can control which model the Agent uses in three ways:\n\n1. **In the prompt** (simple) — `\"generate ocean waves video using kling\"`\n2. **`--prefer-models`** (soft preference) — `'{\"IMAGE\":[\"generate_image_midjourney\"]}'`\n3. **`--include-tools`** (strongest steer, not an enforced whitelist) — `upscale_image`\n\n`--include-tools` is a strong instruction the Agent normally follows, but it may still pick\nanother tool — for example after the requested one rejects the input. `--exclude-tools` is\naccepted for forward compatibility and currently has no effect on tool selection.\n\n## 🖼️ Reference subjects\n\n`--attachments` takes any image URL and each new URL is reviewed again. For a reference that\nalready lives in the asset library, pass its library URL with `--subjects` so the existing\nreview is reused and the Agent knows the subject is approved:\n\n```bash\npython3 scripts/agent_skill.py chat --prompt \"put these characters in one scene\" \\\n  --subjects '[{\"url\":\"LIBRARY_URL\",\"asset_id\":\"asset_xxx\",\"display_name\":\"Hero\"}]' \\\n  --json --download\n```\n\n## ⚠️ Rejected tool calls\n\nA run can finish `done` and still have had tool calls rejected — the Agent may drop a\nreference or switch models and carry on. The result carries a `failures` array plus a\none-line `warning`. Read it before reporting success; retrying a rejected reference with the\nsame input will fail again and still costs credits.\n\nAvailable models:\n\n| Category | Tool name | Display name | Premium |\n|---|---|---|---|\n| IMAGE | `generate_image_gpt_image_2` | GPT Image 2 Auto |  |\n| IMAGE | `generate_image_gpt_image_2_low` | GPT Image 2 Low |  |\n| IMAGE | `generate_image_gpt_image_2_medium` | GPT Image 2 Medium |  |\n| IMAGE | `generate_image_gpt_image_2_high` | GPT Image 2 High |  |\n| IMAGE | `generate_image_nano_banana_pro` | Nano Banana Pro |  |\n| IMAGE | `generate_image_nano_banana_2` | Nano Banana 2 |  |\n| IMAGE | `generate_image_seedream_v5_pro` | Seedream 5.0 Pro |  |\n| IMAGE | `generate_image_gpt_image_1_5` | GPT Image 1.5 |  |\n| IMAGE | `generate_image_seedream_v5` | Seedream 5.0 Lite |  |\n| IMAGE | `generate_image_luma_uni_1` | Luma uni-1 |  |\n| IMAGE | `generate_image_luma_uni_1_max` | Luma uni-1-max |  |\n| IMAGE | `generate_image_flux_2_max` | Flux.2 Max |  |\n| IMAGE | `generate_image_flux_2_pro` | Flux.2 Pro |  |\n| IMAGE | `generate_image_seedream_v4_5` | Seedream 4.5 |  |\n| IMAGE | `generate_image_nano_banana` | Nano Banana |  |\n| IMAGE | `generate_image_seedream_v4` | Seedream 4 |  |\n| IMAGE | `generate_image_midjourney` | Midjourney |  |\n| IMAGE | `generate_image_ideogram_v4` | Ideogram 4 |  |\n| IMAGE | `generate_image_qwen_image3` | Qwen Image3 |  |\n| IMAGE | `generate_image_qwen_image3_pro` | Qwen Image3 Pro |  |\n| IMAGE | `generate_image_nano_banana_2_lite` | Nano Banana 2 Lite |  |\n| IMAGE | `generate_image_p_image_ideogram` | Ideogram P-Image |  |\n| VIDEO | `generate_video_seedance_v2_5` | Seedance 2.5 | ⭐ Premium |\n| VIDEO | `generate_video_seedance_v2_0` | Seedance 2.0 | ⭐ Premium |\n| VIDEO | `generate_video_seedance_v2_0_fast` | Seedance 2.0 Fast | ⭐ Premium |\n| VIDEO | `generate_video_seedance_v2_0_mini` | Seedance 2.0 Mini | ⭐ Premium |\n| VIDEO | `generate_video_kling_v3` | Kling 3.0 | ⭐ Premium |\n| VIDEO | `generate_video_kling_v3_omni` | Kling 3.0 Omni | ⭐ Premium |\n| VIDEO | `generate_video_minimax_h3` | MiniMax H3 | ⭐ Premium |\n| VIDEO | `generate_video_seedance_pro_v1_5` | Seedance 1.5 Pro |  |\n| VIDEO | `generate_video_kling_v2_6` | Kling 2.6 | ⭐ Premium |\n| VIDEO | `generate_video_wan_v2_6` | Wan 2.6 |  |\n| VIDEO | `generate_video_veo3_1` | Veo 3.1 | ⭐ Premium |\n| VIDEO | `generate_video_veo3_1_fast` | Veo 3.1 Fast | ⭐ Premium |\n| VIDEO | `generate_video_kling_omni_v1` | Kling O1 | ⭐ Premium |\n| VIDEO | `generate_video_hailuo_v2_3` | Hailuo 2.3 |  |\n| VIDEO | `generate_video_veo3` | Veo 3 | ⭐ Premium |\n| VIDEO | `generate_video_vidu_q2` | Vidu Q2 |  |\n| VIDEO | `generate_video_gemini_omni_flash` | Gemini Omni Flash | ⭐ Premium |\n| VIDEO | `generate_video_minimax_h3_max` | MiniMax H3 Max | ⭐ Premium |\n| VIDEO | `generate_video_wan_v3` | Wan 3.0 | ⭐ Premium |\n| VIDEO | `generate_video_wan_v3_prime` | Wan 3.0 Prime | ⭐ Premium |\n| 3D | `generate_3d_tripo` | Tripo |  |\n\n## 🧠 Reasoning modes\n\nControl how the agent thinks per request via `--mode`:\n\n- **`fast`** (default) — lightweight single-pass response. Faster, cheaper, suitable for simple one-shot generations.\n- **`thinking`** — deep structured reasoning with planning and multi-step analysis. Use for complex brand systems, multi-asset campaigns, anything that benefits from deliberate planning. Slower but higher quality.\n\n```bash\n# Quick, single-shot (default)\npython3 scripts/agent_skill.py chat --prompt \"draw a cat\"\n\n# Deliberate, plan-first reasoning\npython3 scripts/agent_skill.py chat --prompt \"design a full brand identity\" --mode thinking\n```\n\n**Mode is locked to the thread on its first message.** To switch modes, start a new thread (omit `--thread-id`). Mirrors the Lovart web UI toggle.\n\n## ⚡ Billing modes\n\nSeparate from reasoning mode. This is a persistent account-level billing setting:\n\n```bash\n# Fast — costs credits, no queue\npython3 scripts/agent_skill.py set-mode --fast\n\n# Unlimited — free, may queue\npython3 scripts/agent_skill.py set-mode --unlimited\n\n# Check current\npython3 scripts/agent_skill.py query-mode\n```\n\n## 🚦 Rate limits\n\nThe API enforces per-account request frequency limits, split into two tiers based on the endpoint you hit:\n\n| Tier | Endpoints | Per minute | Per hour |\n|------|-----------|-----------|---------|\n| **Chat** (write) | `/chat`, `/chat/confirm` | 60 | 600 |\n| **Query** (read) | `/chat/status`, `/chat/result`, `/project/*`, `/mode/*`, everything else | 300 | 3000 |\n\nThe stricter `Chat` tier protects generation. The `Query` tier is much looser so polling for status/results doesn't eat into your generation budget.\n\nExceeding a limit returns `HTTP 429` with `Retry-After: 60`.\n\nThis is separate from **generation concurrency** — each thread can only run one generation task at a time. If a task is already running in a thread, new requests to that thread are rejected with `HTTP 409` until it finishes. You can run tasks in different threads concurrently.\n\nThe skill auto-retries on transient network errors (3 attempts with backoff), but rate limit and billing errors are returned immediately.\n\n## 💾 Local state\n\nSettings and thread history are persisted at `~/.lovart/state.json`:\n\n```json\n{\n  \"active_project\": \"abc123...\",\n  \"projects\": {\n    \"abc123...\": {\"name\": \"My Project\", \"created_at\": \"...\"}\n  },\n  \"threads\": [\n    {\"id\": \"xxx\", \"project_id\": \"abc123...\", \"topic\": \"cyberpunk cat\", \"updated_at\": \"...\"}\n  ]\n}\n```\n\n## 🤖 Integration\n\nThe skill works with multiple agent ecosystems. Pick the one that\nmatches yours.\n\n### OpenClaw\n\n```bash\nnpx skills add lovartai/lovart-skill\n```\n\nOpenClaw reads `metadata.openclaw` from `SKILL.md` and auto-discovers\nthe skill after install — no extra configuration beyond the env vars.\n\n### Hermes Agent\n\nDrop the skill into `~/.hermes/skills/<category>/<skill-name>/` (see\nthe Hermes subsection under `Install` above). Hermes reads\n`metadata.hermes` and routes visual / audio creation requests to the\nskill via its `/lovart-api` slash command.\n\n### Other AI assistants\n\nThe skill also works with Claude Code, Cursor, and any assistant that\ncan invoke Python scripts directly. See `SKILL.md` for the full\nintegration contract.\n\n## 📁 Project structure\n\n```\nlovart-skill/\n├── README.md\n├── README_CN.md\n├── README_TW.md\n├── README_JA.md\n└── skills/\n    └── lovart-skill/\n        ├── SKILL.md                 # Skill contract (dual-format: OpenClaw + Hermes)\n        └── scripts/\n            └── agent_skill.py       # Python client (zero dependencies)\n```\n\n## 🔒 Security & privacy\n\n- **Local state file**: The skill reads/writes `~/.lovart/state.json` to persist your active project and recent thread IDs. No other files are accessed.\n- **Outbound calls**: Only talks to the Lovart API (`https://lgw.lovart.ai`) and Lovart CDN (for downloading your own generated artifacts). No third-party services.\n- **API keys**: AK/SK are read from env vars (`LOVART_ACCESS_KEY` / `LOVART_SECRET_KEY`) and signed with HMAC-SHA256 per request. Keys are never logged or persisted to disk.\n- **TLS**: SSL certificate verification is **enabled by default**. Set `LOVART_INSECURE_SSL=1` to disable (only if you're behind a corporate proxy/VPN that intercepts TLS).\n- **Source code**: `skills/lovart-skill/scripts/agent_skill.py` is ~900 lines of pure Python standard library — you're encouraged to read it before installing.\n\n## 🏗️ Architecture\n\n```\nOpenClaw / Hermes Agent / Claude Code / other AI assistant\n  -> scripts/agent_skill.py (this skill)\n    -> Lovart OpenAPI (AK/SK HMAC-SHA256 auth)\n      -> Lovart AI Agent (model selection, orchestration)\n        -> Generated images / videos / audio\n```\n\n## 🤝 Contributing\n\nContributions are welcome! Feel free to:\n\n- [Open an issue](https://github.com/lovartai/lovart-skill/issues) to report bugs or suggest features\n- [Submit a pull request](https://github.com/lovartai/lovart-skill/pulls) to fix issues or add improvements\n\n\n## 📄 License\n\n[MIT](LICENSE)\n",
  "bytes": 15790,
  "sha": "fadae8cda97f26ee10dd84a5c57a0322c98692ecb85f10b91b919cb412adfa1b",
  "repo_slug": "lovartai/lovart-skill",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/skl_lovartai_lovart_skill_lovart_api_e19cbbd7/readme"
}