pexoai-agent

pexoai-agent 技能概览

pexoai-agent 是一个以 shell script 为底层的技能，用于把短视频制作任务提交给 Pexo 托管的视频 agent。它最适合这样一类用户：希望由 AI 系统直接接手创意生产闭环——脚本、镜头、转场、音乐、预览选择——而不是自己从头搭一套视频生成流程。它真正解决的任务，不是“生成一段关于视频的文本”，而是“从 prompt 到素材回收，创建并管理一个真实的短视频项目”。

pexoai-agent 实际能做什么

pexoai-agent 技能面向的大致是 5 到 120 秒的视频。它支持常见的短视频类型，比如产品宣传、解说视频、社媒短片、品牌视频和创作者风格内容，画幅比例包括 16:9、9:16 和 1:1。

和普通 prompt 不同，这个技能给 agent 提供的是一条明确的执行路径：

• 创建项目
• 向 Pexo 提交消息
• 可选上传素材
• 轮询项目状态
• 拉取生成后的资产

适合哪些用户

如果你符合以下情况，pexoai-agent 会很匹配：

• 你想要的是 AI 辅助的视频生成，而不只是创意构思
• 你能接受 API key 配置和 shell 工具链
• 你需要一套可重复执行的短视频生产流程
• 你希望 agent 能把用户请求真正转发到生产后端

它尤其适合 pexoai-agent for Video Editing 这类场景：用户要的是一个做好的短视频，或者在现有结果上改稿，而不是时间轴级别的手动编辑控制。

相比普通 prompting 的核心差异

pexoai-agent 最大的优势在于它有明确的操作结构。仓库里已经提供了专门用途的脚本，例如：

• scripts/pexo-project-create.sh
• scripts/pexo-chat.sh
• scripts/pexo-project-get.sh
• scripts/pexo-upload.sh
• scripts/pexo-asset-get.sh
• scripts/pexo-doctor.sh

这意味着，pexoai-agent 不是只给你一套 prompt 写法，而是给出了一条可以安装落地的工作流，包含诊断、后端交互和更清晰的错误处理。

安装 pexoai-agent 前必须了解的限制

pexoai-agent 不是本地视频生成工具。你需要准备：

• 一个 Pexo 账户和 API key
• PEXO_API_KEY
• PEXO_BASE_URL
• 本地 CLI 依赖：curl、jq、file

它还默认你的 agent 环境可以执行 shell script。如果你的运行环境不能执行本地脚本，或者不能在 ~/.pexo/config 下保存配置，那么接入成本会高不少。

尽早了解的主要接入阻碍

决定是否安装 pexoai-agent 时，真正的阻碍通常是工程层面的，而不是概念层面的：

• ~/.pexo/config 缺少配置
• API key 无效或已过期
• shell 依赖不完整
• 误以为 pexo-chat.sh 会直接返回最终成片，而实际上它是异步提交任务
• prompt 里的素材引用写错

这些问题都能处理，但它们比仓库是否“精致”更影响你值不值得花时间安装 pexoai-agent。

如何使用 pexoai-agent 技能

pexoai-agent 的安装上下文

如果你用的是基于 skills 的 agent runtime，可以从 pexoai/pexo-skills 仓库添加这个技能，然后重点查看 skills/pexo-agent 目录下的文件。安装完成后，请把它理解为“shell 辅助的 API 工作流”，而不是纯 prompt 包。

因为这个技能本身并不是围绕一个“一键 bootstrap 脚本”设计的，所以你真正的接入起点是配置和诊断，而不是直接发请求。

先完成必需配置

按脚本预期的位置创建配置文件：

mkdir -p ~/.pexo
cat > ~/.pexo/config << 'EOF'
PEXO_BASE_URL="https://pexo.ai"
PEXO_API_KEY="sk-<your-api-key>"
EOF

这一步是任何 pexoai-agent 安装中最关键的一步。公共脚本层会自动加载这个文件；如果有需要，也可以再用环境变量覆盖其中的值。

首次请求前先跑诊断

在尝试创建项目之前，先运行 doctor 脚本：

pexo-doctor.sh

它会检查：

• 配置文件是否存在
• 必需变量是否齐全
• curl、jq 和 file
• 网络是否可达
• 你的 API key 是否真的能访问 Pexo

如果诊断没通过，先把这些问题修好。相比后面在项目创建或 chat 提交时报错后再排查，这样会快得多。

用一次安全的读取调用验证环境

诊断完成后，再用下面这个命令确认环境是否可用：

pexo-project-list.sh

如果它能返回 JSON，说明你的 pexoai-agent 使用链路大概率已经打通。相比一上来就尝试完整的视频创作请求，这是更稳妥的首轮验证方式。

理解 pexoai-agent 的真实工作流

