{"id":"805e4132-5353-48c0-a86a-c0675bfc895c","entityType":"agent","slug":"clawhub-pexo-pexo-video-agent","name":"Pexo Video Agent","canonicalUrl":"https://www.xpersona.co/agent/clawhub-pexo-pexo-video-agent","canonicalPath":"/agent/clawhub-pexo-pexo-video-agent","generatedAt":"2026-10-10T23:46:31.198Z","source":"CLAWHUB","claimStatus":"UNCLAIMED","verificationTier":"NONE","summary":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-10T21:40:56.140Z","emptyReason":null},"description":"Create finished multi-shot AI videos","descriptionLabel":"Source description","evidenceSummary":"Capability contract not published. No trust telemetry is available yet. 1.3K downloads reported by the source. Last updated 10/10/2026.","installCommand":"clawhub skill install s175307e49dag2pvn09nzmxzgs87hp6q:pexo-video-agent","sourceUrl":"https://clawhub.ai/pexo/pexo-video-agent","homepage":"https://clawhub.ai/pexo/skills/pexo-video-agent","primaryLinks":[{"label":"View on ClawHub","url":"https://clawhub.ai/pexo/pexo-video-agent","kind":"source"},{"label":"Homepage","url":"https://clawhub.ai/pexo/skills/pexo-video-agent","kind":"homepage"}],"safetyScore":84,"overallRank":62,"popularityScore":62,"trustScore":null,"claimedByName":null,"isOwner":false,"seoDescription":"Pexo Video Agent technical dossier on Xpersona with agent coverage, OPENCLEW support, and live trust metadata."},"coverage":{"evidence":{"source":"public-profile","verified":false,"confidence":"medium","updatedAt":"2026-10-10T21:40:56.140Z","emptyReason":null},"protocols":[{"protocol":"OPENCLEW","label":"OpenClaw","status":"self-declared","notes":"Declared in the public agent profile."}],"capabilities":[],"verifiedCount":0,"selfDeclaredCount":1,"capabilityMatrix":{"rows":[{"key":"OPENCLEW","type":"protocol","support":"unknown","confidenceSource":"profile","notes":"Listed on profile"}],"flattenedTokens":"protocol:OPENCLEW|unknown|profile"}},"adoption":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-10T21:40:56.140Z","emptyReason":null},"stars":null,"forks":null,"downloads":1250,"packageName":null,"latestVersion":"0.3.16","tractionLabel":"1.3K downloads"},"release":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-10T21:40:56.123Z","emptyReason":null},"lastUpdatedAt":"2026-10-10T21:40:56.140Z","lastCrawledAt":"2026-10-10T21:40:56.123Z","lastIndexedAt":null,"nextCrawlAt":"2026-10-11T21:40:56.123Z","lastVerifiedAt":null,"highlights":[{"version":"0.3.16","createdAt":"2026-08-20T07:47:07.704Z","changelog":"Add watermark-controlled downloads, harden diagnostics, and improve attachment delivery.","fileCount":15,"zipByteSize":36048},{"version":"0.1.4","createdAt":"2026-07-21T02:16:08.702Z","changelog":"Declare runtime requirements and require an explicit user-approval marker before any billing confirmation request.","fileCount":15,"zipByteSize":35317},{"version":"0.1.3","createdAt":"2026-07-21T02:07:21.706Z","changelog":"Pin authenticated traffic to the production Pexo origin, clarify safe URL handling, and disclose diagnostic network activity.","fileCount":15,"zipByteSize":34895},{"version":"0.1.2","createdAt":"2026-07-21T01:58:42.421Z","changelog":"Harden API-key setup, disclose data and permission boundaries, and require explicit approval for billable generation by default.","fileCount":15,"zipByteSize":34339},{"version":"0.1.1","createdAt":"2026-07-21T01:47:53.665Z","changelog":"Add explicit credit confirmation, hardened API-key config handling, reliable final-video delivery, and cross-agent compatibility.","fileCount":15,"zipByteSize":33818},{"version":"0.3.12","createdAt":"2026-07-21T01:41:48.580Z","changelog":"Add explicit credit confirmation, hardened API-key config handling, reliable final-video delivery, and cross-agent compatibility.","fileCount":15,"zipByteSize":33957},{"version":"0.1.0","createdAt":"2026-06-17T06:00:33.278Z","changelog":"Pexo video agent — make any video (ad, social, explainer, product, brand) via the hosted Pexo agent","fileCount":14,"zipByteSize":25819}]},"execution":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No published capability contract is available yet."},"installCommand":"clawhub skill install s175307e49dag2pvn09nzmxzgs87hp6q:pexo-video-agent","setupComplexity":"low","setupSteps":["Install using `clawhub skill install s175307e49dag2pvn09nzmxzgs87hp6q:pexo-video-agent` in an isolated environment before connecting it to live workloads.","No published capability contract is available yet, so validate auth and request/response behavior manually.","Review the upstream CLAWHUB listing at https://clawhub.ai/pexo/pexo-video-agent before using production credentials."],"contract":{"contractStatus":"missing","authModes":[],"requires":[],"forbidden":[],"supportsMcp":false,"supportsA2a":false,"supportsStreaming":false,"inputSchemaRef":null,"outputSchemaRef":null,"dataRegion":null,"contractUpdatedAt":null,"sourceUpdatedAt":null,"freshnessSeconds":null},"invocationGuide":{"preferredApi":{"snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-pexo-pexo-video-agent/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-pexo-pexo-video-agent/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-pexo-pexo-video-agent/trust"},"curlExamples":["curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-pexo-pexo-video-agent/snapshot\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-pexo-pexo-video-agent/contract\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-pexo-pexo-video-agent/trust\""],"jsonRequestTemplate":{"query":"summarize this repo","constraints":{"maxLatencyMs":2000,"protocolPreference":["OPENCLEW"]}},"jsonResponseTemplate":{"ok":true,"result":{"summary":"...","confidence":0.9},"meta":{"source":"CLAWHUB","generatedAt":"2026-10-10T23:46:31.191Z"}},"retryPolicy":{"maxAttempts":3,"backoffMs":[500,1500,3500],"retryableConditions":["HTTP_429","HTTP_503","NETWORK_TIMEOUT"]}},"endpoints":{"dossierUrl":"https://www.xpersona.co/api/v1/agents/clawhub-pexo-pexo-video-agent/dossier","snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-pexo-pexo-video-agent/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-pexo-pexo-video-agent/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-pexo-pexo-video-agent/trust"}},"reliability":{"evidence":{"source":"runtime-metrics","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No trust, reliability, or runtime telemetry is available."},"trust":{"status":"unavailable","handshakeStatus":"UNKNOWN","verificationFreshnessHours":null,"reputationScore":null,"p95LatencyMs":null,"successRate30d":null,"fallbackRate":null,"attempts30d":null,"trustUpdatedAt":null,"trustConfidence":"unknown","sourceUpdatedAt":null,"freshnessSeconds":null},"decisionGuardrails":{"doNotUseIf":["Contract metadata is missing or unavailable for deterministic execution."],"safeUseWhen":[],"riskFlags":["missing_or_unavailable_contract","trust_data_unavailable","schema_references_missing"],"operationalConfidence":"low"},"executionMetrics":{"observedLatencyMsP50":null,"observedLatencyMsP95":null,"estimatedCostUsd":null,"uptime30d":null,"rateLimitRpm":null,"rateLimitBurst":null,"lastVerifiedAt":null,"verificationSource":null},"runtimeMetrics":{"successRate":null,"avgLatencyMs":null,"avgCostUsd":null,"hallucinationRate":null,"retryRate":null,"disputeRate":null,"p50Latency":null,"p95Latency":null,"lastUpdated":null}},"benchmarks":{"evidence":{"source":"no-benchmark-data","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No benchmark suites or observed failure patterns are available."},"suites":[],"failurePatterns":[]},"artifacts":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-10T21:40:56.140Z","emptyReason":null},"readme":"Skill: Pexo Video Agent\n\nOwner: pexo\n\nSummary: Create finished multi-shot AI videos\n\nTags: latest:0.3.16\n\nVersion history:\n\nv0.3.16 | 2026-08-20T07:47:07.704Z | user\n\nAdd watermark-controlled downloads, harden diagnostics, and improve attachment delivery.\n\nv0.1.4 | 2026-07-21T02:16:08.702Z | user\n\nDeclare runtime requirements and require an explicit user-approval marker before any billing confirmation request.\n\nv0.1.3 | 2026-07-21T02:07:21.706Z | user\n\nPin authenticated traffic to the production Pexo origin, clarify safe URL handling, and disclose diagnostic network activity.\n\nv0.1.2 | 2026-07-21T01:58:42.421Z | user\n\nHarden API-key setup, disclose data and permission boundaries, and require explicit approval for billable generation by default.\n\nv0.1.1 | 2026-07-21T01:47:53.665Z | user\n\nAdd explicit credit confirmation, hardened API-key config handling, reliable final-video delivery, and cross-agent compatibility.\n\nv0.3.12 | 2026-07-21T01:41:48.580Z | user\n\nAdd explicit credit confirmation, hardened API-key config handling, reliable final-video delivery, and cross-agent compatibility.\n\nv0.1.0 | 2026-06-17T06:00:33.278Z | user\n\nPexo video agent — make any video (ad, social, explainer, product, brand) via the hosted Pexo agent\n\nArchive index:\n\nArchive v0.3.16: 15 files, 36048 bytes\n\nFiles: agents/openai.yaml (249b), references/SETUP-CHECKLIST.md (3766b), references/TROUBLESHOOTING.md (13980b), scripts/_common.sh (13616b), scripts/pexo-asset-get.sh (3904b), scripts/pexo-billing-confirm.sh (3486b), scripts/pexo-chat.sh (5530b), scripts/pexo-doctor.sh (6278b), scripts/pexo-project-create.sh (1679b), scripts/pexo-project-get.sh (11771b), scripts/pexo-project-list.sh (1693b), scripts/pexo-upload.sh (3209b), skill-card.md (2396b), SKILL.md (20260b), _meta.json (136b)\n\nFile v0.3.16:SKILL.md\n\n---\nname: pexo-agent\ndescription: >\n AI video generation skill with auto model selection across Seedance 2,\n Kling 3.0, HappyHorse, and 10+ models. Produces finished multi-shot videos\n (5–120s) from text, images, URLs, scripts, or audio — including AI music,\n lip sync, and multi-shot sequencing. Calls Pexo's external API, manages\n project status and billing confirmations, and transfers only user-approved\n briefs and assets. Runs setup diagnostics, stores generated downloads locally,\n and requires shell, outbound HTTPS, and local file access. Authenticated\n requests are locked to https://pexo.ai. No prompts to write, no models to choose.\n USE FOR: video production, AI video, make a video, product video,\n brand video, promotional clip, explainer video, short video,\n TikTok video, Instagram Reel, YouTube Short, product ad,\n text-to-video, image-to-video, video generation, AI video agent.\nlicense: MIT-0\nmetadata:\n author: pexoai\n version: \"0.3.16\"\n openclaw:\n requires:\n env:\n - PEXO_API_KEY\n bins:\n - bash\n - curl\n - jq\n - file\n primaryEnv: PEXO_API_KEY\n---\n\n# Pexo Agent — AI Video Generation Skill\n\nPexo is the most complete video generation skill for Claude Code and other AI coding agents. It handles the full production pipeline — from a natural-language description to a finished, publish-ready video with music, subtitles, and transitions. Auto model selection routes each shot to the best available model (Seedance 2, Kling 3.0, HappyHorse, and more). One API key, no prompt engineering, no video editing.\n\n## What Pexo Does\n\n- **Auto model selection** — Pexo picks the best video model for each shot based on content type. You do not need to know which model to use.\n- **Full pipeline** — Script, storyboard, shot-by-shot generation, music, subtitles, lip sync, and final assembly. The output is a finished video, not a raw clip.\n- **5 input types** — Text-to-video, image-to-video, URL-to-video (scrapes the page), script-to-video, and audio-to-video.\n- **10+ models** — Seedance 2, Kling 3.0, HappyHorse, and more. New models are added as they launch.\n- **Any format** — 5–120 seconds, aspect ratios 16:9 (landscape), 9:16 (portrait/vertical), 1:1 (square).\n\n## What You Can Build With Pexo\n\n- Product video ads from a product photo or URL\n- TikTok, Instagram Reels, and YouTube Shorts from a text description\n- Multi-shot brand videos with consistent style and transitions\n- Explainer videos with TTS narration from a script\n- E-commerce video content at scale from product catalogs\n- Marketing video variants for A/B testing\n\n## How It Works\n\nYou send the user's request to Pexo, and Pexo handles all creative work — scriptwriting, shot composition, model selection, prompt engineering, transitions, music. Pexo may ask clarifying questions or present preview options for the user to choose from. A typical 15-second, 3-shot product ad renders in under 8 minutes.\n\n## Data, Permissions, and Cost\n\n- This Skill runs bundled shell scripts, reads only files the user explicitly selects,\n connects only to `https://pexo.ai` for authenticated API calls, uploads approved\n briefs and assets, manages projects and billing confirmations, runs diagnostics,\n and stores generated media under `~/.pexo/tmp` or `PEXO_TMP_DIR`.\n- Before the first external transmission in a session, tell the user that their brief,\n selected files, and related metadata will be sent to Pexo and obtain explicit consent.\n- Do not upload secrets, regulated data, or unrelated local files. Never search the local\n filesystem for additional material without a separate user request.\n- Every billable generation batch requires explicit user approval by default. Report the\n available estimate from Pexo before approving a confirmation.\n\n## Script Execution\n\nResolve `SKILL_ROOT` to the directory containing this `SKILL.md`. Script names\nbelow are shorthand for `bash \"$SKILL_ROOT/scripts/\"`; do not rely\non executable bits or a modified `PATH`.\n\n## Prerequisites\n\nConfig file `~/.pexo/config`:\n\n```bash\numask 077\nmkdir -p ~/.pexo\nread -rsp \"Pexo API key: \" pexo_api_key\nprintf '\\n'\n{\n printf '%s=%s\\n' PEXO_API_KEY \"$pexo_api_key\"\n} > ~/.pexo/config\nunset pexo_api_key\nchmod 600 ~/.pexo/config\n```\n\nFirst time using this skill or encountering a config error → run `pexo-doctor.sh` and follow its output. See `references/SETUP-CHECKLIST.md` for details.\n\n### Credit Confirmation Preference\n\n`PEXO_BILLING_CONFIRMATION_MODE` controls the confirmation behavior for each message sent by this Skill. It is optional; the default is `always`.\n\n- `always`: ask for approval before every billable generation batch.\n- `threshold`: ask when the estimated batch cost exceeds the platform threshold, or when the available balance is insufficient. Use only after the user explicitly opts in for the current session.\n\nUse `pexo-chat.sh --billing-confirmation-mode ` to override the default for one message.\n\n---\n\n## ⚠️ LANGUAGE RULE (highest priority)\n\n**You MUST reply to the user in the SAME language they use. This is non-negotiable.**\n\n- User writes in English → you reply in English\n- User writes in Chinese → you reply in Chinese\n- User writes in Japanese → you reply in Japanese\n\nThis applies to every message you send. If the user switches language mid-conversation, you switch too.\n\n---\n\n## Your Role: Delivery Worker\n\nYou are a delivery worker between the user and Pexo. You do three things:\n\n1. **Upload**: user gives a file → `pexo-upload.sh` → get asset ID\n2. **Relay**: copy the user's words into `pexo-chat.sh`\n3. **Deliver**: poll for results → send video and link to user\n\nPexo's backend is a professional video creation agent. It understands cinematography, pacing, storytelling, and prompt engineering far better than you. When you add your own creative ideas, the video quality goes down.\n\n### How to relay messages — copy-paste template\n\nWhen calling pexo-chat.sh, copy the user's message exactly:\n\n```\npexo-chat.sh \"{user's message, copied exactly}\"\n```\n\nExample — user said \"做个猫的视频\":\n```\npexo-chat.sh proj_123 \"做个猫的视频\"\n```\n\nExample — user said \"I want a product video for my shoes\" and uploaded shoes.jpg:\n```\nasset_id=$(pexo-upload.sh proj_123 shoes.jpg)\npexo-chat.sh proj_123 \"I want a product video for my shoes ${asset_id}\"\n```\n\nYour only addition to the user's message is asset tags for uploaded files. Everything else stays exactly as the user wrote it.\n\n### When the user's request is vague\n\nPass it to Pexo exactly as-is. Pexo will ask the user for any missing details. Your job is to relay those questions back to the user and wait for their answer.\n\n### Why this matters\n\nPexo's backend agent specializes in video production. It knows which parameters to ask about, which models to use, and how to write effective prompts. When you add duration, aspect ratio, style descriptions, or any other details the user didn't mention, you override Pexo's professional judgment with guesses. This produces worse videos.\n\n---\n\n## First-Time Setup Message\n\nAfter Pexo is configured for the first time, send the user this message (in the user's language):\n\n> ✅ Pexo is ready!\n> 📖 Guide: https://pexo.ai/connect/openclaw\n> Tell me what video you'd like to make.\n\n---\n\n## Step-by-Step Workflow\n\nFollow these steps in order.\n\n### Making a New Video\n\n```\nStep 1. Create project.\n Run: pexo-project-create.sh \"brief description\"\n If the command succeeds: save the returned project_id.\n If the command fails and stderr contains \"Credits balance\"\n or \"credits\" or \"Insufficient credits\":\n → Go to Credit Error Handling below.\n If the command fails for other reasons:\n → Tell the user what went wrong and offer to retry.\n\nStep 2. Upload files (if user provided any images/videos/audio).\n Run: pexo-upload.sh \n Save the returned asset_id.\n Wrap in tag: asset_id\n (or / for other file types)\n\nStep 3. Send user's message to Pexo.\n Run: pexo-chat.sh \"{user's exact words} asset_id\"\n Copy the user's words exactly. Only add asset tags for uploaded files.\n If the command fails and stderr contains \"Credits balance\"\n or \"credits\" or \"Insufficient credits\":\n → Go to Credit Error Handling below.\n If the command fails for other reasons:\n → Tell the user what went wrong and offer to retry.\n\nStep 4. Notify the user (in the user's language).\n Your message must contain these three items:\n - Confirmation that the request is submitted to Pexo\n - Estimated time: 15–20 minutes for a short video\n - Project link: https://pexo.ai/project/{project_id}\n\nStep 5. Poll for status.\n Run: sleep 60\n Run: pexo-project-get.sh \n Read the nextAction field from the returned JSON.\n Continue to Step 6.\n\nStep 6. Act on nextAction:\n\n \"WAIT\" →\n Go back to Step 5. Keep repeating.\n Every 5 polls (~5 minutes), send user a brief update with\n the project link: https://pexo.ai/project/{project_id}\n\n \"CONFIRM\" →\n Read the confirmation object. It contains confirmation_id, estimated_credits,\n available_credits, sufficient, and the pending tool batch.\n\n If sufficient is false:\n Tell the user that the available credits cannot cover this request.\n Go to Credit Error Handling below. Do not run pexo-billing-confirm.sh.\n\n If sufficient is true:\n Tell the user the estimated credit cost and ask for explicit approval.\n Do not approve on the user's behalf.\n\n After explicit approval:\n Run: pexo-billing-confirm.sh --user-approved\n Go back to Step 5.\n\n If the user changes the request instead:\n Run: pexo-chat.sh \"{user's exact revised request}\"\n This cancels the pending confirmation before submitting the new message.\n Go back to Step 5.\n\n \"RESPOND\" →\n Read the recentMessages array. Handle every event:\n\n Event \"message\" (Pexo sent text):\n Relay Pexo's text to the user in full.\n If Pexo asked a question, wait for the user's answer.\n Then run: pexo-chat.sh \"{user's exact answer}\"\n Go back to Step 5.\n\n Event \"preview_video\" (Pexo sent preview options):\n For each assetId in assetIds:\n Run: pexo-asset-get.sh \n Copy the \"url\" field from the returned JSON.\n Show all preview URLs to the user with labels (A, B, C...).\n Ask the user to pick one.\n After user picks:\n Run: pexo-chat.sh \"{user's choice}\" --choice \n Go back to Step 5.\n\n Event \"document\":\n Mention the document to the user.\n\n Event \"attachment\":\n Fetch each assetId with pexo-asset-get.sh and deliver the resulting file or URL.\n\n \"DELIVER\" →\n Go to Step 7.\n\n \"FAILED\" →\n Go to Step 8.\n\n \"RECONNECT\" →\n Run: pexo-chat.sh \"continue\"\n Tell the user the connection was interrupted and you are reconnecting.\n Go back to Step 5.\n\nStep 7. Deliver the final video.\n\n 7a. Relay any message events in recentMessages, then find the final_video\n event and get its assetId.\n\n 7b. Decide the download variant from the user's request:\n - Default: download without a watermark.\n - If the user explicitly asks to keep, show, or add a watermark, use\n the watermarked variant.\n - Both variants require an active subscription or watermark whitelist.\n\n 7c. Run one of:\n - pexo-asset-get.sh \n (default, no watermark)\n - pexo-asset-get.sh --with-watermark\n (only when explicitly requested)\n\n 7d. Show the downloaded video file to the user.\n\n 7e. Also send the user a message (in their language) with:\n - The video download URL (copy the \"url\" field from the JSON output).\n Send the FULL URL as plain text, including all query parameters.\n Example:\n https://pexo-assets.oss-us-east-1.aliyuncs.com/projects%2F123%2Fassets%2Fvideo.mp4?OSSAccessKeyId=xxx&Expires=xxx&Signature=xxx\n - Project page: https://pexo.ai/project/{project_id}\n - Ask if satisfied or want revisions.\n\n Common delivery mistakes to avoid:\n ✗ Truncated URL (missing ?OSSAccessKeyId=...&Signature=...) → 403 Forbidden\n ✗ Markdown wrapped [text](url) → URL breaks on some platforms\n\nStep 8. Handle failure.\n\n 8a. Read failureReason, nextActionHint, and recentMessages from the JSON.\n 8b. If failureReason is \"INSUFFICIENT_CREDITS\":\n Tell the user prominently that production stopped because the account\n has insufficient credits.\n Go to Credit Error Handling below. Do not offer or attempt a retry\n until the user confirms that credits have been added.\n Otherwise, if stderr from the failed command contains \"Credits balance\",\n \"credits\", or \"Insufficient credits\":\n Go to Credit Error Handling below.\n Otherwise, send the user a message (in their language) with:\n - What went wrong (explain nextActionHint in simple terms)\n - Project page: https://pexo.ai/project/{project_id}\n - Offer to retry.\n\nStep 9. Timeout.\n\n If you have been in the Step 5 loop for more than 30 minutes\n and nextAction is still \"WAIT\":\n\n Send the user a message (in their language) with:\n - The video is taking longer than expected.\n - Project page: https://pexo.ai/project/{project_id}\n - Help guide: https://pexo.ai/connect/openclaw\n - Ask whether to keep waiting or start over.\n Stop polling. Wait for user instructions.\n```\n\n### Credit Error Handling\n\nUse this flow when `pexo-project-get.sh` returns\n`failureReason: \"INSUFFICIENT_CREDITS\"`, or when a command fails and stderr\ncontains credit-related information (look for: \"Credits balance\", \"credits\",\nor \"Insufficient credits\"):\n\n```\nStep A. If stderr contains a purchase link and instructions, send them\n to the user (in their language).\n\nStep B. If stderr only contains the error message without a purchase link,\n send the user a message (in their language) with:\n - Their credits are insufficient.\n - To add credits: visit https://pexo.ai/home?billing=credits\n and complete the purchase flow.\n\nStep C. After the user confirms they have added credits, retry the failed step.\n```\n\n### Revising an Existing Video\n\n```\nStep 1. Use the same project_id.\nStep 2. Run: pexo-chat.sh \"{user's exact feedback}\"\nStep 3. Go to Step 5 of the main workflow (start polling).\n```\n\n---\n\n## Asset Upload\n\nPexo can process a public `https://` webpage URL when it is included verbatim in the user's\nbrief. Pass that webpage URL to Pexo; do not scrape or download the page locally.\n\nFor a direct image, video, or audio file URL, ask for explicit approval before downloading it,\nthen upload the downloaded file. Only fetch public `https://` URLs. Never fetch `http://`,\nlocalhost, loopback, link-local, private-network, credential-bearing, or signed/private URLs;\nask the user to upload those files directly instead.\n\nUpload and reference workflow:\n```bash\n# Upload the file\nasset_id=$(pexo-upload.sh photo.jpg)\n\n# Reference the asset in your message to Pexo\npexo-chat.sh \"Here is the product photo ${asset_id}, please use it as reference\"\n```\n\nTag formats:\n```\nasset-id\nasset-id\nasset-id\n```\n\nTags are mandatory. Bare asset IDs in pexo-chat.sh messages are ignored by Pexo.\n\n---\n\n## Important Rules\n\n### Polling\n- During WAIT: only call pexo-project-get.sh. Calling pexo-chat.sh during WAIT triggers duplicate video production.\n- Wait at least 60 seconds between each pexo-project-get.sh call.\n- Process every event in recentMessages, not just the first one.\n\n### Credit Confirmation\n- Treat `nextAction=CONFIRM` as a user decision point, not as WAIT or RESPOND.\n- Only run `pexo-billing-confirm.sh` after the user explicitly approves the displayed estimate;\n pass `--user-approved` to record that prior approval. The script refuses to contact Pexo\n without this flag and emits a visible approval event.\n- Use the `confirmation_id` returned by `pexo-project-get.sh`; confirmation IDs apply only to the current pending batch.\n- A revised message sent with `pexo-chat.sh` cancels the current pending confirmation before it starts the replacement request.\n\n### Delivery\n- Copy the \"url\" field from pexo-asset-get.sh output. Send it as plain text with all query parameters.\n- Treat the script's `withWatermark` field as the authoritative selected variant.\n- Do not claim a clean download if the request failed or `withWatermark` is not false.\n- Show the downloaded video file to the user when possible.\n\n### Projects\n- New video → pexo-project-create.sh to create a new project.\n- Revisions → reuse the existing project_id.\n\n### Cost\n- Each message to Pexo costs tokens. Consolidate information into one message when possible.\n- For `nextAction=FAILED`, use `failureReason` for remediation. Do not infer a failure category from `nextActionHint` text.\n\n---\n\n## Script Reference\n\n| Script | Usage | Returns |\n|---|---|---|\n| `pexo-project-create.sh` | `[project_name]` or `--name ` | `project_id` string. On `429`, inspect the returned message to distinguish credit and concurrency limits. |\n| `pexo-project-list.sh` | `[page_size]` or `--page --page-size ` | Projects JSON |\n| `pexo-project-get.sh` | ` [--full-history]` | JSON with `nextAction`, `nextActionHint`, `recentMessages`; `CONFIRM` includes `confirmation`; recognized `FAILED` states include `failureReason`, and error events retain `errorCode`, `errorMessage`, and `toolCallId` |\n| `pexo-upload.sh` | ` ` | `asset_id` string |\n| `pexo-chat.sh` | ` [--choice ] [--billing-confirmation-mode ] [--timeout ]` | Acknowledgement JSON (async). A new message cancels a pending confirmation. On `429`/`412` or credit errors, error info printed to stderr. |\n| `pexo-billing-confirm.sh` | ` --user-approved [--timeout ]` | Approves the current sufficient credit confirmation after explicit user approval; refuses to make a request without the approval flag. |\n| `pexo-asset-get.sh` | ` [--with-watermark]` | JSON with video details, selected `url`, `localPath`, and `withWatermark` |\n| `pexo-doctor.sh` | (no args) | Diagnostic report |\n\n---\n\n## Pexo Capabilities\n\n- Output: 5–120 second finished videos with music, subtitles, and transitions\n- Aspect ratios: 16:9 (landscape), 9:16 (portrait/vertical for TikTok, Reels, Shorts), 1:1 (square)\n- Auto model selection: Seedance 2, Kling 3.0, HappyHorse, and more — Pexo picks the best model per shot\n- Input types: text, images, URLs, scripts, audio\n- Production time: ~8 minutes for a 15-second 3-shot video, ~20 minutes for a 60-second brand video\n- Supported uploads: Images (jpg, png, webp, bmp, tiff, heic), Videos (mp4, mov, avi), Audio (mp3, wav, aac, m4a, ogg, flac)\n- Post-production: AI music, TTS narration, voice cloning, lip sync, subtitles, transitions\n\n---\n\n## References\n\nLoad these when needed:\n\n- **First time or config error** → read `references/SETUP-CHECKLIST.md`\n- **Error codes or failures** → read `references/TROUBLESHOOTING.md`\n\nFile v0.3.16:_meta.json\n\n{\n \"ownerId\": \"kn7cyy6q5gnqcc174487e2pd4n828hay\",\n \"slug\": \"pexo-video-agent\",\n \"version\": \"0.3.16\",\n \"publishedAt\": 1787212027704\n}\n\nFile v0.3.16:references/SETUP-CHECKLIST.md\n\n# Setup Checklist\n\nThis guide covers first-time setup and environment diagnostics for the Pexo agent skill.\n\nRun bundled scripts through Bash from the skill directory, for example\n`bash scripts/pexo-doctor.sh`; installed files may not retain executable bits.\n\n## Quick Start\n\n### 1. Create config file\n\n```bash\numask 077\nmkdir -p ~/.pexo\nread -rsp \"Pexo API key: \" pexo_api_key\nprintf '\\n'\n{\n printf '%s=%s\\n' PEXO_API_KEY \"$pexo_api_key\"\n} > ~/.pexo/config\nunset pexo_api_key\nchmod 600 ~/.pexo/config\n```\n\nGet your API key at: https://pexo.ai\n\n- If you do not have an account:\n Go to https://pexo.ai and sign up. During registration, you will be asked for an invite code.\n Use invite code: **BV5N38**\n New users receive bonus credits upon registration — enough to try out video generation right away.\n- If you are already logged in:\n click the top-right avatar → `API Keys` → `Create Key`, then copy the new key.\n\n### 2. Run diagnostics\n\nThe next command makes outbound HTTPS requests only to `https://pexo.ai`. It performs\nan unauthenticated connectivity check and, when an API key is configured, an authenticated\nproject-list request to validate access. Pexo may log these requests; they do not start a\ngeneration or consume generation credits. Run it only after the user approves this check.\n\n```bash\nbash scripts/pexo-doctor.sh\n```\n\nThis checks:\n- Config file exists and is readable\n- `PEXO_BASE_URL` and `PEXO_API_KEY` are set\n- `curl`, `jq`, and `file` are installed\n- Network connectivity to Pexo servers\n- API key is valid (attempts to list projects)\n\nFix any issues reported before using other scripts.\n\n### 3. Verify\n\nThe next command sends an authenticated project-list request to `https://pexo.ai` and may\nappear in Pexo service logs. It does not create a project or consume generation credits.\n\n```bash\nbash scripts/pexo-project-list.sh\n```\n\nIf this returns a JSON list (even if empty), setup is complete.\n\n## Troubleshooting Setup Issues\n\n### \"PEXO_BASE_URL must be exactly https://pexo.ai\"\n\nAuthenticated requests are restricted to the production Pexo origin. Remove any custom base\nURL override, or set it to exactly `https://pexo.ai`.\n\n### \"Set PEXO_API_KEY in ~/.pexo/config or env\"\n\nSame as above — the API key line is missing from the config file.\n\n### API key invalid (401 Unauthenticated)\n\nYour API key may be expired or incorrect. Log in at https://pexo.ai to generate a new one. Replace the value in `~/.pexo/config`.\n\n### curl, jq, or file not found\n\nInstall the missing dependency:\n\n```bash\n# macOS (file is usually preinstalled)\nbrew install curl jq\n\n# Ubuntu/Debian\napt-get install -y curl jq file\n\n# CentOS/RHEL\nyum install -y curl jq file\n```\n\n### Network connectivity failure\n\nIf `pexo-doctor.sh` reports a connectivity issue:\n- Check if your server can reach `pexo.ai` (e.g. `curl -I https://pexo.ai`)\n- Check firewall rules for outbound HTTPS (port 443)\n- If behind a proxy, configure `http_proxy`/`https_proxy` environment variables\n\n## Environment Variables\n\nAll scripts read `~/.pexo/config` automatically. You can also override via environment variables:\n\nOnly `PEXO_*` assignments are accepted in the config file; it is parsed as data\nand is never executed as shell code. Explicit environment variables take\nprecedence over values in the config file.\n\n| Variable | Description | Required |\n|---|---|---|\n| `PEXO_BASE_URL` | Optional compatibility override; if set, must be exactly `https://pexo.ai` | No |\n| `PEXO_API_KEY` | Your Pexo API key (starts with `sk-`) | Yes |\n| `PEXO_CONFIG` | Custom path to config file (default: `~/.pexo/config`) | No |\n| `PEXO_BILLING_CONFIRMATION_MODE` | Credit confirmation mode: `always` or `threshold` (default: `always`; use `threshold` only after explicit user opt-in) | No |\n\nFile v0.3.16:references/TROUBLESHOOTING.md\n\n# Troubleshooting\n\n## Script Exit Behavior\n\n- Exit `0`: success\n- Exit `1`: request/transport/backend failure\n- Exit `2`: local usage error (missing args, invalid flags, invalid local input)\n\nOn request failure, scripts print compact JSON to `stderr`, for example:\n\n```json\n{\"ok\":false,\"httpCode\":429,\"message\":\"Daily creation limit reached. Contact support email for more access.\"}\n```\n\nFields you may see:\n\n- `httpCode`: the real HTTP status code returned to the script\n- `error`: auth/proxy error code such as `INVALID_API_KEY` or `INTERNAL_ERROR`\n- `message`: the most useful user-facing message extracted from the response\n- `details`: extra backend detail when available\n\n## Auth And Proxy Errors\n\nThese can happen on every script that makes API calls:\n\n| HTTP | `error` | Meaning | What to do |\n|---|---|---|---|\n| 401 | `INVALID_API_KEY` | API key is invalid or revoked | Update `PEXO_API_KEY` in `~/.pexo/config`. Get a new key at pexo.ai. |\n| 401 | `MISSING_TOKEN` | The request was sent without an API key | Run `pexo-doctor.sh` to verify config. Make sure `~/.pexo/config` is sourced correctly. |\n| 401 | `INTERNAL_ERROR` | The service failed to process the request before authentication completed | This is a temporary service issue, not a problem with the API key. Wait a moment and retry; if it persists, contact support. |\n| 409 | `SESSION_REPLACED` | This API key's session was invalidated by a new login elsewhere | Unusual for API-key usage. Retry the command. If it keeps happening, regenerate the API key at pexo.ai. |\n\nIf the message says `Invalid API key`, it is an auth problem.\nIf the body says `error=INTERNAL_ERROR`, do not tell the user to rotate the key first; the service may simply be temporarily down.\n\n## Script-Specific Errors\n\n### `pexo-project-create.sh`\n\nReal statuses:\n\n- `400`: project name is too long. Ask the user to use a shorter name and retry.\n- `401`: auth failure — see Auth and Proxy Errors above.\n- `429`: creation limit reached — could be any of:\n - User already has an active project running (must wait for it to finish)\n - Insufficient credits to start a new project\n Read the error `message` to distinguish these cases. The script does not query the balance automatically.\n- `500`: an unexpected server error occurred. Retry in a moment; if the problem persists, contact support at pexo.ai.\n\nNotes:\n\n- If no project name is provided, the script defaults to `\"Untitled\"`.\n\n### `pexo-project-list.sh`\n\nReal statuses:\n\n- `401`: auth failure — see Auth and Proxy Errors above.\n- `500`: an unexpected server error occurred. Retry in a moment; if the problem persists, contact support at pexo.ai.\n\nNotes:\n\n- Invalid `page` / `page_size` values are handled locally by the script before request time.\n- Backend page size is effectively capped at `100`.\n\n### `pexo-project-get.sh`\n\nReal statuses from the first project fetch:\n\n- `401`: auth failure — see Auth and Proxy Errors above.\n- `404`: the project does not exist or has been deleted. Verify the project_id; if correct, start a new project.\n- `500`: an unexpected server error occurred. Retry in a moment; if the problem persists, contact support at pexo.ai.\n\nSubsequent status fetches can also fail with:\n\n- `401`: auth failure — see Auth and Proxy Errors above.\n- `404`: project not found. Same action as above.\n- `500`: an unexpected server error occurred. Retry in a moment; if the problem persists, contact support at pexo.ai.\n\n`nextAction=CONFIRM` is a successful status response. The output includes a `confirmation` object for the current pending batch. Use its `confirmation_id` only after obtaining explicit user approval.\n\n`nextAction=FAILED` can include `failureReason=INSUFFICIENT_CREDITS`. In that case, `recentMessages` retains the terminal error with `errorCode=credits.insufficient_credits_err`. This polling result is the authoritative way to detect an insufficient-credit failure that occurs after `pexo-chat.sh` has acknowledged an asynchronous submission.\n\n### `pexo-upload.sh`\n\nThis script has three phases, and the failure source matters.\n\n#### Phase 1: upload credential\n\nReal statuses:\n\n- `400`: the file name or file size is invalid. Check that the file exists and is not empty; rename it if it contains special characters.\n- `401`: auth failure — see Auth and Proxy Errors above.\n- `500`: an unexpected server error occurred. Retry in a moment; if the problem persists, contact support at pexo.ai.\n\nNotes:\n\n- The script rejects unsupported extensions locally. Supported formats:\n - Images: `jpg`, `jpeg`, `png`, `webp`, `bmp`, `tiff`, `heic`, `heif`\n - Videos: `mp4`, `mov`, `avi`\n - Audio: `mp3`, `wav`, `aac`, `m4a`, `ogg`, `flac`\n\n#### Phase 2: file transfer\n\nPossible failures:\n\n- `4xx/5xx`: the file storage service rejected the upload. Check network connectivity and retry. If the problem persists, contact support at pexo.ai.\n\nThe script surfaces this directly as:\n\n```text\nError: upload failed with HTTP \n```\n\n#### Phase 3: finalize\n\nReal statuses:\n\n- `400`: the file was rejected — possible reasons: file exceeds the size limit, file format is not supported, or the file content does not match its extension. Convert or compress the file and re-upload from scratch using `pexo-upload.sh`.\n- `401`: auth failure — see Auth and Proxy Errors above.\n- `404`: the file record was not found. The upload session may have been cleaned up. Re-upload from scratch using `pexo-upload.sh`.\n- `412`: the upload session has already expired or been completed. Re-upload from scratch using `pexo-upload.sh`.\n- `500`: an unexpected server error occurred. Retry in a moment; if the problem persists, contact support at pexo.ai.\n\n### `pexo-chat.sh`\n\nReal statuses:\n\n- `400`: the message could not be sent due to invalid content. Check the message text; if the issue persists, start a new project.\n- `401`: auth failure — see Auth and Proxy Errors above.\n- `404`: the project does not exist or has been deleted. Start a new project.\n- `412`: two possible causes:\n - **Project no longer supported**: this project was created with an older version of Pexo's production system and cannot be continued. Start a new project.\n - **Account billing issue**: the account's credits are frozen or suspended. Read the response `message`, then direct the user to top up or contact support at pexo.ai.\n- `429`: limit reached — could be insufficient credits or the project's video output limit. Read the response `message` to distinguish the cause.\n- `500`: an unexpected server error occurred. Retry in a moment; if the problem persists, contact support at pexo.ai.\n\nNotes:\n\n- `pexo-chat.sh` is asynchronous. Success means the request was accepted, not that the video is done.\n- The script stops reading the SSE stream after `: stream opened`. A business error emitted later in that stream is not returned by `pexo-chat.sh`.\n- Synchronous HTTP failures are printed as compact JSON to `stderr`. Use the HTTP status and response `message` to classify them.\n- A successful `pexo-chat.sh` call should be followed by `pexo-project-get.sh` polling, typically every `60` seconds.\n- If the asynchronous run later fails for insufficient credits, `pexo-project-get.sh` returns `nextAction=FAILED`, `failureReason=INSUFFICIENT_CREDITS`, and the matching error in `recentMessages`.\n- When a project is waiting for credit approval, sending a new message through `pexo-chat.sh` cancels that pending confirmation and submits the replacement message.\n\n### `pexo-billing-confirm.sh`\n\nThis command approves a pending billable batch. It must only be called after explicit user approval\nand requires the `--user-approved` flag. Without that flag it exits before making a network request.\n\nLocal validation failures:\n\n- The project is not in `CONFIRM_REQUIRED`: fetch the project again and follow its current `nextAction`.\n- The supplied `confirmation_id` does not match the latest confirmation: use the current `confirmation.confirmation_id` returned by `pexo-project-get.sh`.\n- The confirmation event is temporarily unavailable in history: poll again shortly; the event may still be persisting.\n- `sufficient` is `false`: the available balance cannot cover the batch. Direct the user to purchase credits and do not submit approval.\n- The confirmation mode is missing or invalid: fetch the current confirmation again; do not construct an approval request manually.\n\n### `pexo-asset-get.sh`\n\nReal statuses:\n\n- `401`: auth failure — see Auth and Proxy Errors above.\n- `403`: the account is not subscribed or watermark-whitelisted, or object storage denied access.\n- `404`: the file does not exist, or it belongs to a different project. Verify the asset_id and project_id.\n- `412`: the requested asset derivative is still processing. Retry after a short delay.\n- `500`: an unexpected server error occurred. Retry in a moment; if the problem persists, contact support at pexo.ai.\n\nSecondary download failures after metadata fetch:\n\n- `403`: the download link has expired. Re-run `pexo-asset-get.sh` to get a fresh link.\n- `000`: network request failed before receiving a response. Check network connectivity and retry.\n- local filesystem write failure: the temp directory (`~/.pexo/tmp/`) is not writable or the disk is full. Free up space or set `PEXO_TMP_DIR` to a writable path.\n\nNotes:\n\n- The script downloads without a watermark by default. Pass `--with-watermark` only when the user explicitly requests it.\n- The script downloads the file into `~/.pexo/tmp/` (or `$PEXO_TMP_DIR`) and returns `url`, `localPath`, and `withWatermark`.\n- If the asset is still uploading or has no ready download URL, the script returns `localPath: null`.\n\n### `pexo-doctor.sh`\n\n- `200`: config and API key look healthy\n- `401` + `INVALID_API_KEY`: API key is invalid or revoked. Update `PEXO_API_KEY` in `~/.pexo/config`.\n- `401` + `INTERNAL_ERROR`: the service failed temporarily — not a key problem. Wait and retry.\n- `409`: session conflict, unusual for API-key usage. Retry the command.\n- `000`: no response received — network is unreachable or DNS failed. Check connectivity.\n\n## Common Scenarios\n\n### Synchronous `429` or `412` from project creation or chat submission\n\nThese scripts print the HTTP failure as compact JSON to `stderr`. They do not query or append the current credit balance. Read both `httpCode` and `message` before choosing an action because these statuses also represent non-credit limits and compatibility failures.\n\nIf the response identifies insufficient or suspended credits:\n\n1. Explain the credit restriction to the user.\n2. Direct them to `https://pexo.ai/home?billing=credits` and have them complete the purchase flow.\n3. Do not retry until the user confirms that credits have been added or the suspension has been resolved.\n\nFor a concurrent-project limit, video output limit, or incompatible project, follow the response `message` instead of using the credit remediation.\n\n### `pexo-chat.sh` returns success immediately\n\nThis is expected.\n\nThe script only confirms that the request was accepted by the server, then exits.\nIt does not stream progress or final results to the terminal.\nIt also does not return business errors emitted after the SSE acknowledgement.\n\nNext step:\n\n1. Wait `60` seconds.\n2. Run `pexo-project-get.sh `.\n3. Follow `nextAction`.\n\n### `nextAction=FAILED` with `failureReason=INSUFFICIENT_CREDITS`\n\nMeaning:\n\n- Production started but stopped when a billable operation found that the account did not have enough credits.\n- The matching error details are retained in `recentMessages` with `event: \"error\"`.\n\nAction:\n\n1. Tell the user prominently that production stopped because the account has insufficient credits.\n2. Direct them to top up credits at `https://pexo.ai/home?billing=credits`.\n3. Do not retry until the user confirms that credits have been added.\n4. Use `recentMessages[].errorMessage` for additional detail when needed; use `failureReason`, not free-form hint text, to select this remediation.\n\n### `nextAction=CONFIRM`\n\nThe project is waiting for a decision on a billable generation batch.\n\n1. Read `confirmation.estimated_credits`, `confirmation.available_credits`, and `confirmation.sufficient`.\n2. If `sufficient` is `true`, explain the estimate and ask the user for explicit approval.\n3. After approval, run `pexo-billing-confirm.sh --user-approved`, then resume polling.\n4. If `sufficient` is `false`, direct the user to purchase credits. Do not submit approval.\n5. If the user changes the request, send the revised message with `pexo-chat.sh`; this cancels the pending confirmation.\n\n### `WAIT` lasts a long time\n\nThis is normal for video generation.\n\nPractical guideline:\n\n1. Keep polling every `60` seconds.\n2. Do not send another `pexo-chat.sh` message while `nextAction=WAIT`.\n3. If the project later becomes `RECONNECT`, send a short continuation message and resume polling.\n\n### `RECONNECT` keeps appearing\n\nMeaning:\n\n- The connection to the video generation service was interrupted.\n\nAction:\n\n1. Send a short message with `pexo-chat.sh`, for example `continue`.\n2. Resume polling with `pexo-project-get.sh`.\n3. If this repeats multiple times, start a new project instead of looping forever.\n\n### Download URL expired or returns `403`\n\nSigned URLs are temporary.\n\nAction:\n\n1. Re-run `pexo-asset-get.sh `.\n2. The script will fetch a fresh download URL for the default clean variant and re-download the file into `~/.pexo/tmp/`.\n3. Deliver the fresh `downloadUrl` and report the `withWatermark` value.\n\n### Upload fails locally with “unsupported file type”\n\nThis is a local pre-check, not a backend outage.\n\nAction:\n\n1. Convert the file into one of the supported formats listed above.\n2. Retry `pexo-upload.sh`.\n\n### A script says `401`, but the API key may still be fine\n\nInspect the error payload:\n\n- `error=INVALID_API_KEY`: fix the key\n- `error=INTERNAL_ERROR`: treat it as a temporary service issue, not a key problem\n\nFile v0.3.16:skill-card.md\n\n## Description:\n\nPexo Video Agent helps agents create finished multi-shot AI videos from text, images, URLs, scripts, or audio through Pexo's external video generation service.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[pexo](https://clawhub.ai/user/pexo)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nExternal users and developers use this skill to submit approved briefs and media assets to Pexo, manage video-generation projects, confirm billable batches, and retrieve generated video outputs.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: Selected media files, briefs, related metadata, and generated asset links are handled by Pexo's external service.\n\nMitigation: Use the skill only with files the user intentionally selects, avoid secrets or regulated data, and obtain explicit consent before transmitting briefs or assets.\n\nRisk: Remote service messages, billing links, and signed asset URLs may be relayed back to the user.\n\nMitigation: Treat returned content as external Pexo-provided content, review links before acting on them, and avoid treating service responses as trusted local instructions.\n\nRisk: The skill requires a PEXO_API_KEY and outbound HTTPS access.\n\nMitigation: Keep the API key scoped and removable, store it with restricted file permissions, and review before installation on networks with sensitive internal services.\n\n## Reference(s):\n\n- [ClawHub Skill Page](https://clawhub.ai/pexo/skills/pexo-video-agent)\n- [Setup Checklist](references/SETUP-CHECKLIST.md)\n- [Troubleshooting](references/TROUBLESHOOTING.md)\n- [Pexo OpenClaw Guide](https://pexo.ai/connect/openclaw)\n\n## Skill Output:\n\n**Output Type(s):** [Text, Markdown, Shell commands, Configuration, Guidance]\n\n**Output Format:** [Markdown and plain text with inline shell commands and external video links]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [May retrieve generated video files and signed asset URLs from Pexo when the user has approved the request.]\n\n## Skill Version(s):\n\n0.3.16 (source: server release metadata and skill frontmatter)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.\n\nFile v0.3.16:agents/openai.yaml\n\ninterface:\n display_name: \"Pexo Video Agent\"\n short_description: \"Create finished multi-shot AI videos\"\n default_prompt: \"Use $pexo-agent only when I explicitly ask to produce a video; confirm before sending my brief or selected assets to Pexo.\"\n\nArchive v0.1.4: 15 files, 35317 bytes\n\nFiles: agents/openai.yaml (255b), references/SETUP-CHECKLIST.md (3766b), references/TROUBLESHOOTING.md (13589b), scripts/_common.sh (13616b), scripts/pexo-asset-get.sh (2403b), scripts/pexo-billing-confirm.sh (3486b), scripts/pexo-chat.sh (5530b), scripts/pexo-doctor.sh (6278b), scripts/pexo-project-create.sh (1679b), scripts/pexo-project-get.sh (11771b), scripts/pexo-project-list.sh (1693b), scripts/pexo-upload.sh (3209b), skill-card.md (2788b), SKILL.md (19549b), _meta.json (135b)\n\nFile v0.1.4:SKILL.md\n\n---\nname: pexo-video-agent\ndescription: >\n AI video generation skill with auto model selection across Seedance 2,\n Kling 3.0, HappyHorse, and 10+ models. Produces finished multi-shot videos\n (5–120s) from text, images, URLs, scripts, or audio — including AI music,\n lip sync, and multi-shot sequencing. Calls Pexo's external API, manages\n project status and billing confirmations, and transfers only user-approved\n briefs and assets. Runs setup diagnostics, stores generated downloads locally,\n and requires shell, outbound HTTPS, and local file access. Authenticated\n requests are locked to https://pexo.ai. No prompts to write, no models to choose.\n USE FOR: video production, AI video, make a video, product video,\n brand video, promotional clip, explainer video, short video,\n TikTok video, Instagram Reel, YouTube Short, product ad,\n text-to-video, image-to-video, video generation, AI video agent.\nlicense: MIT-0\nmetadata:\n author: pexoai\n version: \"0.1.4\"\n openclaw:\n requires:\n env:\n - PEXO_API_KEY\n bins:\n - bash\n - curl\n - jq\n - file\n primaryEnv: PEXO_API_KEY\n---\n\n# Pexo Video Agent — AI Video Generation Skill\n\nPexo is the most complete video generation skill for Claude Code and other AI coding agents. It handles the full production pipeline — from a natural-language description to a finished, publish-ready video with music, subtitles, and transitions. Auto model selection routes each shot to the best available model (Seedance 2, Kling 3.0, HappyHorse, and more). One API key, no prompt engineering, no video editing.\n\n## What Pexo Does\n\n- **Auto model selection** — Pexo picks the best video model for each shot based on content type. You do not need to know which model to use.\n- **Full pipeline** — Script, storyboard, shot-by-shot generation, music, subtitles, lip sync, and final assembly. The output is a finished video, not a raw clip.\n- **5 input types** — Text-to-video, image-to-video, URL-to-video (scrapes the page), script-to-video, and audio-to-video.\n- **10+ models** — Seedance 2, Kling 3.0, HappyHorse, and more. New models are added as they launch.\n- **Any format** — 5–120 seconds, aspect ratios 16:9 (landscape), 9:16 (portrait/vertical), 1:1 (square).\n\n## What You Can Build With Pexo\n\n- Product video ads from a product photo or URL\n- TikTok, Instagram Reels, and YouTube Shorts from a text description\n- Multi-shot brand videos with consistent style and transitions\n- Explainer videos with TTS narration from a script\n- E-commerce video content at scale from product catalogs\n- Marketing video variants for A/B testing\n\n## How It Works\n\nYou send the user's request to Pexo, and Pexo handles all creative work — scriptwriting, shot composition, model selection, prompt engineering, transitions, music. Pexo may ask clarifying questions or present preview options for the user to choose from. A typical 15-second, 3-shot product ad renders in under 8 minutes.\n\n## Data, Permissions, and Cost\n\n- This Skill runs bundled shell scripts, reads only files the user explicitly selects,\n connects only to `https://pexo.ai` for authenticated API calls, uploads approved\n briefs and assets, manages projects and billing confirmations, runs diagnostics,\n and stores generated media under `~/.pexo/tmp` or `PEXO_TMP_DIR`.\n- Before the first external transmission in a session, tell the user that their brief,\n selected files, and related metadata will be sent to Pexo and obtain explicit consent.\n- Do not upload secrets, regulated data, or unrelated local files. Never search the local\n filesystem for additional material without a separate user request.\n- Every billable generation batch requires explicit user approval by default. Report the\n available estimate from Pexo before approving a confirmation.\n\n## Script Execution\n\nResolve `SKILL_ROOT` to the directory containing this `SKILL.md`. Script names\nbelow are shorthand for `bash \"$SKILL_ROOT/scripts/\"`; do not rely\non executable bits or a modified `PATH`.\n\n## Prerequisites\n\nConfig file `~/.pexo/config`:\n\n```bash\numask 077\nmkdir -p ~/.pexo\nread -rsp \"Pexo API key: \" pexo_api_key\nprintf '\\n'\n{\n printf '%s=%s\\n' PEXO_API_KEY \"$pexo_api_key\"\n} > ~/.pexo/config\nunset pexo_api_key\nchmod 600 ~/.pexo/config\n```\n\nFirst time using this skill or encountering a config error → run `pexo-doctor.sh` and follow its output. See `references/SETUP-CHECKLIST.md` for details.\n\n### Credit Confirmation Preference\n\n`PEXO_BILLING_CONFIRMATION_MODE` controls the confirmation behavior for each message sent by this Skill. It is optional; the default is `always`.\n\n- `always`: ask for approval before every billable generation batch.\n- `threshold`: ask when the estimated batch cost exceeds the platform threshold, or when the available balance is insufficient. Use only after the user explicitly opts in for the current session.\n\nUse `pexo-chat.sh --billing-confirmation-mode ` to override the default for one message.\n\n---\n\n## ⚠️ LANGUAGE RULE (highest priority)\n\n**You MUST reply to the user in the SAME language they use. This is non-negotiable.**\n\n- User writes in English → you reply in English\n- User writes in Chinese → you reply in Chinese\n- User writes in Japanese → you reply in Japanese\n\nThis applies to every message you send. If the user switches language mid-conversation, you switch too.\n\n---\n\n## Your Role: Delivery Worker\n\nYou are a delivery worker between the user and Pexo. You do three things:\n\n1. **Upload**: user gives a file → `pexo-upload.sh` → get asset ID\n2. **Relay**: copy the user's words into `pexo-chat.sh`\n3. **Deliver**: poll for results → send video and link to user\n\nPexo's backend is a professional video creation agent. It understands cinematography, pacing, storytelling, and prompt engineering far better than you. When you add your own creative ideas, the video quality goes down.\n\n### How to relay messages — copy-paste template\n\nWhen calling pexo-chat.sh, copy the user's message exactly:\n\n```\npexo-chat.sh \"{user's message, copied exactly}\"\n```\n\nExample — user said \"做个猫的视频\":\n```\npexo-chat.sh proj_123 \"做个猫的视频\"\n```\n\nExample — user said \"I want a product video for my shoes\" and uploaded shoes.jpg:\n```\nasset_id=$(pexo-upload.sh proj_123 shoes.jpg)\npexo-chat.sh proj_123 \"I want a product video for my shoes ${asset_id}\"\n```\n\nYour only addition to the user's message is asset tags for uploaded files. Everything else stays exactly as the user wrote it.\n\n### When the user's request is vague\n\nPass it to Pexo exactly as-is. Pexo will ask the user for any missing details. Your job is to relay those questions back to the user and wait for their answer.\n\n### Why this matters\n\nPexo's backend agent specializes in video production. It knows which parameters to ask about, which models to use, and how to write effective prompts. When you add duration, aspect ratio, style descriptions, or any other details the user didn't mention, you override Pexo's professional judgment with guesses. This produces worse videos.\n\n---\n\n## First-Time Setup Message\n\nAfter Pexo is configured for the first time, send the user this message (in the user's language):\n\n> ✅ Pexo is ready!\n> 📖 Guide: https://pexo.ai/connect/openclaw\n> Tell me what video you'd like to make.\n\n---\n\n## Step-by-Step Workflow\n\nFollow these steps in order.\n\n### Making a New Video\n\n```\nStep 1. Create project.\n Run: pexo-project-create.sh \"brief description\"\n If the command succeeds: save the returned project_id.\n If the command fails and stderr contains \"Credits balance\"\n or \"credits\" or \"Insufficient credits\":\n → Go to Credit Error Handling below.\n If the command fails for other reasons:\n → Tell the user what went wrong and offer to retry.\n\nStep 2. Upload files (if user provided any images/videos/audio).\n Run: pexo-upload.sh \n Save the returned asset_id.\n Wrap in tag: asset_id\n (or / for other file types)\n\nStep 3. Send user's message to Pexo.\n Run: pexo-chat.sh \"{user's exact words} asset_id\"\n Copy the user's words exactly. Only add asset tags for uploaded files.\n If the command fails and stderr contains \"Credits balance\"\n or \"credits\" or \"Insufficient credits\":\n → Go to Credit Error Handling below.\n If the command fails for other reasons:\n → Tell the user what went wrong and offer to retry.\n\nStep 4. Notify the user (in the user's language).\n Your message must contain these three items:\n - Confirmation that the request is submitted to Pexo\n - Estimated time: 15–20 minutes for a short video\n - Project link: https://pexo.ai/project/{project_id}\n\nStep 5. Poll for status.\n Run: sleep 60\n Run: pexo-project-get.sh \n Read the nextAction field from the returned JSON.\n Continue to Step 6.\n\nStep 6. Act on nextAction:\n\n \"WAIT\" →\n Go back to Step 5. Keep repeating.\n Every 5 polls (~5 minutes), send user a brief update with\n the project link: https://pexo.ai/project/{project_id}\n\n \"CONFIRM\" →\n Read the confirmation object. It contains confirmation_id, estimated_credits,\n available_credits, sufficient, and the pending tool batch.\n\n If sufficient is false:\n Tell the user that the available credits cannot cover this request.\n Go to Credit Error Handling below. Do not run pexo-billing-confirm.sh.\n\n If sufficient is true:\n Tell the user the estimated credit cost and ask for explicit approval.\n Do not approve on the user's behalf.\n\n After explicit approval:\n Run: pexo-billing-confirm.sh --user-approved\n Go back to Step 5.\n\n If the user changes the request instead:\n Run: pexo-chat.sh \"{user's exact revised request}\"\n This cancels the pending confirmation before submitting the new message.\n Go back to Step 5.\n\n \"RESPOND\" →\n Read the recentMessages array. Handle every event:\n\n Event \"message\" (Pexo sent text):\n Relay Pexo's text to the user in full.\n If Pexo asked a question, wait for the user's answer.\n Then run: pexo-chat.sh \"{user's exact answer}\"\n Go back to Step 5.\n\n Event \"preview_video\" (Pexo sent preview options):\n For each assetId in assetIds:\n Run: pexo-asset-get.sh \n Copy the \"url\" field from the returned JSON.\n Show all preview URLs to the user with labels (A, B, C...).\n Ask the user to pick one.\n After user picks:\n Run: pexo-chat.sh \"{user's choice}\" --choice \n Go back to Step 5.\n\n Event \"document\":\n Mention the document to the user.\n\n Event \"attachment\":\n Fetch each assetId with pexo-asset-get.sh and deliver the resulting file or URL.\n\n \"DELIVER\" →\n Go to Step 7.\n\n \"FAILED\" →\n Go to Step 8.\n\n \"RECONNECT\" →\n Run: pexo-chat.sh \"continue\"\n Tell the user the connection was interrupted and you are reconnecting.\n Go back to Step 5.\n\nStep 7. Deliver the final video.\n\n 7a. Relay any message events in recentMessages, then find the final_video\n event and get its assetId.\n\n 7b. Run: pexo-asset-get.sh \n\n 7c. Show the downloaded video file to the user.\n\n 7d. Also send the user a message (in their language) with:\n - The video download URL (copy the \"url\" field from the JSON output).\n Send the FULL URL as plain text, including all query parameters.\n Example:\n https://pexo-assets.oss-us-east-1.aliyuncs.com/projects%2F123%2Fassets%2Fvideo.mp4?OSSAccessKeyId=xxx&Expires=xxx&Signature=xxx\n - Project page: https://pexo.ai/project/{project_id}\n - Ask if satisfied or want revisions.\n\n Common delivery mistakes to avoid:\n ✗ Truncated URL (missing ?OSSAccessKeyId=...&Signature=...) → 403 Forbidden\n ✗ Markdown wrapped [text](url) → URL breaks on some platforms\n\nStep 8. Handle failure.\n\n 8a. Read failureReason, nextActionHint, and recentMessages from the JSON.\n 8b. If failureReason is \"INSUFFICIENT_CREDITS\":\n Tell the user prominently that production stopped because the account\n has insufficient credits.\n Go to Credit Error Handling below. Do not offer or attempt a retry\n until the user confirms that credits have been added.\n Otherwise, if stderr from the failed command contains \"Credits balance\",\n \"credits\", or \"Insufficient credits\":\n Go to Credit Error Handling below.\n Otherwise, send the user a message (in their language) with:\n - What went wrong (explain nextActionHint in simple terms)\n - Project page: https://pexo.ai/project/{project_id}\n - Offer to retry.\n\nStep 9. Timeout.\n\n If you have been in the Step 5 loop for more than 30 minutes\n and nextAction is still \"WAIT\":\n\n Send the user a message (in their language) with:\n - The video is taking longer than expected.\n - Project page: https://pexo.ai/project/{project_id}\n - Help guide: https://pexo.ai/connect/openclaw\n - Ask whether to keep waiting or start over.\n Stop polling. Wait for user instructions.\n```\n\n### Credit Error Handling\n\nUse this flow when `pexo-project-get.sh` returns\n`failureReason: \"INSUFFICIENT_CREDITS\"`, or when a command fails and stderr\ncontains credit-related information (look for: \"Credits balance\", \"credits\",\nor \"Insufficient credits\"):\n\n```\nStep A. If stderr contains a purchase link and instructions, send them\n to the user (in their language).\n\nStep B. If stderr only contains the error message without a purchase link,\n send the user a message (in their language) with:\n - Their credits are insufficient.\n - To add credits: visit https://pexo.ai/home?billing=credits\n and complete the purchase flow.\n\nStep C. After the user confirms they have added credits, retry the failed step.\n```\n\n### Revising an Existing Video\n\n```\nStep 1. Use the same project_id.\nStep 2. Run: pexo-chat.sh \"{user's exact feedback}\"\nStep 3. Go to Step 5 of the main workflow (start polling).\n```\n\n---\n\n## Asset Upload\n\nPexo can process a public `https://` webpage URL when it is included verbatim in the user's\nbrief. Pass that webpage URL to Pexo; do not scrape or download the page locally.\n\nFor a direct image, video, or audio file URL, ask for explicit approval before downloading it,\nthen upload the downloaded file. Only fetch public `https://` URLs. Never fetch `http://`,\nlocalhost, loopback, link-local, private-network, credential-bearing, or signed/private URLs;\nask the user to upload those files directly instead.\n\nUpload and reference workflow:\n```bash\n# Upload the file\nasset_id=$(pexo-upload.sh photo.jpg)\n\n# Reference the asset in your message to Pexo\npexo-chat.sh \"Here is the product photo ${asset_id}, please use it as reference\"\n```\n\nTag formats:\n```\nasset-id\nasset-id\nasset-id\n```\n\nTags are mandatory. Bare asset IDs in pexo-chat.sh messages are ignored by Pexo.\n\n---\n\n## Important Rules\n\n### Polling\n- During WAIT: only call pexo-project-get.sh. Calling pexo-chat.sh during WAIT triggers duplicate video production.\n- Wait at least 60 seconds between each pexo-project-get.sh call.\n- Process every event in recentMessages, not just the first one.\n\n### Credit Confirmation\n- Treat `nextAction=CONFIRM` as a user decision point, not as WAIT or RESPOND.\n- Only run `pexo-billing-confirm.sh` after the user explicitly approves the displayed estimate;\n pass `--user-approved` to record that prior approval. The script refuses to contact Pexo\n without this flag and emits a visible approval event.\n- Use the `confirmation_id` returned by `pexo-project-get.sh`; confirmation IDs apply only to the current pending batch.\n- A revised message sent with `pexo-chat.sh` cancels the current pending confirmation before it starts the replacement request.\n\n### Delivery\n- Copy the \"url\" field from pexo-asset-get.sh output. Send it as plain text with all query parameters.\n- Show the downloaded video file to the user when possible.\n\n### Projects\n- New video → pexo-project-create.sh to create a new project.\n- Revisions → reuse the existing project_id.\n\n### Cost\n- Each message to Pexo costs tokens. Consolidate information into one message when possible.\n- For `nextAction=FAILED`, use `failureReason` for remediation. Do not infer a failure category from `nextActionHint` text.\n\n---\n\n## Script Reference\n\n| Script | Usage | Returns |\n|---|---|---|\n| `pexo-project-create.sh` | `[project_name]` or `--name ` | `project_id` string. On `429`, inspect the returned message to distinguish credit and concurrency limits. |\n| `pexo-project-list.sh` | `[page_size]` or `--page --page-size ` | Projects JSON |\n| `pexo-project-get.sh` | ` [--full-history]` | JSON with `nextAction`, `nextActionHint`, `recentMessages`; `CONFIRM` includes `confirmation`; recognized `FAILED` states include `failureReason`, and error events retain `errorCode`, `errorMessage`, and `toolCallId` |\n| `pexo-upload.sh` | ` ` | `asset_id` string |\n| `pexo-chat.sh` | ` [--choice ] [--billing-confirmation-mode ] [--timeout ]` | Acknowledgement JSON (async). A new message cancels a pending confirmation. On `429`/`412` or credit errors, error info printed to stderr. |\n| `pexo-billing-confirm.sh` | ` --user-approved [--timeout ]` | Approves the current sufficient credit confirmation after explicit user approval; refuses to make a request without the approval flag. |\n| `pexo-asset-get.sh` | ` ` | JSON with video details and `url` field |\n| `pexo-doctor.sh` | (no args) | Diagnostic report |\n\n---\n\n## Pexo Capabilities\n\n- Output: 5–120 second finished videos with music, subtitles, and transitions\n- Aspect ratios: 16:9 (landscape), 9:16 (portrait/vertical for TikTok, Reels, Shorts), 1:1 (square)\n- Auto model selection: Seedance 2, Kling 3.0, HappyHorse, and more — Pexo picks the best model per shot\n- Input types: text, images, URLs, scripts, audio\n- Production time: ~8 minutes for a 15-second 3-shot video, ~20 minutes for a 60-second brand video\n- Supported uploads: Images (jpg, png, webp, bmp, tiff, heic), Videos (mp4, mov, avi), Audio (mp3, wav, aac, m4a, ogg, flac)\n- Post-production: AI music, TTS narration, voice cloning, lip sync, subtitles, transitions\n\n---\n\n## References\n\nLoad these when needed:\n\n- **First time or config error** → read `references/SETUP-CHECKLIST.md`\n- **Error codes or failures** → read `references/TROUBLESHOOTING.md`\n\nFile v0.1.4:_meta.json\n\n{\n \"ownerId\": \"kn7cyy6q5gnqcc174487e2pd4n828hay\",\n \"slug\": \"pexo-video-agent\",\n \"version\": \"0.1.4\",\n \"publishedAt\": 1784600168702\n}\n\nFile v0.1.4:references/SETUP-CHECKLIST.md\n\n# Setup Checklist\n\nThis guide covers first-time setup and environment diagnostics for the Pexo agent skill.\n\nRun bundled scripts through Bash from the skill directory, for example\n`bash scripts/pexo-doctor.sh`; installed files may not retain executable bits.\n\n## Quick Start\n\n### 1. Create config file\n\n```bash\numask 077\nmkdir -p ~/.pexo\nread -rsp \"Pexo API key: \" pexo_api_key\nprintf '\\n'\n{\n printf '%s=%s\\n' PEXO_API_KEY \"$pexo_api_key\"\n} > ~/.pexo/config\nunset pexo_api_key\nchmod 600 ~/.pexo/config\n```\n\nGet your API key at: https://pexo.ai\n\n- If you do not have an account:\n Go to https://pexo.ai and sign up. During registration, you will be asked for an invite code.\n Use invite code: **BV5N38**\n New users receive bonus credits upon registration — enough to try out video generation right away.\n- If you are already logged in:\n click the top-right avatar → `API Keys` → `Create Key`, then copy the new key.\n\n### 2. Run diagnostics\n\nThe next command makes outbound HTTPS requests only to `https://pexo.ai`. It performs\nan unauthenticated connectivity check and, when an API key is configured, an authenticated\nproject-list request to validate access. Pexo may log these requests; they do not start a\ngeneration or consume generation credits. Run it only after the user approves this check.\n\n```bash\nbash scripts/pexo-doctor.sh\n```\n\nThis checks:\n- Config file exists and is readable\n- `PEXO_BASE_URL` and `PEXO_API_KEY` are set\n- `curl`, `jq`, and `file` are installed\n- Network connectivity to Pexo servers\n- API key is valid (attempts to list projects)\n\nFix any issues reported before using other scripts.\n\n### 3. Verify\n\nThe next command sends an authenticated project-list request to `https://pexo.ai` and may\nappear in Pexo service logs. It does not create a project or consume generation credits.\n\n```bash\nbash scripts/pexo-project-list.sh\n```\n\nIf this returns a JSON list (even if empty), setup is complete.\n\n## Troubleshooting Setup Issues\n\n### \"PEXO_BASE_URL must be exactly https://pexo.ai\"\n\nAuthenticated requests are restricted to the production Pexo origin. Remove any custom base\nURL override, or set it to exactly `https://pexo.ai`.\n\n### \"Set PEXO_API_KEY in ~/.pexo/config or env\"\n\nSame as above — the API key line is missing from the config file.\n\n### API key invalid (401 Unauthenticated)\n\nYour API key may be expired or incorrect. Log in at https://pexo.ai to generate a new one. Replace the value in `~/.pexo/config`.\n\n### curl, jq, or file not found\n\nInstall the missing dependency:\n\n```bash\n# macOS (file is usually preinstalled)\nbrew install curl jq\n\n# Ubuntu/Debian\napt-get install -y curl jq file\n\n# CentOS/RHEL\nyum install -y curl jq file\n```\n\n### Network connectivity failure\n\nIf `pexo-doctor.sh` reports a connectivity issue:\n- Check if your server can reach `pexo.ai` (e.g. `curl -I https://pexo.ai`)\n- Check firewall rules for outbound HTTPS (port 443)\n- If behind a proxy, configure `http_proxy`/`https_proxy` environment variables\n\n## Environment Variables\n\nAll scripts read `~/.pexo/config` automatically. You can also override via environment variables:\n\nOnly `PEXO_*` assignments are accepted in the config file; it is parsed as data\nand is never executed as shell code. Explicit environment variables take\nprecedence over values in the config file.\n\n| Variable | Description | Required |\n|---|---|---|\n| `PEXO_BASE_URL` | Optional compatibility override; if set, must be exactly `https://pexo.ai` | No |\n| `PEXO_API_KEY` | Your Pexo API key (starts with `sk-`) | Yes |\n| `PEXO_CONFIG` | Custom path to config file (default: `~/.pexo/config`) | No |\n| `PEXO_BILLING_CONFIRMATION_MODE` | Credit confirmation mode: `always` or `threshold` (default: `always`; use `threshold` only after explicit user opt-in) | No |\n\nFile v0.1.4:references/TROUBLESHOOTING.md\n\n# Troubleshooting\n\n## Script Exit Behavior\n\n- Exit `0`: success\n- Exit `1`: request/transport/backend failure\n- Exit `2`: local usage error (missing args, invalid flags, invalid local input)\n\nOn request failure, scripts print compact JSON to `stderr`, for example:\n\n```json\n{\"ok\":false,\"httpCode\":429,\"message\":\"Daily creation limit reached. Contact support email for more access.\"}\n```\n\nFields you may see:\n\n- `httpCode`: the real HTTP status code returned to the script\n- `error`: auth/proxy error code such as `INVALID_API_KEY` or `INTERNAL_ERROR`\n- `message`: the most useful user-facing message extracted from the response\n- `details`: extra backend detail when available\n\n## Auth And Proxy Errors\n\nThese can happen on every script that makes API calls:\n\n| HTTP | `error` | Meaning | What to do |\n|---|---|---|---|\n| 401 | `INVALID_API_KEY` | API key is invalid or revoked | Update `PEXO_API_KEY` in `~/.pexo/config`. Get a new key at pexo.ai. |\n| 401 | `MISSING_TOKEN` | The request was sent without an API key | Run `pexo-doctor.sh` to verify config. Make sure `~/.pexo/config` is sourced correctly. |\n| 401 | `INTERNAL_ERROR` | The service failed to process the request before authentication completed | This is a temporary service issue, not a problem with the API key. Wait a moment and retry; if it persists, contact support. |\n| 409 | `SESSION_REPLACED` | This API key's session was invalidated by a new login elsewhere | Unusual for API-key usage. Retry the command. If it keeps happening, regenerate the API key at pexo.ai. |\n\nIf the message says `Invalid API key`, it is an auth problem.\nIf the body says `error=INTERNAL_ERROR`, do not tell the user to rotate the key first; the service may simply be temporarily down.\n\n## Script-Specific Errors\n\n### `pexo-project-create.sh`\n\nReal statuses:\n\n- `400`: project name is too long. Ask the user to use a shorter name and retry.\n- `401`: auth failure — see Auth and Proxy Errors above.\n- `429`: creation limit reached — could be any of:\n - User already has an active project running (must wait for it to finish)\n - Insufficient credits to start a new project\n Read the error `message` to distinguish these cases. The script does not query the balance automatically.\n- `500`: an unexpected server error occurred. Retry in a moment; if the problem persists, contact support at pexo.ai.\n\nNotes:\n\n- If no project name is provided, the script defaults to `\"Untitled\"`.\n\n### `pexo-project-list.sh`\n\nReal statuses:\n\n- `401`: auth failure — see Auth and Proxy Errors above.\n- `500`: an unexpected server error occurred. Retry in a moment; if the problem persists, contact support at pexo.ai.\n\nNotes:\n\n- Invalid `page` / `page_size` values are handled locally by the script before request time.\n- Backend page size is effectively capped at `100`.\n\n### `pexo-project-get.sh`\n\nReal statuses from the first project fetch:\n\n- `401`: auth failure — see Auth and Proxy Errors above.\n- `404`: the project does not exist or has been deleted. Verify the project_id; if correct, start a new project.\n- `500`: an unexpected server error occurred. Retry in a moment; if the problem persists, contact support at pexo.ai.\n\nSubsequent status fetches can also fail with:\n\n- `401`: auth failure — see Auth and Proxy Errors above.\n- `404`: project not found. Same action as above.\n- `500`: an unexpected server error occurred. Retry in a moment; if the problem persists, contact support at pexo.ai.\n\n`nextAction=CONFIRM` is a successful status response. The output includes a `confirmation` object for the current pending batch. Use its `confirmation_id` only after obtaining explicit user approval.\n\n`nextAction=FAILED` can include `failureReason=INSUFFICIENT_CREDITS`. In that case, `recentMessages` retains the terminal error with `errorCode=credits.insufficient_credits_err`. This polling result is the authoritative way to detect an insufficient-credit failure that occurs after `pexo-chat.sh` has acknowledged an asynchronous submission.\n\n### `pexo-upload.sh`\n\nThis script has three phases, and the failure source matters.\n\n#### Phase 1: upload credential\n\nReal statuses:\n\n- `400`: the file name or file size is invalid. Check that the file exists and is not empty; rename it if it contains special characters.\n- `401`: auth failure — see Auth and Proxy Errors above.\n- `500`: an unexpected server error occurred. Retry in a moment; if the problem persists, contact support at pexo.ai.\n\nNotes:\n\n- The script rejects unsupported extensions locally. Supported formats:\n - Images: `jpg`, `jpeg`, `png`, `webp`, `bmp`, `tiff`, `heic`, `heif`\n - Videos: `mp4`, `mov`, `avi`\n - Audio: `mp3`, `wav`, `aac`, `m4a`, `ogg`, `flac`\n\n#### Phase 2: file transfer\n\nPossible failures:\n\n- `4xx/5xx`: the file storage service rejected the upload. Check network connectivity and retry. If the problem persists, contact support at pexo.ai.\n\nThe script surfaces this directly as:\n\n```text\nError: upload failed with HTTP \n```\n\n#### Phase 3: finalize\n\nReal statuses:\n\n- `400`: the file was rejected — possible reasons: file exceeds the size limit, file format is not supported, or the file content does not match its extension. Convert or compress the file and re-upload from scratch using `pexo-upload.sh`.\n- `401`: auth failure — see Auth and Proxy Errors above.\n- `404`: the file record was not found. The upload session may have been cleaned up. Re-upload from scratch using `pexo-upload.sh`.\n- `412`: the upload session has already expired or been completed. Re-upload from scratch using `pexo-upload.sh`.\n- `500`: an unexpected server error occurred. Retry in a moment; if the problem persists, contact support at pexo.ai.\n\n### `pexo-chat.sh`\n\nReal statuses:\n\n- `400`: the message could not be sent due to invalid content. Check the message text; if the issue persists, start a new project.\n- `401`: auth failure — see Auth and Proxy Errors above.\n- `404`: the project does not exist or has been deleted. Start a new project.\n- `412`: two possible causes:\n - **Project no longer supported**: this project was created with an older version of Pexo's production system and cannot be continued. Start a new project.\n - **Account billing issue**: the account's credits are frozen or suspended. Read the response `message`, then direct the user to top up or contact support at pexo.ai.\n- `429`: limit reached — could be insufficient credits or the project's video output limit. Read the response `message` to distinguish the cause.\n- `500`: an unexpected server error occurred. Retry in a moment; if the problem persists, contact support at pexo.ai.\n\nNotes:\n\n- `pexo-chat.sh` is asynchronous. Success means the request was accepted, not that the video is done.\n- The script stops reading the SSE stream after `: stream opened`. A business error emitted later in that stream is not returned by `pexo-chat.sh`.\n- Synchronous HTTP failures are printed as compact JSON to `stderr`. Use the HTTP status and response `message` to classify them.\n- A successful `pexo-chat.sh` call should be followed by `pexo-project-get.sh` polling, typically every `60` seconds.\n- If the asynchronous run later fails for insufficient credits, `pexo-project-get.sh` returns `nextAction=FAILED`, `failureReason=INSUFFICIENT_CREDITS`, and the matching error in `recentMessages`.\n- When a project is waiting for credit approval, sending a new message through `pexo-chat.sh` cancels that pending confirmation and submits the replacement message.\n\n### `pexo-billing-confirm.sh`\n\nThis command approves a pending billable batch. It must only be called after explicit user approval\nand requires the `--user-approved` flag. Without that flag it exits before making a network request.\n\nLocal validation failures:\n\n- The project is not in `CONFIRM_REQUIRED`: fetch the project again and follow its current `nextAction`.\n- The supplied `confirmation_id` does not match the latest confirmation: use the current `confirmation.confirmation_id` returned by `pexo-project-get.sh`.\n- The confirmation event is temporarily unavailable in history: poll again shortly; the event may still be persisting.\n- `sufficient` is `false`: the available balance cannot cover the batch. Direct the user to purchase credits and do not submit approval.\n- The confirmation mode is missing or invalid: fetch the current confirmation again; do not construct an approval request manually.\n\n### `pexo-asset-get.sh`\n\nReal statuses:\n\n- `401`: auth failure — see Auth and Proxy Errors above.\n- `404`: the file does not exist, or it belongs to a different project. Verify the asset_id and project_id.\n- `500`: an unexpected server error occurred. Retry in a moment; if the problem persists, contact support at pexo.ai.\n\nSecondary download failures after metadata fetch:\n\n- `403`: the download link has expired. Re-run `pexo-asset-get.sh` to get a fresh link.\n- `000`: network request failed before receiving a response. Check network connectivity and retry.\n- local filesystem write failure: the temp directory (`~/.pexo/tmp/`) is not writable or the disk is full. Free up space or set `PEXO_TMP_DIR` to a writable path.\n\nNotes:\n\n- The script downloads the file into `~/.pexo/tmp/` (or `$PEXO_TMP_DIR`) and returns both `url` and `localPath`.\n- If the asset metadata exists but `downloadUrl` is absent, the script returns `localPath: null`.\n\n### `pexo-doctor.sh`\n\n- `200`: config and API key look healthy\n- `401` + `INVALID_API_KEY`: API key is invalid or revoked. Update `PEXO_API_KEY` in `~/.pexo/config`.\n- `401` + `INTERNAL_ERROR`: the service failed temporarily — not a key problem. Wait and retry.\n- `409`: session conflict, unusual for API-key usage. Retry the command.\n- `000`: no response received — network is unreachable or DNS failed. Check connectivity.\n\n## Common Scenarios\n\n### Synchronous `429` or `412` from project creation or chat submission\n\nThese scripts print the HTTP failure as compact JSON to `stderr`. They do not query or append the current credit balance. Read both `httpCode` and `message` before choosing an action because these statuses also represent non-credit limits and compatibility failures.\n\nIf the response identifies insufficient or suspended credits:\n\n1. Explain the credit restriction to the user.\n2. Direct them to `https://pexo.ai/home?billing=credits` and have them complete the purchase flow.\n3. Do not retry until the user confirms that credits have been added or the suspension has been resolved.\n\nFor a concurrent-project limit, video output limit, or incompatible project, follow the response `message` instead of using the credit remediation.\n\n### `pexo-chat.sh` returns success immediately\n\nThis is expected.\n\nThe script only confirms that the request was accepted by the server, then exits.\nIt does not stream progress or final results to the terminal.\nIt also does not return business errors emitted after the SSE acknowledgement.\n\nNext step:\n\n1. Wait `60` seconds.\n2. Run `pexo-project-get.sh `.\n3. Follow `nextAction`.\n\n### `nextAction=FAILED` with `failureReason=INSUFFICIENT_CREDITS`\n\nMeaning:\n\n- Production started but stopped when a billable operation found that the account did not have enough credits.\n- The matching error details are retained in `recentMessages` with `event: \"error\"`.\n\nAction:\n\n1. Tell the user prominently that production stopped because the account has insufficient credits.\n2. Direct them to top up credits at `https://pexo.ai/home?billing=credits`.\n3. Do not retry until the user confirms that credits have been added.\n4. Use `recentMessages[].errorMessage` for additional detail when needed; use `failureReason`, not free-form hint text, to select this remediation.\n\n### `nextAction=CONFIRM`\n\nThe project is waiting for a decision on a billable generation batch.\n\n1. Read `confirmation.estimated_credits`, `confirmation.available_credits`, and `confirmation.sufficient`.\n2. If `sufficient` is `true`, explain the estimate and ask the user for explicit approval.\n3. After approval, run `pexo-billing-confirm.sh --user-approved`, then resume polling.\n4. If `sufficient` is `false`, direct the user to purchase credits. Do not submit approval.\n5. If the user changes the request, send the revised message with `pexo-chat.sh`; this cancels the pending confirmation.\n\n### `WAIT` lasts a long time\n\nThis is normal for video generation.\n\nPractical guideline:\n\n1. Keep polling every `60` seconds.\n2. Do not send another `pexo-chat.sh` message while `nextAction=WAIT`.\n3. If the project later becomes `RECONNECT`, send a short continuation message and resume polling.\n\n### `RECONNECT` keeps appearing\n\nMeaning:\n\n- The connection to the video generation service was interrupted.\n\nAction:\n\n1. Send a short message with `pexo-chat.sh`, for example `continue`.\n2. Resume polling with `pexo-project-get.sh`.\n3. If this repeats multiple times, start a new project instead of looping forever.\n\n### Download URL expired or returns `403`\n\nSigned URLs are temporary.\n\nAction:\n\n1. Re-run `pexo-asset-get.sh `.\n2. The script will fetch a fresh `downloadUrl` and re-download the file into `~/.pexo/tmp/`.\n3. Deliver the fresh `downloadUrl`.\n\n### Upload fails locally with “unsupported file type”\n\nThis is a local pre-check, not a backend outage.\n\nAction:\n\n1. Convert the file into one of the supported formats listed above.\n2. Retry `pexo-upload.sh`.\n\n### A script says `401`, but the API key may still be fine\n\nInspect the error payload:\n\n- `error=INVALID_API_KEY`: fix the key\n- `error=INTERNAL_ERROR`: treat it as a temporary service issue, not a key problem\n\nFile v0.1.4:skill-card.md\n\n## Description:
\nPexo Video Agent helps agents create finished multi-shot videos from text, images, URLs, scripts, or audio through Pexo's external API, with project tracking, billing confirmation, diagnostics, and local download handling.
\n\nThis skill is ready for commercial/non-commercial use.
\n\n## Publisher:
\n[pexo](https://clawhub.ai/user/pexo)
\n\n### License/Terms of Use:
\nMIT-0
\n\n\n## Use Case:
\nExternal users, developers, and content teams use this skill to turn natural-language briefs and approved media into product ads, social clips, explainer videos, brand videos, and revisions managed through Pexo projects.
\n\n### Deployment Geography for Use:
\nGlobal
\n\n## Known Risks and Mitigations:
\nRisk: Briefs, selected media files, project metadata, and billing-confirmation decisions are sent to Pexo.
\nMitigation: Obtain explicit user consent before the first external transmission, upload only user-selected assets, and avoid secrets, regulated data, and unrelated local files.
\nRisk: Billable generation batches can consume Pexo credits.
\nMitigation: Show the Pexo-provided estimate and require explicit user approval before running billing confirmation; the script requires the --user-approved flag.
\nRisk: Generated media downloads are stored on local disk.
\nMitigation: Store downloads under ~/.pexo/tmp or PEXO_TMP_DIR with restricted permissions and periodically clear that directory when generated media should not remain on disk.
\nRisk: A Pexo API key is required for authenticated requests.
\nMitigation: Keep the API key private, store it in ~/.pexo/config or the environment with restrictive permissions, and rotate it if it is exposed or invalid.
\n\n\n## Reference(s):
\n- [ClawHub Pexo Video Agent](https://clawhub.ai/pexo/skills/pexo-video-agent)
\n- [Pexo OpenClaw Guide](https://pexo.ai/connect/openclaw)
\n- [Setup Checklist](references/SETUP-CHECKLIST.md)
\n- [Troubleshooting](references/TROUBLESHOOTING.md)
\n\n\n## Skill Output:
\n**Output Type(s):** [text, shell commands, configuration, guidance, files]
\n**Output Format:** [Markdown instructions with bash commands and JSON-producing shell scripts]
\n**Output Parameters:** [1D]
\n**Other Properties Related to Output:** [Requires PEXO_API_KEY, bash, curl, jq, file, outbound HTTPS to https://pexo.ai, and local storage for generated media.]
\n\n## Skill Version(s):
\n0.1.4 (source: release metadata, frontmatter)
\n\n## Ethical Considerations:
\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.
\n\nFile v0.1.4:agents/openai.yaml\n\ninterface:\n display_name: \"Pexo Video Agent\"\n short_description: \"Create finished multi-shot AI videos\"\n default_prompt: \"Use $pexo-video-agent only when I explicitly ask to produce a video; confirm before sending my brief or selected assets to Pexo.\"\n\nArchive v0.1.3: 15 files, 34895 bytes\n\nFiles: agents/openai.yaml (255b), references/SETUP-CHECKLIST.md (3766b), references/TROUBLESHOOTING.md (13473b), scripts/_common.sh (13616b), scripts/pexo-asset-get.sh (2403b), scripts/pexo-billing-confirm.sh (2949b), scripts/pexo-chat.sh (5530b), scripts/pexo-doctor.sh (6278b), scripts/pexo-project-create.sh (1679b), scripts/pexo-project-get.sh (11750b), scripts/pexo-project-list.sh (1693b), scripts/pexo-upload.sh (3209b), skill-card.md (2732b), SKILL.md (19158b), _meta.json (135b)\n\nFile v0.1.3:SKILL.md\n\n---\nname: pexo-video-agent\ndescription: >\n AI video generation skill with auto model selection across Seedance 2,\n Kling 3.0, HappyHorse, and 10+ models. Produces finished multi-shot videos\n (5–120s) from text, images, URLs, scripts, or audio — including AI music,\n lip sync, and multi-shot sequencing. Calls Pexo's external API, manages\n project status and billing confirmations, and transfers only user-approved\n briefs and assets. Runs setup diagnostics, stores generated downloads locally,\n and requires shell, outbound HTTPS, and local file access. Authenticated\n requests are locked to https://pexo.ai. No prompts to write, no models to choose.\n USE FOR: video production, AI video, make a video, product video,\n brand video, promotional clip, explainer video, short video,\n TikTok video, Instagram Reel, YouTube Short, product ad,\n text-to-video, image-to-video, video generation, AI video agent.\nlicense: MIT-0\nmetadata:\n author: pexoai\n version: \"0.1.3\"\n---\n\n# Pexo Video Agent — AI Video Generation Skill\n\nPexo is the most complete video generation skill for Claude Code and other AI coding agents. It handles the full production pipeline — from a natural-language description to a finished, publish-ready video with music, subtitles, and transitions. Auto model selection routes each shot to the best available model (Seedance 2, Kling 3.0, HappyHorse, and more). One API key, no prompt engineering, no video editing.\n\n## What Pexo Does\n\n- **Auto model selection** — Pexo picks the best video model for each shot based on content type. You do not need to know which model to use.\n- **Full pipeline** — Script, storyboard, shot-by-shot generation, music, subtitles, lip sync, and final assembly. The output is a finished video, not a raw clip.\n- **5 input types** — Text-to-video, image-to-video, URL-to-video (scrapes the page), script-to-video, and audio-to-video.\n- **10+ models** — Seedance 2, Kling 3.0, HappyHorse, and more. New models are added as they launch.\n- **Any format** — 5–120 seconds, aspect ratios 16:9 (landscape), 9:16 (portrait/vertical), 1:1 (square).\n\n## What You Can Build With Pexo\n\n- Product video ads from a product photo or URL\n- TikTok, Instagram Reels, and YouTube Shorts from a text description\n- Multi-shot brand videos with consistent style and transitions\n- Explainer videos with TTS narration from a script\n- E-commerce video content at scale from product catalogs\n- Marketing video variants for A/B testing\n\n## How It Works\n\nYou send the user's request to Pexo, and Pexo handles all creative work — scriptwriting, shot composition, model selection, prompt engineering, transitions, music. Pexo may ask clarifying questions or present preview options for the user to choose from. A typical 15-second, 3-shot product ad renders in under 8 minutes.\n\n## Data, Permissions, and Cost\n\n- This Skill runs bundled shell scripts, reads only files the user explicitly selects,\n connects only to `https://pexo.ai` for authenticated API calls, uploads approved\n briefs and assets, manages projects and billing confirmations, runs diagnostics,\n and stores generated media under `~/.pexo/tmp` or `PEXO_TMP_DIR`.\n- Before the first external transmission in a session, tell the user that their brief,\n selected files, and related metadata will be sent to Pexo and obtain explicit consent.\n- Do not upload secrets, regulated data, or unrelated local files. Never search the local\n filesystem for additional material without a separate user request.\n- Every billable generation batch requires explicit user approval by default. Report the\n available estimate from Pexo before approving a confirmation.\n\n## Script Execution\n\nResolve `SKILL_ROOT` to the directory containing this `SKILL.md`. Script names\nbelow are shorthand for `bash \"$SKILL_ROOT/scripts/\"`; do not rely\non executable bits or a modified `PATH`.\n\n## Prerequisites\n\nConfig file `~/.pexo/config`:\n\n```bash\numask 077\nmkdir -p ~/.pexo\nread -rsp \"Pexo API key: \" pexo_api_key\nprintf '\\n'\n{\n printf '%s=%s\\n' PEXO_API_KEY \"$pexo_api_key\"\n} > ~/.pexo/config\nunset pexo_api_key\nchmod 600 ~/.pexo/config\n```\n\nFirst time using this skill or encountering a config error → run `pexo-doctor.sh` and follow its output. See `references/SETUP-CHECKLIST.md` for details.\n\n### Credit Confirmation Preference\n\n`PEXO_BILLING_CONFIRMATION_MODE` controls the confirmation behavior for each message sent by this Skill. It is optional; the default is `always`.\n\n- `always`: ask for approval before every billable generation batch.\n- `threshold`: ask when the estimated batch cost exceeds the platform threshold, or when the available balance is insufficient. Use only after the user explicitly opts in for the current session.\n\nUse `pexo-chat.sh --billing-confirmation-mode ` to override the default for one message.\n\n---\n\n## ⚠️ LANGUAGE RULE (highest priority)\n\n**You MUST reply to the user in the SAME language they use. This is non-negotiable.**\n\n- User writes in English → you reply in English\n- User writes in Chinese → you reply in Chinese\n- User writes in Japanese → you reply in Japanese\n\nThis applies to every message you send. If the user switches language mid-conversation, you switch too.\n\n---\n\n## Your Role: Delivery Worker\n\nYou are a delivery worker between the user and Pexo. You do three things:\n\n1. **Upload**: user gives a file → `pexo-upload.sh` → get asset ID\n2. **Relay**: copy the user's words into `pexo-chat.sh`\n3. **Deliver**: poll for results → send video and link to user\n\nPexo's backend is a professional video creation agent. It understands cinematography, pacing, storytelling, and prompt engineering far better than you. When you add your own creative ideas, the video quality goes down.\n\n### How to relay messages — copy-paste template\n\nWhen calling pexo-chat.sh, copy the user's message exactly:\n\n```\npexo-chat.sh \"{user's message, copied exactly}\"\n```\n\nExample — user said \"做个猫的视频\":\n```\npexo-chat.sh proj_123 \"做个猫的视频\"\n```\n\nExample — user said \"I want a product video for my shoes\" and uploaded shoes.jpg:\n```\nasset_id=$(pexo-upload.sh proj_123 shoes.jpg)\npexo-chat.sh proj_123 \"I want a product video for my shoes ${asset_id}\"\n```\n\nYour only addition to the user's message is asset tags for uploaded files. Everything else stays exactly as the user wrote it.\n\n### When the user's request is vague\n\nPass it to Pexo exactly as-is. Pexo will ask the user for any missing details. Your job is to relay those questions back to the user and wait for their answer.\n\n### Why this matters\n\nPexo's backend agent specializes in video production. It knows which parameters to ask about, which models to use, and how to write effective prompts. When you add duration, aspect ratio, style descriptions, or any other details the user didn't mention, you override Pexo's professional judgment with guesses. This produces worse videos.\n\n---\n\n## First-Time Setup Message\n\nAfter Pexo is configured for the first time, send the user this message (in the user's language):\n\n> ✅ Pexo is ready!\n> 📖 Guide: https://pexo.ai/connect/openclaw\n> Tell me what video you'd like to make.\n\n---\n\n## Step-by-Step Workflow\n\nFollow these steps in order.\n\n### Making a New Video\n\n```\nStep 1. Create project.\n Run: pexo-project-create.sh \"brief description\"\n If the command succeeds: save the returned project_id.\n If the command fails and stderr contains \"Credits balance\"\n or \"credits\" or \"Insufficient credits\":\n → Go to Credit Error Handling below.\n If the command fails for other reasons:\n → Tell the user what went wrong and offer to retry.\n\nStep 2. Upload files (if user provided any images/videos/audio).\n Run: pexo-upload.sh \n Save the returned asset_id.\n Wrap in tag: asset_id\n (or / for other file types)\n\nStep 3. Send user's message to Pexo.\n Run: pexo-chat.sh \"{user's exact words} asset_id\"\n Copy the user's words exactly. Only add asset tags for uploaded files.\n If the command fails and stderr contains \"Credits balance\"\n or \"credits\" or \"Insufficient credits\":\n → Go to Credit Error Handling below.\n If the command fails for other reasons:\n → Tell the user what went wrong and offer to retry.\n\nStep 4. Notify the user (in the user's language).\n Your message must contain these three items:\n - Confirmation that the request is submitted to Pexo\n - Estimated time: 15–20 minutes for a short video\n - Project link: https://pexo.ai/project/{project_id}\n\nStep 5. Poll for status.\n Run: sleep 60\n Run: pexo-project-get.sh \n Read the nextAction field from the returned JSON.\n Continue to Step 6.\n\nStep 6. Act on nextAction:\n\n \"WAIT\" →\n Go back to Step 5. Keep repeating.\n Every 5 polls (~5 minutes), send user a brief update with\n the project link: https://pexo.ai/project/{project_id}\n\n \"CONFIRM\" →\n Read the confirmation object. It contains confirmation_id, estimated_credits,\n available_credits, sufficient, and the pending tool batch.\n\n If sufficient is false:\n Tell the user that the available credits cannot cover this request.\n Go to Credit Error Handling below. Do not run pexo-billing-confirm.sh.\n\n If sufficient is true:\n Tell the user the estimated credit cost and ask for explicit approval.\n Do not approve on the user's behalf.\n\n After explicit approval:\n Run: pexo-billing-confirm.sh \n Go back to Step 5.\n\n If the user changes the request instead:\n Run: pexo-chat.sh \"{user's exact revised request}\"\n This cancels the pending confirmation before submitting the new message.\n Go back to Step 5.\n\n \"RESPOND\" →\n Read the recentMessages array. Handle every event:\n\n Event \"message\" (Pexo sent text):\n Relay Pexo's text to the user in full.\n If Pexo asked a question, wait for the user's answer.\n Then run: pexo-chat.sh \"{user's exact answer}\"\n Go back to Step 5.\n\n Event \"preview_video\" (Pexo sent preview options):\n For each assetId in assetIds:\n Run: pexo-asset-get.sh \n Copy the \"url\" field from the returned JSON.\n Show all preview URLs to the user with labels (A, B, C...).\n Ask the user to pick one.\n After user picks:\n Run: pexo-chat.sh \"{user's choice}\" --choice \n Go back to Step 5.\n\n Event \"document\":\n Mention the document to the user.\n\n Event \"attachment\":\n Fetch each assetId with pexo-asset-get.sh and deliver the resulting file or URL.\n\n \"DELIVER\" →\n Go to Step 7.\n\n \"FAILED\" →\n Go to Step 8.\n\n \"RECONNECT\" →\n Run: pexo-chat.sh \"continue\"\n Tell the user the connection was interrupted and you are reconnecting.\n Go back to Step 5.\n\nStep 7. Deliver the final video.\n\n 7a. Relay any message events in recentMessages, then find the final_video\n event and get its assetId.\n\n 7b. Run: pexo-asset-get.sh \n\n 7c. Show the downloaded video file to the user.\n\n 7d. Also send the user a message (in their language) with:\n - The video download URL (copy the \"url\" field from the JSON output).\n Send the FULL URL as plain text, including all query parameters.\n Example:\n https://pexo-assets.oss-us-east-1.aliyuncs.com/projects%2F123%2Fassets%2Fvideo.mp4?OSSAccessKeyId=xxx&Expires=xxx&Signature=xxx\n - Project page: https://pexo.ai/project/{project_id}\n - Ask if satisfied or want revisions.\n\n Common delivery mistakes to avoid:\n ✗ Truncated URL (missing ?OSSAccessKeyId=...&Signature=...) → 403 Forbidden\n ✗ Markdown wrapped [text](url) → URL breaks on some platforms\n\nStep 8. Handle failure.\n\n 8a. Read failureReason, nextActionHint, and recentMessages from the JSON.\n 8b. If failureReason is \"INSUFFICIENT_CREDITS\":\n Tell the user prominently that production stopped because the account\n has insufficient credits.\n Go to Credit Error Handling below. Do not offer or attempt a retry\n until the user confirms that credits have been added.\n Otherwise, if stderr from the failed command contains \"Credits balance\",\n \"credits\", or \"Insufficient credits\":\n Go to Credit Error Handling below.\n Otherwise, send the user a message (in their language) with:\n - What went wrong (explain nextActionHint in simple terms)\n - Project page: https://pexo.ai/project/{project_id}\n - Offer to retry.\n\nStep 9. Timeout.\n\n If you have been in the Step 5 loop for more than 30 minutes\n and nextAction is still \"WAIT\":\n\n Send the user a message (in their language) with:\n - The video is taking longer than expected.\n - Project page: https://pexo.ai/project/{project_id}\n - Help guide: https://pexo.ai/connect/openclaw\n - Ask whether to keep waiting or start over.\n Stop polling. Wait for user instructions.\n```\n\n### Credit Error Handling\n\nUse this flow when `pexo-project-get.sh` returns\n`failureReason: \"INSUFFICIENT_CREDITS\"`, or when a command fails and stderr\ncontains credit-related information (look for: \"Credits balance\", \"credits\",\nor \"Insufficient credits\"):\n\n```\nStep A. If stderr contains a purchase link and instructions, send them\n to the user (in their language).\n\nStep B. If stderr only contains the error message without a purchase link,\n send the user a message (in their language) with:\n - Their credits are insufficient.\n - To add credits: visit https://pexo.ai/home?billing=credits\n and complete the purchase flow.\n\nStep C. After the user confirms they have added credits, retry the failed step.\n```\n\n### Revising an Existing Video\n\n```\nStep 1. Use the same project_id.\nStep 2. Run: pexo-chat.sh \"{user's exact feedback}\"\nStep 3. Go to Step 5 of the main workflow (start polling).\n```\n\n---\n\n## Asset Upload\n\nPexo can process a public `https://` webpage URL when it is included verbatim in the user's\nbrief. Pass that webpage URL to Pexo; do not scrape or download the page locally.\n\nFor a direct image, video, or audio file URL, ask for explicit approval before downloading it,\nthen upload the downloaded file. Only fetch public `https://` URLs. Never fetch `http://`,\nlocalhost, loopback, link-local, private-network, credential-bearing, or signed/private URLs;\nask the user to upload those files directly instead.\n\nUpload and reference workflow:\n```bash\n# Upload the file\nasset_id=$(pexo-upload.sh photo.jpg)\n\n# Reference the asset in your message to Pexo\npexo-chat.sh \"Here is the product photo ${asset_id}, please use it as reference\"\n```\n\nTag formats:\n```\nasset-id\nasset-id\nasset-id\n```\n\nTags are mandatory. Bare asset IDs in pexo-chat.sh messages are ignored by Pexo.\n\n---\n\n## Important Rules\n\n### Polling\n- During WAIT: only call pexo-project-get.sh. Calling pexo-chat.sh during WAIT triggers duplicate video production.\n- Wait at least 60 seconds between each pexo-project-get.sh call.\n- Process every event in recentMessages, not just the first one.\n\n### Credit Confirmation\n- Treat `nextAction=CONFIRM` as a user decision point, not as WAIT or RESPOND.\n- Only run `pexo-billing-confirm.sh` after the user explicitly approves the displayed estimate.\n- Use the `confirmation_id` returned by `pexo-project-get.sh`; confirmation IDs apply only to the current pending batch.\n- A revised message sent with `pexo-chat.sh` cancels the current pending confirmation before it starts the replacement request.\n\n### Delivery\n- Copy the \"url\" field from pexo-asset-get.sh output. Send it as plain text with all query parameters.\n- Show the downloaded video file to the user when possible.\n\n### Projects\n- New video → pexo-project-create.sh to create a new project.\n- Revisions → reuse the existing project_id.\n\n### Cost\n- Each message to Pexo costs tokens. Consolidate information into one message when possible.\n- For `nextAction=FAILED`, use `failureReason` for remediation. Do not infer a failure category from `nextActionHint` text.\n\n---\n\n## Script Reference\n\n| Script | Usage | Returns |\n|---|---|---|\n| `pexo-project-create.sh` | `[project_name]` or `--name ` | `project_id` string. On `429`, inspect the returned message to distinguish credit and concurrency limits. |\n| `pexo-project-list.sh` | `[page_size]` or `--page --page-size ` | Projects JSON |\n| `pexo-project-get.sh` | ` [--full-history]` | JSON with `nextAction`, `nextActionHint`, `recentMessages`; `CONFIRM` includes `confirmation`; recognized `FAILED` states include `failureReason`, and error events retain `errorCode`, `errorMessage`, and `toolCallId` |\n| `pexo-upload.sh` | ` ` | `asset_id` string |\n| `pexo-chat.sh` | ` [--choice ] [--billing-confirmation-mode ] [--timeout ]` | Acknowledgement JSON (async). A new message cancels a pending confirmation. On `429`/`412` or credit errors, error info printed to stderr. |\n| `pexo-billing-confirm.sh` | ` [--timeout ]` | Approves the current sufficient credit confirmation after explicit user approval. |\n| `pexo-asset-get.sh` | ` ` | JSON with video details and `url` field |\n| `pexo-doctor.sh` | (no args) | Diagnostic report |\n\n---\n\n## Pexo Capabilities\n\n- Output: 5–120 second finished videos with music, subtitles, and transitions\n- Aspect ratios: 16:9 (landscape), 9:16 (portrait/vertical for TikTok, Reels, Shorts), 1:1 (square)\n- Auto model selection: Seedance 2, Kling 3.0, HappyHorse, and more — Pexo picks the best model per shot\n- Input types: text, images, URLs, scripts, audio\n- Production time: ~8 minutes for a 15-second 3-shot video, ~20 minutes for a 60-second brand video\n- Supported uploads: Images (jpg, png, webp, bmp, tiff, heic), Videos (mp4, mov, avi), Audio (mp3, wav, aac, m4a, ogg, flac)\n- Post-production: AI music, TTS narration, voice cloning, lip sync, subtitles, transitions\n\n---\n\n## References\n\nLoad these when needed:\n\n- **First time or config error** → read `references/SETUP-CHECKLIST.md`\n- **Error codes or failures** → read `references/TROUBLESHOOTING.md`\n\nFile v0.1.3:_meta.json\n\n{\n \"ownerId\": \"kn7cyy6q5gnqcc174487e2pd4n828hay\",\n \"slug\": \"pexo-video-agent\",\n \"version\": \"0.1.3\",\n \"publishedAt\": 1784599641706\n}\n\nFile v0.1.3:references/SETUP-CHECKLIST.md\n\n# Setup Checklist\n\nThis guide covers first-time setup and environment diagnostics for the Pexo agent skill.\n\nRun bundled scripts through Bash from the skill directory, for example\n`bash scripts/pexo-doctor.sh`; installed files may not retain executable bits.\n\n## Quick Start\n\n### 1. Create config file\n\n```bash\numask 077\nmkdir -p ~/.pexo\nread -rsp \"Pexo API key: \" pexo_api_key\nprintf '\\n'\n{\n printf '%s=%s\\n' PEXO_API_KEY \"$pexo_api_key\"\n} > ~/.pexo/config\nunset pexo_api_key\nchmod 600 ~/.pexo/config\n```\n\nGet your API key at: https://pexo.ai\n\n- If you do not have an account:\n Go to https://pexo.ai and sign up. During registration, you will be asked for an invite code.\n Use invite code: **BV5N38**\n New users receive bonus credits upon registration — enough to try out video generation right away.\n- If you are already logged in:\n click the top-right avatar → `API Keys` → `Create Key`, then copy the new key.\n\n### 2. Run diagnostics\n\nThe next command makes outbound HTTPS requests only to `https://pexo.ai`. It performs\nan unauthenticated connectivity check and, when an API key is configured, an authenticated\nproject-list request to validate access. Pexo may log these requests; they do not start a\ngeneration or consume generation credits. Run it only after the user approves this check.\n\n```bash\nbash scripts/pexo-doctor.sh\n```\n\nThis checks:\n- Config file exists and is readable\n- `PEXO_BASE_URL` and `PEXO_API_KEY` are set\n- `curl`, `jq`, and `file` are installed\n- Network connectivity to Pexo servers\n- API key is valid (attempts to list projects)\n\nFix any issues reported before using other scripts.\n\n### 3. Verify\n\nThe next command sends an authenticated project-list request to `https://pexo.ai` and may\nappear in Pexo service logs. It does not create a project or consume generation credits.\n\n```bash\nbash scripts/pexo-project-list.sh\n```\n\nIf this returns a JSON list (even if empty), setup is complete.\n\n## Troubleshooting Setup Issues\n\n### \"PEXO_BASE_URL must be exactly https://pexo.ai\"\n\nAuthenticated requests are restricted to the production Pexo origin. Remove any custom base\nURL override, or set it to exactly `https://pexo.ai`.\n\n### \"Set PEXO_API_KEY in ~/.pexo/config or env\"\n\nSame as above — the API key line is missing from the config file.\n\n### API key invalid (401 Unauthenticated)\n\nYour API key may be expired or incorrect. Log in at https://pexo.ai to generate a new one. Replace the value in `~/.pexo/config`.\n\n### curl, jq, or file not found\n\nInstall the missing dependency:\n\n```bash\n# macOS (file is usually preinstalled)\nbrew install curl jq\n\n# Ubuntu/Debian\napt-get install -y curl jq file\n\n# CentOS/RHEL\nyum install -y curl jq file\n```\n\n### Network connectivity failure\n\nIf `pexo-doctor.sh` reports a connectivity issue:\n- Check if your server can reach `pexo.ai` (e.g. `curl -I https://pexo.ai`)\n- Check firewall rules for outbound HTTPS (port 443)\n- If behind a proxy, configure `http_proxy`/`https_proxy` environment variables\n\n## Environment Variables\n\nAll scripts read `~/.pexo/config` automatically. You can also override via environment variables:\n\nOnly `PEXO_*` assignments are accepted in the config file; it is parsed as data\nand is never executed as shell code. Explicit environment variables take\nprecedence over values in the config file.\n\n| Variable | Description | Required |\n|---|---|---|\n| `PEXO_BASE_URL` | Optional compatibility override; if set, must be exactly `https://pexo.ai` | No |\n| `PEXO_API_KEY` | Your Pexo API key (starts with `sk-`) | Yes |\n| `PEXO_CONFIG` | Custom path to config file (default: `~/.pexo/config`) | No |\n| `PEXO_BILLING_CONFIRMATION_MODE` | Credit confirmation mode: `always` or `threshold` (default: `always`; use `threshold` only after explicit user opt-in) | No |\n\nFile v0.1.3:references/TROUBLESHOOTING.md\n\n# Troubleshooting\n\n## Script Exit Behavior\n\n- Exit `0`: success\n- Exit `1`: request/transport/backend failure\n- Exit `2`: local usage error (missing args, invalid flags, invalid local input)\n\nOn request failure, scripts print compact JSON to `stderr`, for example:\n\n```json\n{\"ok\":false,\"httpCode\":429,\"message\":\"Daily creation limit reached. Contact support email for more access.\"}\n```\n\nFields you may see:\n\n- `httpCode`: the real HTTP status code returned to the script\n- `error`: auth/proxy error code such as `INVALID_API_KEY` or `INTERNAL_ERROR`\n- `message`: the most useful user-facing message extracted from the response\n- `details`: extra backend detail when available\n\n## Auth And Proxy Errors\n\nThese can happen on every script that makes API calls:\n\n| HTTP | `error` | Meaning | What to do |\n|---|---|---|---|\n| 401 | `INVALID_API_KEY` | API key is invalid or revoked | Update `PEXO_API_KEY` in `~/.pexo/config`. Get a new key at pexo.ai. |\n| 401 | `MISSING_TOKEN` | The request was sent without an API key | Run `pexo-doctor.sh` to verify config. Make sure `~/.pexo/config` is sourced correctly. |\n| 401 | `INTERNAL_ERROR` | The service failed to process the request before authentication completed | This is a temporary service issue, not a problem with the API key. Wait a moment and retry; if it persists, contact support. |\n| 409 | `SESSION_REPLACED` | This API key's session was invalidated by a new login elsewhere | Unusual for API-key usage. Retry the command. If it keeps happening, regenerate the API key at pexo.ai. |\n\nIf the message says `Invalid API key`, it is an auth problem.\nIf the body says `error=INTERNAL_ERROR`, do not tell the user to rotate the key first; the service may simply be temporarily down.\n\n## Script-Specific Errors\n\n### `pexo-project-create.sh`\n\nReal statuses:\n\n- `400`: project name is too long. Ask the user to use a shorter name and retry.\n- `401`: auth failure — see Auth and Proxy Errors above.\n- `429`: creation limit reached — could be any of:\n - User already has an active project running (must wait for it to finish)\n - Insufficient credits to start a new project\n Read the error `message` to distinguish these cases. The script does not query the balance automatically.\n- `500`: an unexpected server error occurred. Retry in a moment; if the problem persists, contact support at pexo.ai.\n\nNotes:\n\n- If no project name is provided, the script defaults to `\"Untitled\"`.\n\n### `pexo-project-list.sh`\n\nReal statuses:\n\n- `401`: auth failure — see Auth and Proxy Errors above.\n- `500`: an unexpected server error occurred. Retry in a moment; if the problem persists, contact support at pexo.ai.\n\nNotes:\n\n- Invalid `page` / `page_size` values are handled locally by the script before request time.\n- Backend page size is effectively capped at `100`.\n\n### `pexo-project-get.sh`\n\nReal statuses from the first project fetch:\n\n- `401`: auth failure — see Auth and Proxy Errors above.\n- `404`: the project does not exist or has been deleted. Verify the project_id; if correct, start a new project.\n- `500`: an unexpected server error occurred. Retry in a moment; if the problem persists, contact support at pexo.ai.\n\nSubsequent status fetches can also fail with:\n\n- `401`: auth failure — see Auth and Proxy Errors above.\n- `404`: project not found. Same action as above.\n- `500`: an unexpected server error occurred. Retry in a moment; if the problem persists, contact support at pexo.ai.\n\n`nextAction=CONFIRM` is a successful status response. The output includes a `confirmation` object for the current pending batch. Use its `confirmation_id` only after obtaining explicit user approval.\n\n`nextAction=FAILED` can include `failureReason=INSUFFICIENT_CREDITS`. In that case, `recentMessages` retains the terminal error with `errorCode=credits.insufficient_credits_err`. This polling result is the authoritative way to detect an insufficient-credit failure that occurs after `pexo-chat.sh` has acknowledged an asynchronous submission.\n\n### `pexo-upload.sh`\n\nThis script has three phases, and the failure source matters.\n\n#### Phase 1: upload credential\n\nReal statuses:\n\n- `400`: the file name or file size is invalid. Check that the file exists and is not empty; rename it if it contains special characters.\n- `401`: auth failure — see Auth and Proxy Errors above.\n- `500`: an unexpected server error occurred. Retry in a moment; if the problem persists, contact support at pexo.ai.\n\nNotes:\n\n- The script rejects unsupported extensions locally. Supported formats:\n - Images: `jpg`, `jpeg`, `png`, `webp`, `bmp`, `tiff`, `heic`, `heif`\n - Videos: `mp4`, `mov`, `avi`\n - Audio: `mp3`, `wav`, `aac`, `m4a`, `ogg`, `flac`\n\n#### Phase 2: file transfer\n\nPossible failures:\n\n- `4xx/5xx`: the file storage service rejected the upload. Check network connectivity and retry. If the problem persists, contact support at pexo.ai.\n\nThe script surfaces this directly as:\n\n```text\nError: upload failed with HTTP \n```\n\n#### Phase 3: finalize\n\nReal statuses:\n\n- `400`: the file was rejected — possible reasons: file exceeds the size limit, file format is not supported, or the file content does not match its extension. Convert or compress the file and re-upload from scratch using `pexo-upload.sh`.\n- `401`: auth failure — see Auth and Proxy Errors above.\n- `404`: the file record was not found. The upload session may have been cleaned up. Re-upload from scratch using `pexo-upload.sh`.\n- `412`: the upload session has already expired or been completed. Re-upload from scratch using `pexo-upload.sh`.\n- `500`: an unexpected server error occurred. Retry in a moment; if the problem persists, contact support at pexo.ai.\n\n### `pexo-chat.sh`\n\nReal statuses:\n\n- `400`: the message could not be sent due to invalid content. Check the message text; if the issue persists, start a new project.\n- `401`: auth failure — see Auth and Proxy Errors above.\n- `404`: the project does not exist or has been deleted. Start a new project.\n- `412`: two possible causes:\n - **Project no longer supported**: this project was created with an older version of Pexo's production system and cannot be continued. Start a new project.\n - **Account billing issue**: the account's credits are frozen or suspended. Read the response `message`, then direct the user to top up or contact support at pexo.ai.\n- `429`: limit reached — could be insufficient credits or the project's video output limit. Read the response `message` to distinguish the cause.\n- `500`: an unexpected server error occurred. Retry in a moment; if the problem persists, contact support at pexo.ai.\n\nNotes:\n\n- `pexo-chat.sh` is asynchronous. Success means the request was accepted, not that the video is done.\n- The script stops reading the SSE stream after `: stream opened`. A business error emitted later in that stream is not returned by `pexo-chat.sh`.\n- Synchronous HTTP failures are printed as compact JSON to `stderr`. Use the HTTP status and response `message` to classify them.\n- A successful `pexo-chat.sh` call should be followed by `pexo-project-get.sh` polling, typically every `60` seconds.\n- If the asynchronous run later fails for insufficient credits, `pexo-project-get.sh` returns `nextAction=FAILED`, `failureReason=INSUFFICIENT_CREDITS`, and the matching error in `recentMessages`.\n- When a project is waiting for credit approval, sending a new message through `pexo-chat.sh` cancels that pending confirmation and submits the replacement message.\n\n### `pexo-billing-confirm.sh`\n\nThis command approves a pending billable batch. It must only be called after explicit user approval.\n\nLocal validation failures:\n\n- The project is not in `CONFIRM_REQUIRED`: fetch the project again and follow its current `nextAction`.\n- The supplied `confirmation_id` does not match the latest confirmation: use the current `confirmation.confirmation_id` returned by `pexo-project-get.sh`.\n- The confirmation event is temporarily unavailable in history: poll again shortly; the event may still be persisting.\n- `sufficient` is `false`: the available balance cannot cover the batch. Direct the user to purchase credits and do not submit approval.\n- The confirmation mode is missing or invalid: fetch the current confirmation again; do not construct an approval request manually.\n\n### `pexo-asset-get.sh`\n\nReal statuses:\n\n- `401`: auth failure — see Auth and Proxy Errors above.\n- `404`: the file does not exist, or it belongs to a different project. Verify the asset_id and project_id.\n- `500`: an unexpected server error occurred. Retry in a moment; if the problem persists, contact support at pexo.ai.\n\nSecondary download failures after metadata fetch:\n\n- `403`: the download link has expired. Re-run `pexo-asset-get.sh` to get a fresh link.\n- `000`: network request failed before receiving a response. Check network connectivity and retry.\n- local filesystem write failure: the temp directory (`~/.pexo/tmp/`) is not writable or the disk is full. Free up space or set `PEXO_TMP_DIR` to a writable path.\n\nNotes:\n\n- The script downloads the file into `~/.pexo/tmp/` (or `$PEXO_TMP_DIR`) and returns both `url` and `localPath`.\n- If the asset metadata exists but `downloadUrl` is absent, the script returns `localPath: null`.\n\n### `pexo-doctor.sh`\n\n- `200`: config and API key look healthy\n- `401` + `INVALID_API_KEY`: API key is invalid or revoked. Update `PEXO_API_KEY` in `~/.pexo/config`.\n- `401` + `INTERNAL_ERROR`: the service failed temporarily — not a key problem. Wait and retry.\n- `409`: session conflict, unusual for API-key usage. Retry the command.\n- `000`: no response received — network is unreachable or DNS failed. Check connectivity.\n\n## Common Scenarios\n\n### Synchronous `429` or `412` from project creation or chat submission\n\nThese scripts print the HTTP failure as compact JSON to `stderr`. They do not query or append the current credit balance. Read both `httpCode` and `message` before choosing an action because these statuses also represent non-credit limits and compatibility failures.\n\nIf the response identifies insufficient or suspended credits:\n\n1. Explain the credit restriction to the user.\n2. Direct them to `https://pexo.ai/home?billing=credits` and have them complete the purchase flow.\n3. Do not retry until the user confirms that credits have been added or the suspension has been resolved.\n\nFor a concurrent-project limit, video output limit, or incompatible project, follow the response `message` instead of using the credit remediation.\n\n### `pexo-chat.sh` returns success immediately\n\nThis is expected.\n\nThe script only confirms that the request was accepted by the server, then exits.\nIt does not stream progress or final results to the terminal.\nIt also does not return business errors emitted after the SSE acknowledgement.\n\nNext step:\n\n1. Wait `60` seconds.\n2. Run `pexo-project-get.sh `.\n3. Follow `nextAction`.\n\n### `nextAction=FAILED` with `failureReason=INSUFFICIENT_CREDITS`\n\nMeaning:\n\n- Production started but stopped when a billable operation found that the account did not have enough credits.\n- The matching error details are retained in `recentMessages` with `event: \"error\"`.\n\nAction:\n\n1. Tell the user prominently that production stopped because the account has insufficient credits.\n2. Direct them to top up credits at `https://pexo.ai/home?billing=credits`.\n3. Do not retry until the user confirms that credits have been added.\n4. Use `recentMessages[].errorMessage` for additional detail when needed; use `failureReason`, not free-form hint text, to select this remediation.\n\n### `nextAction=CONFIRM`\n\nThe project is waiting for a decision on a billable generation batch.\n\n1. Read `confirmation.estimated_credits`, `confirmation.available_credits`, and `confirmation.sufficient`.\n2. If `sufficient` is `true`, explain the estimate and ask the user for explicit approval.\n3. After approval, run `pexo-billing-confirm.sh `, then resume polling.\n4. If `sufficient` is `false`, direct the user to purchase credits. Do not submit approval.\n5. If the user changes the request, send the revised message with `pexo-chat.sh`; this cancels the pending confirmation.\n\n### `WAIT` lasts a long time\n\nThis is normal for video generation.\n\nPractical guideline:\n\n1. Keep polling every `60` seconds.\n2. Do not send another `pexo-chat.sh` message while `nextAction=WAIT`.\n3. If the project later becomes `RECONNECT`, send a short continuation message and resume polling.\n\n### `RECONNECT` keeps appearing\n\nMeaning:\n\n- The connection to the video generation service was interrupted.\n\nAction:\n\n1. Send a short message with `pexo-chat.sh`, for example `continue`.\n2. Resume polling with `pexo-project-get.sh`.\n3. If this repeats multiple times, start a new project instead of looping forever.\n\n### Download URL expired or returns `403`\n\nSigned URLs are temporary.\n\nAction:\n\n1. Re-run `pexo-asset-get.sh `.\n2. The script will fetch a fresh `downloadUrl` and re-download the file into `~/.pexo/tmp/`.\n3. Deliver the fresh `downloadUrl`.\n\n### Upload fails locally with “unsupported file type”\n\nThis is a local pre-check, not a backend outage.\n\nAction:\n\n1. Convert the file into one of the supported formats listed above.\n2. Retry `pexo-upload.sh`.\n\n### A script says `401`, but the API key may still be fine\n\nInspect the error payload:\n\n- `error=INVALID_API_KEY`: fix the key\n- `error=INTERNAL_ERROR`: treat it as a temporary service issue, not a key problem\n\nFile v0.1.3:skill-card.md\n\n## Description:
\nPexo Video Agent creates finished multi-shot videos from text, images, URLs, scripts, or audio by sending user-approved briefs and assets to Pexo's external API, managing project status, billing confirmations, setup diagnostics, and local downloads.
\n\nThis skill is ready for commercial/non-commercial use.
\n\n## Publisher:
\n[pexo](https://clawhub.ai/user/pexo)
\n\n### License/Terms of Use:
\nMIT-0
\n\n\n## Use Case:
\nExternal users, marketers, creators, and developers use this skill to turn product photos, URLs, scripts, audio, or text briefs into finished short videos and revisions through Pexo.
\n\n### Deployment Geography for Use:
\nGlobal
\n\n## Known Risks and Mitigations:
\nRisk: Approved briefs, selected media, and related metadata are sent to Pexo for video generation.
\nMitigation: Obtain explicit consent before transmission and avoid uploading secrets, regulated data, or unrelated local files.
\nRisk: Billable generation batches may consume Pexo credits.
\nMitigation: Show the available estimate and require explicit user approval before confirming billable steps.
\nRisk: Generated media is stored locally under ~/.pexo/tmp or PEXO_TMP_DIR.
\nMitigation: Set PEXO_TMP_DIR to a controlled location or delete cached media when generated assets are sensitive.
\nRisk: Diagnostics and project checks make outbound HTTPS requests to Pexo and may appear in Pexo service logs.
\nMitigation: Run diagnostics only after user approval and keep authenticated traffic pinned to https://pexo.ai.
\n\n\n## Reference(s):
\n- [Pexo Video Agent on ClawHub](https://clawhub.ai/pexo/skills/pexo-video-agent)
\n- [Pexo OpenClaw Guide](https://pexo.ai/connect/openclaw)
\n- [Setup Checklist](references/SETUP-CHECKLIST.md)
\n- [Troubleshooting](references/TROUBLESHOOTING.md)
\n\n\n## Skill Output:
\n**Output Type(s):** [Text, Shell commands, Configuration, Guidance, Files]
\n**Output Format:** [Markdown or plain text with shell commands, JSON status payloads, asset IDs, video download URLs, and local video files.]
\n**Output Parameters:** [1D]
\n**Other Properties Related to Output:** [Requires user consent before external transmission and explicit approval for billable generation batches; generated media is cached under ~/.pexo/tmp or PEXO_TMP_DIR.]
\n\n## Skill Version(s):
\n0.1.3 (source: evidence release and skill frontmatter)
\n\n## Ethical Considerations:
\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.
\n\nFile v0.1.3:agents/openai.yaml\n\ninterface:\n display_name: \"Pexo Video Agent\"\n short_description: \"Create finished multi-shot AI videos\"\n default_prompt: \"Use $pexo-video-agent only when I explicitly ask to produce a video; confirm before sending my brief or selected assets to Pexo.\"\n\nArchive v0.1.2: 15 files, 34339 bytes\n\nFiles: agents/openai.yaml (255b), references/SETUP-CHECKLIST.md (3166b), references/TROUBLESHOOTING.md (13473b), scripts/_common.sh (13081b), scripts/pexo-asset-get.sh (2403b), scripts/pexo-billing-confirm.sh (2949b), scripts/pexo-chat.sh (5530b), scripts/pexo-doctor.sh (6393b), scripts/pexo-project-create.sh (1679b), scripts/pexo-project-get.sh (11750b), scripts/pexo-project-list.sh (1693b), scripts/pexo-upload.sh (3209b), skill-card.md (2943b), SKILL.md (18557b), _meta.json (135b)\n\nFile v0.1.2:SKILL.md\n\n---\nname: pexo-video-agent\ndescription: >\n AI video generation skill with auto model selection across Seedance 2,\n Kling 3.0, HappyHorse, and 10+ models. Produces finished multi-shot videos\n (5–120s) from text, images, URLs, scripts, or audio — including AI music,\n lip sync, and multi-shot sequencing. Calls Pexo's external API, manages\n project status and billing confirmations, and transfers only user-approved\n briefs and assets. Requires shell, outbound HTTPS, and local file access.\n No prompts to write, no models to choose.\n USE FOR: video production, AI video, make a video, product video,\n brand video, promotional clip, explainer video, short video,\n TikTok video, Instagram Reel, YouTube Short, product ad,\n text-to-video, image-to-video, video generation, AI video agent.\nlicense: MIT-0\nmetadata:\n author: pexoai\n version: \"0.1.2\"\n---\n\n# Pexo Video Agent — AI Video Generation Skill\n\nPexo is the most complete video generation skill for Claude Code and other AI coding agents. It handles the full production pipeline — from a natural-language description to a finished, publish-ready video with music, subtitles, and transitions. Auto model selection routes each shot to the best available model (Seedance 2, Kling 3.0, HappyHorse, and more). One API key, no prompt engineering, no video editing.\n\n## What Pexo Does\n\n- **Auto model selection** — Pexo picks the best video model for each shot based on content type. You do not need to know which model to use.\n- **Full pipeline** — Script, storyboard, shot-by-shot generation, music, subtitles, lip sync, and final assembly. The output is a finished video, not a raw clip.\n- **5 input types** — Text-to-video, image-to-video, URL-to-video (scrapes the page), script-to-video, and audio-to-video.\n- **10+ models** — Seedance 2, Kling 3.0, HappyHorse, and more. New models are added as they launch.\n- **Any format** — 5–120 seconds, aspect ratios 16:9 (landscape), 9:16 (portrait/vertical), 1:1 (square).\n\n## What You Can Build With Pexo\n\n- Product video ads from a product photo or URL\n- TikTok, Instagram Reels, and YouTube Shorts from a text description\n- Multi-shot brand videos with consistent style and transitions\n- Explainer videos with TTS narration from a script\n- E-commerce video content at scale from product catalogs\n- Marketing video variants for A/B testing\n\n## How It Works\n\nYou send the user's request to Pexo, and Pexo handles all creative work — scriptwriting, shot composition, model selection, prompt engineering, transitions, music. Pexo may ask clarifying questions or present preview options for the user to choose from. A typical 15-second, 3-shot product ad renders in under 8 minutes.\n\n## Data, Permissions, and Cost\n\n- This Skill runs bundled shell scripts, reads only files the user explicitly selects,\n connects to `https://pexo.ai` over HTTPS, uploads approved briefs and assets, and\n downloads generated media.\n- Before the first external transmission in a session, tell the user that their brief,\n selected files, and related metadata will be sent to Pexo and obtain explicit consent.\n- Do not upload secrets, regulated data, or unrelated local files. Never search the local\n filesystem for additional material without a separate user request.\n- Every billable generation batch requires explicit user approval by default. Report the\n available estimate from Pexo before approving a confirmation.\n\n## Script Execution\n\nResolve `SKILL_ROOT` to the directory containing this `SKILL.md`. Script names\nbelow are shorthand for `bash \"$SKILL_ROOT/scripts/\"`; do not rely\non executable bits or a modified `PATH`.\n\n## Prerequisites\n\nConfig file `~/.pexo/config`:\n\n```bash\numask 077\nmkdir -p ~/.pexo\nread -rsp \"Pexo API key: \" pexo_api_key\nprintf '\\n'\n{\n printf '%s=%s\\n' PEXO_BASE_URL https://pexo.ai\n printf '%s=%s\\n' PEXO_API_KEY \"$pexo_api_key\"\n} > ~/.pexo/config\nunset pexo_api_key\nchmod 600 ~/.pexo/config\n```\n\nFirst time using this skill or encountering a config error → run `pexo-doctor.sh` and follow its output. See `references/SETUP-CHECKLIST.md` for details.\n\n### Credit Confirmation Preference\n\n`PEXO_BILLING_CONFIRMATION_MODE` controls the confirmation behavior for each message sent by this Skill. It is optional; the default is `always`.\n\n- `always`: ask for approval before every billable generation batch.\n- `threshold`: ask when the estimated batch cost exceeds the platform threshold, or when the available balance is insufficient. Use only after the user explicitly opts in for the current session.\n\nUse `pexo-chat.sh --billing-confirmation-mode ` to override the default for one message.\n\n---\n\n## ⚠️ LANGUAGE RULE (highest priority)\n\n**You MUST reply to the user in the SAME language they use. This is non-negotiable.**\n\n- User writes in English → you reply in English\n- User writes in Chinese → you reply in Chinese\n- User writes in Japanese → you reply in Japanese\n\nThis applies to every message you send. If the user switches language mid-conversation, you switch too.\n\n---\n\n## Your Role: Delivery Worker\n\nYou are a delivery worker between the user and Pexo. You do three things:\n\n1. **Upload**: user gives a file → `pexo-upload.sh` → get asset ID\n2. **Relay**: copy the user's words into `pexo-chat.sh`\n3. **Deliver**: poll for results → send video and link to user\n\nPexo's backend is a professional video creation agent. It understands cinematography, pacing, storytelling, and prompt engineering far better than you. When you add your own creative ideas, the video quality goes down.\n\n### How to relay messages — copy-paste template\n\nWhen calling pexo-chat.sh, copy the user's message exactly:\n\n```\npexo-chat.sh \"{user's message, copied exactly}\"\n```\n\nExample — user said \"做个猫的视频\":\n```\npexo-chat.sh proj_123 \"做个猫的视频\"\n```\n\nExample — user said \"I want a product video for my shoes\" and uploaded shoes.jpg:\n```\nasset_id=$(pexo-upload.sh proj_123 shoes.jpg)\npexo-chat.sh proj_123 \"I want a product video for my shoes ${asset_id}\"\n```\n\nYour only addition to the user's message is asset tags for uploaded files. Everything else stays exactly as the user wrote it.\n\n### When the user's request is vague\n\nPass it to Pexo exactly as-is. Pexo will ask the user for any missing details. Your job is to relay those questions back to the user and wait for their answer.\n\n### Why this matters\n\nPexo's backend agent specializes in video production. It knows which parameters to ask about, which models to use, and how to write effective prompts. When you add duration, aspect ratio, style descriptions, or any other details the user didn't mention, you override Pexo's professional judgment with guesses. This produces worse videos.\n\n---\n\n## First-Time Setup Message\n\nAfter Pexo is configured for the first time, send the user this message (in the user's language):\n\n> ✅ Pexo is ready!\n> 📖 Guide: https://pexo.ai/connect/openclaw\n> Tell me what video you'd like to make.\n\n---\n\n## Step-by-Step Workflow\n\nFollow these steps in order.\n\n### Making a New Video\n\n```\nStep 1. Create project.\n Run: pexo-project-create.sh \"brief description\"\n If the command succeeds: save the returned project_id.\n If the command fails and stderr contains \"Credits balance\"\n or \"credits\" or \"Insufficient credits\":\n → Go to Credit Error Handling below.\n If the command fails for other reasons:\n → Tell the user what went wrong and offer to retry.\n\nStep 2. Upload files (if user provided any images/videos/audio).\n Run: pexo-upload.sh \n Save the returned asset_id.\n Wrap in tag: asset_id\n (or / for other file types)\n\nStep 3. Send user's message to Pexo.\n Run: pexo-chat.sh \"{user's exact words} asset_id\"\n Copy the user's words exactly. Only add asset tags for uploaded files.\n If the command fails and stderr contains \"Credits balance\"\n or \"credits\" or \"Insufficient credits\":\n → Go to Credit Error Handling below.\n If the command fails for other reasons:\n → Tell the user what went wrong and offer to retry.\n\nStep 4. Notify the user (in the user's language).\n Your message must contain these three items:\n - Confirmation that the request is submitted to Pexo\n - Estimated time: 15–20 minutes for a short video\n - Project link: https://pexo.ai/project/{project_id}\n\nStep 5. Poll for status.\n Run: sleep 60\n Run: pexo-project-get.sh \n Read the nextAction field from the returned JSON.\n Continue to Step 6.\n\nStep 6. Act on nextAction:\n\n \"WAIT\" →\n Go back to Step 5. Keep repeating.\n Every 5 polls (~5 minutes), send user a brief update with\n the project link: https://pexo.ai/project/{project_id}\n\n \"CONFIRM\" →\n Read the confirmation object. It contains confirmation_id, estimated_credits,\n available_credits, sufficient, and the pending tool batch.\n\n If sufficient is false:\n Tell the user that the available credits cannot cover this request.\n Go to Credit Error Handling below. Do not run pexo-billing-confirm.sh.\n\n If sufficient is true:\n Tell the user the estimated credit cost and ask for explicit approval.\n Do not approve on the user's behalf.\n\n After explicit approval:\n Run: pexo-billing-confirm.sh \n Go back to Step 5.\n\n If the user changes the request instead:\n Run: pexo-chat.sh \"{user's exact revised request}\"\n This cancels the pending confirmation before submitting the new message.\n Go back to Step 5.\n\n \"RESPOND\" →\n Read the recentMessages array. Handle every event:\n\n Event \"message\" (Pexo sent text):\n Relay Pexo's text to the user in full.\n If Pexo asked a question, wait for the user's answer.\n Then run: pexo-chat.sh \"{user's exact answer}\"\n Go back to Step 5.\n\n Event \"preview_video\" (Pexo sent preview options):\n For each assetId in assetIds:\n Run: pexo-asset-get.sh \n Copy the \"url\" field from the returned JSON.\n Show all preview URLs to the user with labels (A, B, C...).\n Ask the user to pick one.\n After user picks:\n Run: pexo-chat.sh \"{user's choice}\" --choice \n Go back to Step 5.\n\n Event \"document\":\n Mention the document to the user.\n\n Event \"attachment\":\n Fetch each assetId with pexo-asset-get.sh and deliver the resulting file or URL.\n\n \"DELIVER\" →\n Go to Step 7.\n\n \"FAILED\" →\n Go to Step 8.\n\n \"RECONNECT\" →\n Run: pexo-chat.sh \"continue\"\n Tell the user the connection was interrupted and you are reconnecting.\n Go back to Step 5.\n\nStep 7. Deliver the final video.\n\n 7a. Relay any message events in recentMessages, then find the final_video\n event and get its assetId.\n\n 7b. Run: pexo-asset-get.sh \n\n 7c. Show the downloaded video file to the user.\n\n 7d. Also send the user a message (in their language) with:\n - The video download URL (copy the \"url\" field from the JSON output).\n Send the FULL URL as plain text, including all query parameters.\n Example:\n https://pexo-assets.oss-us-east-1.aliyuncs.com/projects%2F123%2Fassets%2Fvideo.mp4?OSSAccessKeyId=xxx&Expires=xxx&Signature=xxx\n - Project page: https://pexo.ai/project/{project_id}\n - Ask if satisfied or want revisions.\n\n Common delivery mistakes to avoid:\n ✗ Truncated URL (missing ?OSSAccessKeyId=...&Signature=...) → 403 Forbidden\n ✗ Markdown wrapped [text](url) → URL breaks on some platforms\n\nStep 8. Handle failure.\n\n 8a. Read failureReason, nextActionHint, and recentMessages from the JSON.\n 8b. If failureReason is \"INSUFFICIENT_CREDITS\":\n Tell the user prominently that production stopped because the account\n has insufficient credits.\n Go to Credit Error Handling below. Do not offer or attempt a retry\n until the user confirms that credits have been added.\n Otherwise, if stderr from the failed command contains \"Credits balance\",\n \"credits\", or \"Insufficient credits\":\n Go to Credit Error Handling below.\n Otherwise, send the user a message (in their language) with:\n - What went wrong (explain nextActionHint in simple terms)\n - Project page: https://pexo.ai/project/{project_id}\n - Offer to retry.\n\nStep 9. Timeout.\n\n If you have been in the Step 5 loop for more than 30 minutes\n and nextAction is still \"WAIT\":\n\n Send the user a message (in their language) with:\n - The video is taking longer than expected.\n - Project page: https://pexo.ai/project/{project_id}\n - Help guide: https://pexo.ai/connect/openclaw\n - Ask whether to keep waiting or start over.\n Stop polling. Wait for user instructions.\n```\n\n### Credit Error Handling\n\nUse this flow when `pexo-project-get.sh` returns\n`failureReason: \"INSUFFICIENT_CREDITS\"`, or when a command fails and stderr\ncontains credit-related information (look for: \"Credits balance\", \"credits\",\nor \"Insufficient credits\"):\n\n```\nStep A. If stderr contains a purchase link and instructions, send them\n to the user (in their language).\n\nStep B. If stderr only contains the error message without a purchase link,\n send the user a message (in their language) with:\n - Their credits are insufficient.\n - To add credits: visit https://pexo.ai/home?billing=credits\n and complete the purchase flow.\n\nStep C. After the user confirms they have added credits, retry the failed step.\n```\n\n### Revising an Existing Video\n\n```\nStep 1. Use the same project_id.\nStep 2. Run: pexo-chat.sh \"{user's exact feedback}\"\nStep 3. Go to Step 5 of the main workflow (start polling).\n```\n\n---\n\n## Asset Upload\n\nPexo cannot crawl web URLs. If the user provides a link to a file, download it first, then upload.\n\nUpload and reference workflow:\n```bash\n# Upload the file\nasset_id=$(pexo-upload.sh photo.jpg)\n\n# Reference the asset in your message to Pexo\npexo-chat.sh \"Here is the product photo ${asset_id}, please use it as reference\"\n```\n\nTag formats:\n```\nasset-id\nasset-id\nasset-id\n```\n\nTags are mandatory. Bare asset IDs in pexo-chat.sh messages are ignored by Pexo.\n\n---\n\n## Important Rules\n\n### Polling\n- During WAIT: only call pexo-project-get.sh. Calling pexo-chat.sh during WAIT triggers duplicate video production.\n- Wait at least 60 seconds between each pexo-project-get.sh call.\n- Process every event in recentMessages, not just the first one.\n\n### Credit Confirmation\n- Treat `nextAction=CONFIRM` as a user decision point, not as WAIT or RESPOND.\n- Only run `pexo-billing-confirm.sh` after the user explicitly approves the displayed estimate.\n- Use the `confirmation_id` returned by `pexo-project-get.sh`; confirmation IDs apply only to the current pending batch.\n- A revised message sent with `pexo-chat.sh` cancels the current pending confirmation before it starts the replacement request.\n\n### Delivery\n- Copy the \"url\" field from pexo-asset-get.sh output. Send it as plain text with all query parameters.\n- Show the downloaded video file to the user when possible.\n\n### Projects\n- New video → pexo-project-create.sh to create a new project.\n- Revisions → reuse the existing project_id.\n\n### Cost\n- Each message to Pexo costs tokens. Consolidate information into one message when possible.\n- For `nextAction=FAILED`, use `failureReason` for remediation. Do not infer a failure category from `nextActionHint` text.\n\n---\n\n## Script Reference\n\n| Script | Usage | Returns |\n|---|---|---|\n| `pexo-project-create.sh` | `[project_name]` or `--name ` | `project_id` string. On `429`, inspect the returned message to distinguish credit and concurrency limits. |\n| `pexo-project-list.sh` | `[page_size]` or `--page --page-size ` | Projects JSON |\n| `pexo-project-get.sh` | ` [--full-history]` | JSON with `nextAction`, `nextActionHint`, `recentMessages`; `CONFIRM` includes `confirmation`; recognized `FAILED` states include `failureReason`, and error events retain `errorCode`, `errorMessage`, and `toolCallId` |\n| `pexo-upload.sh` | ` ` | `asset_id` string |\n| `pexo-chat.sh` | ` [--choice ] [--billing-confirmation-mode ] [--timeout ]` | Acknowledgement JSON (async). A new message cancels a pending confirmation. On `429`/`412` or credit errors, error info printed to stderr. |\n| `pexo-billing-confirm.sh` | ` [--timeout ]` | Approves the current sufficient credit confirmation after explicit user approval. |\n| `pexo-asset-get.sh` | ` ` | JSON with video details and `url` field |\n| `pexo-doctor.sh` | (no args) | Diagnostic report |\n\n---\n\n## Pexo Capabilities\n\n- Output: 5–120 second finished videos with music, subtitles, and transitions\n- Aspect ratios: 16:9 (landscape), 9:16 (portrait/vertical for TikTok, Reels, Shorts), 1:1 (square)\n- Auto model selection: Seedance 2, Kling 3.0, HappyHorse, and more — Pexo picks the best model per shot\n- Input types: text, images, URLs, scripts, audio\n- Production time: ~8 minutes for a 15-second 3-shot video, ~20 minutes for a 60-second brand video\n- Supported uploads: Images (jpg, png, webp, bmp, tiff, heic), Videos (mp4, mov, avi), Audio (mp3, wav, aac, m4a, ogg, flac)\n- Post-production: AI music, TTS narration, voice cloning, lip sync, subtitles, transitions\n\n---\n\n## References\n\nLoad these when needed:\n\n- **First time or config error** → read `references/SETUP-CHECKLIST.md`\n- **Error codes or failures** → read `references/TROUBLESHOOTING.md`\n\nFile v0.1.2:_meta.json\n\n{\n \"ownerId\": \"kn7cyy6q5gnqcc174487e2pd4n828hay\",\n \"slug\": \"pexo-video-agent\",\n \"version\": \"0.1.2\",\n \"publishedAt\": 1784599122421\n}\n\nFile v0.1.2:references/SETUP-CHECKLIST.md\n\n# Setup Checklist\n\nThis guide covers first-time setup and environment diagnostics for the Pexo agent skill.\n\nRun bundled scripts through Bash from the skill directory, for example\n`bash scripts/pexo-doctor.sh`; installed files may not retain executable bits.\n\n## Quick Start\n\n### 1. Create config file\n\n```bash\numask 077\nmkdir -p ~/.pexo\nread -rsp \"Pexo API key: \" pexo_api_key\nprintf '\\n'\n{\n printf '%s=%s\\n' PEXO_BASE_URL https://pexo.ai\n printf '%s=%s\\n' PEXO_API_KEY \"$pexo_api_key\"\n} > ~/.pexo/config\nunset pexo_api_key\nchmod 600 ~/.pexo/config\n```\n\nGet your API key at: https://pexo.ai\n\n- If you do not have an account:\n Go to https://pexo.ai and sign up. During registration, you will be asked for an invite code.\n Use invite code: **BV5N38**\n New users receive bonus credits upon registration — enough to try out video generation right away.\n- If you are already logged in:\n click the top-right avatar → `API Keys` → `Create Key`, then copy the new key.\n\n### 2. Run diagnostics\n\n```bash\nbash scripts/pexo-doctor.sh\n```\n\nThis checks:\n- Config file exists and is readable\n- `PEXO_BASE_URL` and `PEXO_API_KEY` are set\n- `curl`, `jq`, and `file` are installed\n- Network connectivity to Pexo servers\n- API key is valid (attempts to list projects)\n\nFix any issues reported before using other scripts.\n\n### 3. Verify\n\n```bash\nbash scripts/pexo-project-list.sh\n```\n\nIf this returns a JSON list (even if empty), setup is complete.\n\n## Troubleshooting Setup Issues\n\n### \"Set PEXO_BASE_URL in ~/.pexo/config or \n\nArchive v0.1.1: 15 files, 33818 bytes\n\nFiles: agents/openai.yaml (201b), references/SETUP-CHECKLIST.md (3048b), references/TROUBLESHOOTING.md (13473b), scripts/_common.sh (13098b), scripts/pexo-asset-get.sh (2403b), scripts/pexo-billing-confirm.sh (2949b), scripts/pexo-chat.sh (5538b), scripts/pexo-doctor.sh (6409b), scripts/pexo-project-create.sh (1679b), scripts/pexo-project-get.sh (11750b), scripts/pexo-project-list.sh (1693b), scripts/pexo-upload.sh (3209b), skill-card.md (2695b), SKILL.md (17599b), _meta.json (135b)\n\nArchive v0.3.12: 15 files, 33957 bytes\n\nFiles: agents/openai.yaml (201b), references/SETUP-CHECKLIST.md (3048b), references/TROUBLESHOOTING.md (13473b), scripts/_common.sh (13098b), scripts/pexo-asset-get.sh (2403b), scripts/pexo-billing-confirm.sh (2949b), scripts/pexo-chat.sh (5538b), scripts/pexo-doctor.sh (6409b), scripts/pexo-project-create.sh (1679b), scripts/pexo-project-get.sh (11750b), scripts/pexo-project-list.sh (1693b), scripts/pexo-upload.sh (3209b), skill-card.md (2985b), SKILL.md (17600b), _meta.json (136b)\n\nArchive v0.1.0: 14 files, 25819 bytes\n\nFiles: references/SETUP-CHECKLIST.md (2504b), references/TROUBLESHOOTING.md (12286b), scripts/_common.sh (11430b), scripts/pexo-asset-get.sh (2340b), scripts/pexo-chat.sh (4558b), scripts/pexo-doctor.sh (5514b), scripts/pexo-entitlements.sh (1604b), scripts/pexo-project-create.sh (1806b), scripts/pexo-project-get.sh (7083b), scripts/pexo-project-list.sh (1670b), scripts/pexo-upload.sh (3175b), skill-card.md (2486b), SKILL.md (5308b), _meta.json (135b)","readmeExcerpt":"Skill: Pexo Video Agent Owner: pexo Summary: Create finished multi-shot AI videos Tags: latest:0.3.16 Version history: v0.3.16 | 2026-08-20T07:47:07.704Z | user Add watermark-controlled downloads, harden diagnostics, and improve attachment delivery. v0.1.4 | 2026-07-21T02:16:08.702Z | user Declare runtime requirements and require an explicit user-approval marker before any billing confirmation request. v0.1.3 | 2026-","codeSnippets":[],"executableExamples":[{"language":"bash","snippet":"umask 077\nmkdir -p ~/.pexo\nread -rsp \"Pexo API key: \" pexo_api_key\nprintf '\\n'\n{\n printf '%s=%s\\n' PEXO_API_KEY \"$pexo_api_key\"\n} > ~/.pexo/config\nunset pexo_api_key\nchmod 600 ~/.pexo/config"},{"language":"text","snippet":"pexo-chat.sh \"{user's message, copied exactly}\""},{"language":"text","snippet":"pexo-chat.sh proj_123 \"做个猫的视频\""},{"language":"text","snippet":"asset_id=$(pexo-upload.sh proj_123 shoes.jpg)\npexo-chat.sh proj_123 \"I want a product video for my shoes ${asset_id}\""},{"language":"text","snippet":"Step 1. Create project.\n Run: pexo-project-create.sh \"brief description\"\n If the command succeeds: save the returned project_id.\n If the command fails and stderr contains \"Credits balance\"\n or \"credits\" or \"Insufficient credits\":\n → Go to Credit Error Handling below.\n If the command fails for other reasons:\n → Tell the user what went wrong and offer to retry.\n\nStep 2. Upload files (if user provided any images/videos/audio).\n Run: pexo-upload.sh \n Save the returned asset_id.\n Wrap in tag: asset_id\n (or / for other file types)\n\nStep 3. Send user's message to Pexo.\n Run: pexo-chat.sh \"{user's exact words} asset_id\"\n Copy the user's words exactly. Only add asset tags for uploaded files.\n If the command fails and stderr contains \"Credits balance\"\n or \"credits\" or \"Insufficient credits\":\n → Go to Credit Error Handling below.\n If the command fails for other reasons:\n → Tell the user what went wrong and offer to retry.\n\nStep 4. Notify the user (in the user's language).\n Your message must contain these three items:\n - Confirmation that the request is submitted to Pexo\n - Estimated time: 15–20 minutes for a short video\n - Project link: https://pexo.ai/project/{project_id}\n\nStep 5. Poll for status.\n Run: sleep 60\n Run: pexo-project-get.sh \n Read the nextAction field from the returned JSON.\n Continue to Step 6.\n\nStep 6. Act on nextAction:\n\n \"WAIT\" →\n Go back to Step 5. Keep repeating.\n Every 5 polls (~5 minutes), send user a brief update with\n the project link: https://pexo.ai/project/{project_id}\n\n \"CONFIRM\" →\n Read the confirmation object. It contains confirmation_id, estimated_credits,\n "},{"language":"text","snippet":"Step A. If stderr contains a purchase link and instructions, send them\n to the user (in their language).\n\nStep B. If stderr only contains the error message without a purchase link,\n send the user a message (in their language) with:\n - Their credits are insufficient.\n - To add credits: visit https://pexo.ai/home?billing=credits\n and complete the purchase flow.\n\nStep C. After the user confirms they have added credits, retry the failed step."}],"parameters":null,"dependencies":[],"permissions":[],"extractedFiles":[{"path":"SKILL.md","content":"---\nname: pexo-agent\ndescription: >\n AI video generation skill with auto model selection across Seedance 2,\n Kling 3.0, HappyHorse, and 10+ models. Produces finished multi-shot videos\n (5–120s) from text, images, URLs, scripts, or audio — including AI music,\n lip sync, and multi-shot sequencing. Calls Pexo's external API, manages\n project status and billing confirmations, and transfers only user-approved\n briefs and assets. Runs setup diagnostics, stores generated downloads locally,\n and requires shell, outbound HTTPS, and local file access. Authenticated\n requests are locked to https://pexo.ai. No prompts to write, no models to choose.\n USE FOR: video production, AI video, make a video, product video,\n brand video, promotional clip, explainer video, short video,\n TikTok video, Instagram Reel, YouTube Short, product ad,\n text-to-video, image-to-video, video generation, AI video agent.\nlicense: MIT-0\nmetadata:\n author: pexoai\n version: \"0.3.16\"\n openclaw:\n requires:\n env:\n - PEXO_API_KEY\n bins:\n - bash\n - curl\n - jq\n - file\n primaryEnv: PEXO_API_KEY\n---\n\n# Pexo Agent — AI Video Generation Skill\n\nPexo is the most complete video generation skill for Claude Code and other AI coding agents. It handles the full production pipeline — from a natural-language description to a finished, publish-ready video with music, subtitles, and transitions. Auto model selection routes each shot to the best available model (Seedance 2, Kling 3.0, HappyHorse, and more). One API key, no prompt engineering, no video editing.\n\n## What Pexo Does\n\n- **Auto model selection** — Pexo picks the best video model for each shot based on content type. You do not need to know which model to use.\n- **Full pipeline** — Script, storyboard, shot-by-shot generation, music, subtitles, lip sync, and final assembly. The output is a finished video, not a raw clip.\n- **5 input types** — Text-to-video, image-to-video, URL-to-video (scrapes the page), script-to-video, and audio-to-video.\n- **10+ models** — Seedance 2, Kling 3.0, HappyHorse, and more. New models are added as they launch.\n- **Any format** — 5–120 seconds, aspect ratios 16:9 (landscape), 9:16 (portrait/vertical), 1:1 (square).\n\n## What You Can Build With Pexo\n\n- Product video ads from a product photo or URL\n- TikTok, Instagram Reels, and YouTube Shorts from a text description\n- Multi-shot brand videos with consistent style and transitions\n- Explainer videos with TTS narration from a script\n- E-commerce video content at scale from product catalogs\n- Marketing video variants for A/B testing\n\n## How It Works\n\nYou send the user's request to Pexo, and Pexo handles all creative work — scriptwriting, shot composition, model selection, prompt engineering, transitions, music. Pexo may ask clarifying questions or present preview options for the user to choose from. A typical 15-second, 3-shot product ad renders in under 8 minutes.\n\n## Data, Permissions, and Cost\n\n- This Skill "},{"path":"_meta.json","content":"{\n \"ownerId\": \"kn7cyy6q5gnqcc174487e2pd4n828hay\",\n \"slug\": \"pexo-video-agent\",\n \"version\": \"0.3.16\",\n \"publishedAt\": 1787212027704\n}"},{"path":"references/SETUP-CHECKLIST.md","content":"# Setup Checklist\n\nThis guide covers first-time setup and environment diagnostics for the Pexo agent skill.\n\nRun bundled scripts through Bash from the skill directory, for example\n`bash scripts/pexo-doctor.sh`; installed files may not retain executable bits.\n\n## Quick Start\n\n### 1. Create config file\n\n```bash\numask 077\nmkdir -p ~/.pexo\nread -rsp \"Pexo API key: \" pexo_api_key\nprintf '\\n'\n{\n printf '%s=%s\\n' PEXO_API_KEY \"$pexo_api_key\"\n} > ~/.pexo/config\nunset pexo_api_key\nchmod 600 ~/.pexo/config\n```\n\nGet your API key at: https://pexo.ai\n\n- If you do not have an account:\n Go to https://pexo.ai and sign up. During registration, you will be asked for an invite code.\n Use invite code: **BV5N38**\n New users receive bonus credits upon registration — enough to try out video generation right away.\n- If you are already logged in:\n click the top-right avatar → `API Keys` → `Create Key`, then copy the new key.\n\n### 2. Run diagnostics\n\nThe next command makes outbound HTTPS requests only to `https://pexo.ai`. It performs\nan unauthenticated connectivity check and, when an API key is configured, an authenticated\nproject-list request to validate access. Pexo may log these requests; they do not start a\ngeneration or consume generation credits. Run it only after the user approves this check.\n\n```bash\nbash scripts/pexo-doctor.sh\n```\n\nThis checks:\n- Config file exists and is readable\n- `PEXO_BASE_URL` and `PEXO_API_KEY` are set\n- `curl`, `jq`, and `file` are installed\n- Network connectivity to Pexo servers\n- API key is valid (attempts to list projects)\n\nFix any issues reported before using other scripts.\n\n### 3. Verify\n\nThe next command sends an authenticated project-list request to `https://pexo.ai` and may\nappear in Pexo service logs. It does not create a project or consume generation credits.\n\n```bash\nbash scripts/pexo-project-list.sh\n```\n\nIf this returns a JSON list (even if empty), setup is complete.\n\n## Troubleshooting Setup Issues\n\n### \"PEXO_BASE_URL must be exactly https://pexo.ai\"\n\nAuthenticated requests are restricted to the production Pexo origin. Remove any custom base\nURL override, or set it to exactly `https://pexo.ai`.\n\n### \"Set PEXO_API_KEY in ~/.pexo/config or env\"\n\nSame as above — the API key line is missing from the config file.\n\n### API key invalid (401 Unauthenticated)\n\nYour API key may be expired or incorrect. Log in at https://pexo.ai to generate a new one. Replace the value in `~/.pexo/config`.\n\n### curl, jq, or file not found\n\nInstall the missing dependency:\n\n```bash\n# macOS (file is usually preinstalled)\nbrew install curl jq\n\n# Ubuntu/Debian\napt-get install -y curl jq file\n\n# CentOS/RHEL\nyum install -y curl jq file\n```\n\n### Network connectivity failure\n\nIf `pexo-doctor.sh` reports a connectivity issue:\n- Check if your server can reach `pexo.ai` (e.g. `curl -I https://pexo.ai`)\n- Check firewall rules for outbound HTTPS (port 443)\n- If behind a proxy, configure `http_proxy`/`https_proxy` environment variables\n\n## Environment Variables\n\n"},{"path":"references/TROUBLESHOOTING.md","content":"# Troubleshooting\n\n## Script Exit Behavior\n\n- Exit `0`: success\n- Exit `1`: request/transport/backend failure\n- Exit `2`: local usage error (missing args, invalid flags, invalid local input)\n\nOn request failure, scripts print compact JSON to `stderr`, for example:\n\n```json\n{\"ok\":false,\"httpCode\":429,\"message\":\"Daily creation limit reached. Contact support email for more access.\"}\n```\n\nFields you may see:\n\n- `httpCode`: the real HTTP status code returned to the script\n- `error`: auth/proxy error code such as `INVALID_API_KEY` or `INTERNAL_ERROR`\n- `message`: the most useful user-facing message extracted from the response\n- `details`: extra backend detail when available\n\n## Auth And Proxy Errors\n\nThese can happen on every script that makes API calls:\n\n| HTTP | `error` | Meaning | What to do |\n|---|---|---|---|\n| 401 | `INVALID_API_KEY` | API key is invalid or revoked | Update `PEXO_API_KEY` in `~/.pexo/config`. Get a new key at pexo.ai. |\n| 401 | `MISSING_TOKEN` | The request was sent without an API key | Run `pexo-doctor.sh` to verify config. Make sure `~/.pexo/config` is sourced correctly. |\n| 401 | `INTERNAL_ERROR` | The service failed to process the request before authentication completed | This is a temporary service issue, not a problem with the API key. Wait a moment and retry; if it persists, contact support. |\n| 409 | `SESSION_REPLACED` | This API key's session was invalidated by a new login elsewhere | Unusual for API-key usage. Retry the command. If it keeps happening, regenerate the API key at pexo.ai. |\n\nIf the message says `Invalid API key`, it is an auth problem.\nIf the body says `error=INTERNAL_ERROR`, do not tell the user to rotate the key first; the service may simply be temporarily down.\n\n## Script-Specific Errors\n\n### `pexo-project-create.sh`\n\nReal statuses:\n\n- `400`: project name is too long. Ask the user to use a shorter name and retry.\n- `401`: auth failure — see Auth and Proxy Errors above.\n- `429`: creation limit reached — could be any of:\n - User already has an active project running (must wait for it to finish)\n - Insufficient credits to start a new project\n Read the error `message` to distinguish these cases. The script does not query the balance automatically.\n- `500`: an unexpected server error occurred. Retry in a moment; if the problem persists, contact support at pexo.ai.\n\nNotes:\n\n- If no project name is provided, the script defaults to `\"Untitled\"`.\n\n### `pexo-project-list.sh`\n\nReal statuses:\n\n- `401`: auth failure — see Auth and Proxy Errors above.\n- `500`: an unexpected server error occurred. Retry in a moment; if the problem persists, contact support at pexo.ai.\n\nNotes:\n\n- Invalid `page` / `page_size` values are handled locally by the script before request time.\n- Backend page size is effectively capped at `100`.\n\n### `pexo-project-get.sh`\n\nReal statuses from the first project fetch:\n\n- `401`: auth failure — see Auth and Proxy Errors above.\n- `404`: the project does not exist or has been deleted. Verify the p"},{"path":"skill-card.md","content":"## Description:\n\nPexo Video Agent helps agents create finished multi-shot AI videos from text, images, URLs, scripts, or audio through Pexo's external video generation service.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[pexo](https://clawhub.ai/user/pexo)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nExternal users and developers use this skill to submit approved briefs and media assets to Pexo, manage video-generation projects, confirm billable batches, and retrieve generated video outputs.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: Selected media files, briefs, related metadata, and generated asset links are handled by Pexo's external service.\n\nMitigation: Use the skill only with files the user intentionally selects, avoid secrets or regulated data, and obtain explicit consent before transmitting briefs or assets.\n\nRisk: Remote service messages, billing links, and signed asset URLs may be relayed back to the user.\n\nMitigation: Treat returned content as external Pexo-provided content, review links before acting on them, and avoid treating service responses as trusted local instructions.\n\nRisk: The skill requires a PEXO_API_KEY and outbound HTTPS access.\n\nMitigation: Keep the API key scoped and removable, store it with restricted file permissions, and review before installation on networks with sensitive internal services.\n\n## Reference(s):\n\n- [ClawHub Skill Page](https://clawhub.ai/pexo/skills/pexo-video-agent)\n- [Setup Checklist](references/SETUP-CHECKLIST.md)\n- [Troubleshooting](references/TROUBLESHOOTING.md)\n- [Pexo OpenClaw Guide](https://pexo.ai/connect/openclaw)\n\n## Skill Output:\n\n**Output Type(s):** [Text, Markdown, Shell commands, Configuration, Guidance]\n\n**Output Format:** [Markdown and plain text with inline shell commands and external video links]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [May retrieve generated video files and signed asset URLs from Pexo when the user has approved the request.]\n\n## Skill Version(s):\n\n0.3.16 (source: server release metadata and skill frontmatter)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment."}],"languages":[],"docsSourceLabel":"CLAWHUB","editorialOverview":null,"editorialQuality":{"score":100,"threshold":65,"status":"thin","wordCount":2076,"uniquenessScore":41,"reasons":["uniqueness-below-45"]}},"media":{"evidence":{"source":"no-media","verified":false,"confidence":"low","updatedAt":"2026-10-10T21:40:56.140Z","emptyReason":"No screenshots, media assets, or demo links are available."},"primaryImageUrl":null,"mediaAssetCount":0,"assets":[],"demoUrl":null},"ownerResources":{"evidence":{"source":"unclaimed","verified":false,"confidence":"low","updatedAt":"2026-10-10T21:40:56.140Z","emptyReason":"This page has not been claimed by the agent owner."},"hasCustomPage":false,"customPageUpdatedAt":null,"customLinks":[],"structuredLinks":{"docsUrl":null,"demoUrl":null,"supportUrl":null,"pricingUrl":null,"statusUrl":null},"customPage":null},"relatedAgents":{"evidence":{"source":"protocol-neighbors","verified":false,"confidence":"medium","updatedAt":"2026-10-10T23:46:31.198Z","emptyReason":null},"items":[{"id":"8ebccd8e-3863-4187-8355-c3f14e1f9edf","entityType":"agent","canonicalPath":"/agent/iofficeai-aionui","slug":"iofficeai-aionui","name":"AionUi","description":"Free, local, open-source 24/7 Cowork app and OpenClaw for Gemini CLI, Claude Code, Codex, OpenCode, Qwen Code, Goose CLI, Auggie, and more | 🌟 Star if you like it!","url":"https://github.com/iOfficeAI/AionUi","homepage":"https://www.aionui.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-10-09T19:11:12.944Z","createdAt":"2026-02-25T03:38:16.584Z","downloads":null},{"id":"b917f68a-ebff-438e-84f8-3f4b2494c0bc","entityType":"agent","canonicalPath":"/agent/activepieces-activepieces","slug":"activepieces-activepieces","name":"activepieces","description":"AI Agents & MCPs & AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows & AI Agents • MCPs for AI Agents","url":"https://github.com/activepieces/activepieces","homepage":"https://www.activepieces.com","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-15T02:22:12.426Z","createdAt":"2026-02-25T03:38:12.412Z","downloads":null},{"id":"5cb26759-3a39-483f-94cf-276a98c13bb8","entityType":"agent","canonicalPath":"/agent/cherryhq-cherry-studio","slug":"cherryhq-cherry-studio","name":"cherry-studio","description":"AI productivity studio with smart chat, autonomous agents, and 300+ assistants. Unified access to frontier LLMs","url":"https://github.com/CherryHQ/cherry-studio","homepage":"https://cherry-ai.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-11T14:38:40.986Z","createdAt":"2026-02-25T03:38:19.379Z","downloads":null},{"id":"6f6582d0-5d76-4f0f-b81d-86520247950b","entityType":"agent","canonicalPath":"/agent/copilotkit-copilotkit","slug":"copilotkit-copilotkit","name":"CopilotKit","description":"The Frontend for Agents & Generative UI. React + Angular","url":"https://github.com/CopilotKit/CopilotKit","homepage":"https://docs.copilotkit.ai","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-03-25T09:50:57.846Z","createdAt":"2026-02-25T03:39:14.617Z","downloads":null}],"links":{"hub":"/agent","source":"/agent/source/clawhub","protocols":[{"label":"OpenClaw","href":"/agent/protocol/openclew"}]}}}