lovart-api

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.0.11 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":"[Truncated]","env":"[Truncated]"},"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. Show the user: "This will cost approximately {estimated_cost} credits. Shall I proceed? (yes/no)" 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) 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. Send any downloaded files that are already available Tell the user: "Generation is still in progress. Checking again..." Run: result --thread-id THREAD_ID --json --download to get the latest results 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 downloaded . This usually means the upstream image model refused the prompt (content moderation), timed out, or the LLM chose to reply with text instead of calling a tool. The skill flags this automatically — when chat() returns, check: result["generation_succeeded"] — boolean. False means no artifact was produced. result["warning"] — explanation string (present only when generation_succeeded is False ). result["agent_message"] — the agent's plain-text reply that hints at why (present when available). Typical triggers: GPT Image 2 with very long/complex prompts involving weapons, specific bodies, or policy-sensitive wording — retry with a different model ( --include-tools generate_image_midjourney or generate_image_nano_banana_pro ) or simplify the prompt. Prompt that describes a task the agent can't fulfill — show agent_message to the user. ⚠️ RULE #3: ALWAYS DELIVER RESULTS + PROJECT LINK After EVERY generation, you MUST: Use --download flag with chat (or result ) Send each downloaded file to the user as a file attachment (images, videos, audio/mp3 — ALL file types): ALWAYS send downloaded[].local_path as file attachments, regardless of file type (.png, .jpg, .mp4, .mp3, etc.) NEVER just paste the URL when a local file has been downloaded — send the actual file Only fall back to displaying URLs if no files were downloaded Append the project canvas link: https://www.lovart.ai/canvas?projectId={project_id} ⚠️ RULE #4: CHECK LOCAL STATE ON FIRST USE (MANDATORY — DO NOT SKIP) Before the FIRST generation in a conversation, you MUST run these two commands IN ORDER. This is NOT optional. Do NOT call chat until you have done both. Step 1: config --json Check local state ( ~/.lovart/state.json ) for active_project If active_project is set → proceed to Step 2. Do NOT create a new project. Do NOT ask the user. If active_project is missing → ask the user: "Do you have an existing Lovart project ID, or should I create a new one?" WAIT for their answer. Save with: project-add --project-id PID --name "name" Step 2: threads --json Check if there's a recent thread to continue If recent thread exists and topic is related → REUSE it (pass --thread-id THREAD_ID to chat ) If no threads or completely different topic → omit --thread-id (creates new thread) CRITICAL RULES: NEVER create a new project if config --json already shows an active_project . Reuse it. NEVER omit --thread-id when a relevant recent thread exists. Always reuse threads by default. NEVER call chat without first running config --json and threads --json in the same conversation. The chat command auto-reads active_project from local state — you do NOT need to pass --project-id every time. Only create a new project if the user explicitly asks for one. Only create a new thread if the topic is completely unrelated to the most recent thread. When in doubt, REUSE both the existing project and the existing thread. Lovart Agent OpenAPI Skill Interact with Lovart AI Agent to generate images, videos, and visual assets via natural language. Lovart is an AI design platform. The Agent understands user requests and automatically selects the best model and workflow. Terminology Thread — A conversation flow (chat session) with the Lovart AI Agent, NOT a programming thread. Each thread has a unique thread_id and preserves multi-turn context. Reusing a thread means continuing the same conversation so the Agent remembers previous images/videos and can iterate on them. Project — A workspace/canvas that groups threads and generated artifacts together. One project can contain multiple threads. Prerequisites export LOVART_ACCESS_KEY= "ak_xxx" export LOVART_SECRET_KEY= "sk_xxx" No third-party dependencies. Python standard library only. Features Chat - Send a message to the AI Agent, get text replies and generated images/videos Confirm - Confirm and wait for high-cost operations (e.g. video generation) Create Project - Create a new project Upload File - Upload a local image/video file, get back a CDN URL Upload Artifact - Upload a link artifact to a project Status/Result - Check thread status and retrieve results Set/Query Mode - Switch between fast (credits) and unlimited (queue) mode Usage 0. First-time setup (saves to ~/.lovart/state.json) python3 {baseDir}/scripts/agent_skill.py project-add --project-id PROJECT_ID --name "My Project" 1. Send a message (reads project_id from local state) python3 {baseDir}/scripts/agent_skill.py chat --prompt "USER_PROMPT" --json --download To override project: add --project-id PROJECT_ID To continue a conversation: add --thread-id THREAD_ID To list saved threads: python3 {baseDir}/scripts/agent_skill.py threads 2. Create a project python3 {baseDir}/scripts/agent_skill.py create-project 3. Upload a file (local image/video → 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"} Use this when the user sends an image/video file that needs to be passed as an attachment to chat. 4. Upload an artifact python3 {baseDir}/scripts/agent_skill.py upload-artifact --project-id PROJECT_ID --url "ARTIFACT_URL" -- type image 5. Check status / get result # 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 artifacts # 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 Typical Workflows Scenario 1: Generate images/videos/audio (most common) First, run config --json to check if project_id is set. If not, ask the user and save with 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 IDs are auto-persisted locally ( ~/.lovart/state.json ): project_id is saved after first chat, reused automatically thread_id + topic are saved after each chat for thread switching Only create a new project if the user explicitly asks for one Only create a new thread (omit --thread-id ) when starting a completely new topic Run threads to list saved threads for the user to pick from Scenario 2: Edit with attachments 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 Scenario 3: Follow-up on same topic (continue context) 1. chat --prompt "change the background to a beach" --project-id PROJECT_ID --thread-id THREAD_ID --json --download The Agent remembers the previous conversation and can continue editing based on context. Scenario 4: New topic (new thread) 1. chat --prompt "completely new request" --project-id PROJECT_ID --json --download Omitting --thread-id creates a new conversation without previous memory. Scenario 5: Streaming / incremental delivery (multiple artifacts) Use when the user's request will produce multiple images/videos and you want to deliver each one to the user as soon as it's ready, rather than waiting for the whole batch. python3 {baseDir}/scripts/agent_skill.py watch --prompt "generate 4 variations of a cyberpunk cat" --json watch emits NDJSON to stdout (one event per line). Parse line-by-line and deliver each artifact event's local_path to the user immediately: { "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" : { ... } }