pexoai-agent 的实际流程是：

1. 创建项目
2. 可选上传源素材
3. 发送生产请求消息
4. 轮询项目状态
5. 拉取最终资产

典型命令流如下：

project_id="$(pexo-project-create.sh "New Product Teaser")"
pexo-chat.sh "$project_id" "Create a 20-second 9:16 product teaser for a skincare serum."
pexo-project-get.sh "$project_id"

如果你的流程里包含用户提供的媒体素材，应先上传素材，再在消息里正确引用返回的 asset ID。

prompt 里素材引用的正确写法

这份 pexoai-agent 指南里一个非常关键的细节是：只写裸的 asset ID 不够。chat 脚本要求使用带标签的引用形式，例如：

• <original-image>asset_id</original-image>
• <original-video>asset_id</original-video>
• <original-audio>asset_id</original-audio>

这一点很重要，因为 pexo-chat.sh 会先在本地做校验；如果格式不对，它会在请求发到后端之前就直接拒绝。

更稳妥的消息可以写成这样：

Create a 15-second vertical ad for this product image <original-image>a_ABC123</original-image>.
Tone: premium but friendly.
Audience: women 25–40.
Include a short hook in the first 2 seconds.
End with a CTA: "Shop now".

什么样的输入更容易产出好视频

pexoai-agent 在你给出“制作导向”的请求时，效果会明显更好，而不是那种模糊的泛泛表述。尽量写清楚：

• 目标
• 时长
• 画幅比例
• 受众
• 平台
• 语气风格
• 核心信息
• 必须包含的视觉内容或素材
• CTA
• 硬性限制

较弱的 prompt：

Make a video for my product.

更强的 prompt：

Create a 30-second 9:16 TikTok-style product video for a portable blender.
Audience: busy students and office workers.
Goal: drive clicks to product page.
Tone: energetic, clean, modern.
Must show portability, USB charging, and smoothie use cases.
Include on-screen text in short phrases.
End with: "Blend anywhere."

后者能大幅减少在节奏、画面组织和转化意图上的猜测空间。

适合 pexoai-agent 的改稿使用方式

更推荐把第一次提交当作“草稿请求”，后续围绕明确改动来迭代，例如：

• 缩短开头
• 强化前几秒的 hook
• 更换音乐情绪
• 突出某一个产品卖点
• 如果有预览选项，明确选择其中一个

从仓库信息来看，Pexo 可能会追问澄清问题，也可能提供预览。因此最合适的 pexoai-agent 工作方式并不是“一条 prompt 一次出完”，而是“提交、检查、选择、细化”。

在仓库里优先阅读哪些文件

如果你想快速搞清 pexoai-agent，建议按这个顺序看：

1. SKILL.md
2. references/SETUP-CHECKLIST.md
3. references/TROUBLESHOOTING.md
4. scripts/pexo-doctor.sh
5. scripts/pexo-chat.sh
6. scripts/pexo-project-create.sh
7. scripts/pexo-project-get.sh
8. scripts/pexo-asset-get.sh

这条阅读路径能让你先掌握安装、常见失败模式，以及完整的请求生命周期，再去看更底层的实现细节。

认识异步提交机制的实际含义

pexoai-agent 使用中一个很常见的误解，是以为 pexo-chat.sh 会直接返回最终视频。实际上不会。它的职责是提交请求、确认 SSE stream 已经建立，然后有意断开连接。

所以你的 agent 应该把它当成一个异步任务系统：

• pexo-chat.sh 负责提交
• pexo-project-get.sh 负责查看进度
• pexo-asset-get.sh 负责获取可下载资产的详情

这一点会直接影响你如何设计自动化流程，以及如何管理用户预期。

真实使用中最值得关注的常见错误

根据仓库里的排障说明，最值得在安装决策阶段关注的错误有：

• 401：API key 无效或认证失败
• 404：项目或资产不存在
• 412：项目 agent 版本不兼容
• 429：触发 rate limit、每日创建次数上限，或项目视频数量上限
• 403：已签名的资产下载 URL 过期

这些脚本还定义了明确的退出行为：

• 0：成功
• 1：请求失败或后端失败
• 2：本地使用错误

如果你准备把 pexoai-agent 包装进更大的自动化系统里，这一点很有价值。

pexoai-agent 技能 FAQ

pexoai-agent 对新手友好吗？

中等偏友好。pexoai-agent 比自己搭建视频后端要容易得多，但又没有纯聊天型技能那么简单。你仍然需要能接受配置文件、shell script，以及异步工作流这些概念。

如果你是 CLI 工具的完全新手，那么前期配置阶段很可能会有一定摩擦。

什么情况下该用 pexoai-agent，而不是普通 LLM prompt？

