Lovart API

⚠️ 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:

⚠️ 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.

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:

1. Use --download flag with chat (or result)
2. 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

1. Append the project canvas link: https://www.lovart.ai/canvas?projectId={project_id}
2. Check failures in the result. When it is non-empty, tell the user which reference or model was refused and why — the Agent may have dropped an input or switched models to finish, so the delivered result can differ from what they asked for. Never report a clean success while failures is non-empty.

⚠️ 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.