当你希望 agent 真正去操作一个视频生成服务，并管理项目状态、上传和可下载资产时，就应该用 pexoai-agent。如果你只需要创意策划、分镜思路或脚本建议，而不需要后端执行，那么普通 prompt 就够了。

pexoai-agent 更偏 Video Editing，还是完整视频生成？

它更偏向 AI 视频生成和生产编排，而不是时间轴式的手动编辑。若你的需求是“把这份 brief 直接做成一个短视频”，那它很合适；但如果你要的是传统 NLE 工作流里的逐帧精细编辑控制，那它不是同一类工具。

pexoai-agent 支持用户素材吗？

支持。这个工作流里包含上传和资产获取脚本，chat 路径也支持引用媒体素材。但要注意，引用必须包在预期的 XML-like 标签里，不能直接粘贴原始 ID。

这个技能的主要限制是什么？

pexoai-agent 的主要限制包括：

• 主要面向短视频场景
• 依赖 Pexo 后端和账户访问权限
• 采用异步处理，而不是立刻返回最终结果
• 可能受到配额或 rate limit 限制
• 不适合高度手动化的精细编辑控制

我能在多语言工作流里使用 pexoai-agent 吗？

可以，而且这个技能明确优先用与用户相同的语言回复。如果你的 agent 服务的是多语言用户，这一点在实际使用中非常重要，因为语言一致性在技能里属于硬性指令。

pexoai-agent 刚安装就失败，该先做什么？

先运行：

pexo-doctor.sh

然后检查：

• references/SETUP-CHECKLIST.md
• references/TROUBLESHOOTING.md

大多数前期失败都来自配置、依赖、连通性或 API 认证，而不是创意请求本身有问题。

如何改进 pexoai-agent 技能的使用效果

给 pexoai-agent 提交可直接生产的 brief

想让 pexoai-agent 更快出好结果，最有效的方法就是不要再给泛泛的需求。更好的 brief 通常会包含：

• 精确时长
• 目标平台
• 画幅比例
• 受众
• 信息层级
• 视觉输入
• 用自然语言描述的风格参考
• CTA
• 限制条件

这样既能提升创意质量，也能减少反复澄清的来回沟通。

约束条件要写明，不要默认它会理解

如果某件事真的重要，就直接写出来：

• “No voiceover”
• “Use upbeat background music”
• “Keep text minimal”
• “No medical claims”
• “Prioritize first 3 seconds for hook”
• “Use 9:16 vertical framing”

pexoai-agent 只能执行那些你明确传达的约束，不能替你补全隐含要求。

把改稿 prompt 写成“变更请求”

第一次输出之后，不要只说“再好一点”。更有效的做法是提出可控变更，比如：

• “Keep the same concept, but cut total runtime to 12 seconds”
• “Use a more premium tone and slower transitions”
• “Replace broad lifestyle shots with closer product detail emphasis”

相比笼统表达不满意，这样的第二轮修改会实用得多。

谨慎处理上传和素材引用

pexoai-agent 一个常见失败点就是输入卫生做得不够严格：

• 上传了错误文件
• 引用了错误的 asset ID
• 忘记加 <original-image> 这类包装标签
• 误以为已签名的 asset URL 会永久有效

如果你的工作流依赖外部媒体素材，就要对文件跟踪和消息格式保持足够严格。

围绕异步轮询来设计，而不是期待即时完成

如果你要在 agent 或自动化里更稳定地使用 pexoai-agent，请按“延迟完成”的方式来设计：

• 提交请求
• 保存 project ID
• 用 backoff 方式轮询
• 只在资产准备好后再拉取
• 对用户展示有意义的状态信息

很多用户体验上的挫败，其实都来自把这个系统当同步聊天来用，而不是当作任务队列。

修改脚本前，先看排障文档

如果输出失败，或者行为不稳定，先读：

• references/TROUBLESHOOTING.md
• scripts/_common.sh

公共层已经把认证、请求处理和精简错误输出做了统一封装。很多情况下，你并不需要改脚本，而是需要正确理解现有错误结构。

用预检提升 pexoai-agent 的稳定性

如果你打算重复使用 pexoai-agent，建议养成 preflight 检查习惯：

• 运行 pexo-doctor.sh
• 验证项目列表是否可读
• 确认素材是否可用
• 在用户提交前检查配额或认证是否过期

这能避免很多在真实生产中本来可以提前拦住的失败。

什么时候不该使用 pexoai-agent

在以下情况下，不建议使用 pexoai-agent：

• 你需要离线或纯本地生成
• 你无法安全保存 API 凭据
• 你的环境不能运行 shell script
• 你需要的是深度手动编辑控制，而不是 AI 生成成片
• 你的任务只是创意 brainstorm，而不是执行落地

对这些边界有清晰判断，往往比再多看一份功能清单更能帮助你做出正确的安装决策。