pexoai-agent

pexoai-agent 스킬 개요

pexoai-agent는 shell script를 기반으로 짧은 형식의 영상 작업을 Pexo의 호스팅 비디오 에이전트로 보내는 스킬입니다. 직접 커스텀 영상 파이프라인을 만들지 않고도, AI가 기획부터 제작 루프 전체—스크립트, 샷 구성, 전환, 음악, 프리뷰 선택—를 처리하길 원하는 사용자에게 특히 잘 맞습니다. 이 스킬의 실제 해결 과제는 단순히 “영상에 대한 텍스트를 생성”하는 것이 아니라, “프롬프트 입력부터 결과 에셋 회수까지 실제 숏폼 영상 프로젝트를 생성하고 관리”하는 데 있습니다.

pexoai-agent가 실제로 하는 일

pexoai-agent 스킬은 대략 5초에서 120초 사이의 영상을 대상으로 설계되었습니다. 제품 프로모션, 설명형 영상, 소셜 클립, 브랜드 영상, 크리에이터 스타일 콘텐츠 같은 일반적인 숏폼 포맷을 지원하며, 16:9, 9:16, 1:1 같은 화면비도 다룹니다.

일반적인 프롬프트와 달리, 이 스킬은 에이전트가 따라갈 수 있는 구체적인 실행 경로를 제공합니다:

• 프로젝트 생성
• Pexo에 메시지 제출
• 필요 시 에셋 업로드
• 프로젝트 상태 조회
• 생성된 에셋 가져오기

어떤 사용자에게 pexoai-agent가 잘 맞는가

다음에 해당한다면 pexoai-agent 스킬이 특히 잘 맞습니다:

• 아이디어 발상만이 아니라 AI 기반 영상 생성을 원한다
• API key 설정과 shell 도구 사용이 부담스럽지 않다
• 숏폼 영상 제작을 반복 가능한 워크플로로 운영하고 싶다
• 사용자 요청을 실제 프로덕션 백엔드로 전달하는 에이전트를 원한다

특히 pexoai-agent for Video Editing 유형의 사용 사례와 관련성이 높습니다. 다만 여기서의 핵심은 타임라인 단위의 수동 편집 제어가 아니라, 완성된 숏폼 영상 또는 그 수정본을 얻고자 하는 경우입니다.

일반 프롬프팅 대비 주요 차별점

가장 큰 장점은 운영 구조가 명확하다는 점입니다. 이 repo에는 다음과 같은 목적별 스크립트가 포함되어 있습니다:

• 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 가이드는 단순한 프롬프트 문구 모음이 아닙니다. 설치해서 바로 쓸 수 있는 워크플로, 진단 도구, 백엔드 연동, 보다 명확한 에러 처리까지 함께 제공합니다.

pexoai-agent 설치 전에 꼭 알아야 할 제약

이것은 로컬 영상 생성 도구가 아닙니다. 사용하려면 다음이 필요합니다:

• Pexo 계정과 API key
• PEXO_API_KEY
• PEXO_BASE_URL
• 로컬 CLI 의존성: curl, jq, file

또한 shell script를 실행할 수 있는 에이전트 환경을 전제로 합니다. 현재 환경에서 로컬 스크립트를 실행할 수 없거나 ~/.pexo/config 아래에 설정을 저장할 수 없다면, pexoai-agent 도입 난이도는 올라갑니다.

pexoai-agent 도입 전에 먼저 알아둘 주요 장애 요인

핵심 장애 요인은 개념적인 문제가 아니라 실무적인 문제입니다:

• ~/.pexo/config 설정 누락
• 잘못되었거나 만료된 API key
• shell 의존성 누락
• pexo-chat.sh가 최종 결과를 스트리밍하는 것이 아니라 비동기 작업을 제출한다는 점에 대한 오해
• 프롬프트 안의 잘못된 에셋 참조

이 문제들은 해결 가능하지만, pexoai-agent 설치가 시간을 들일 만한지 판단할 때 repo의 완성도보다 더 중요하게 작용합니다.

pexoai-agent 스킬 사용 방법

pexoai-agent 설치 맥락 이해하기

skills 기반 에이전트 런타임을 사용한다면 pexoai/pexo-skills 저장소에서 해당 스킬을 추가한 뒤 skills/pexo-agent 아래 파일을 기준으로 작업하면 됩니다. 설치 후에는 이것을 단순 프롬프트 팩이 아니라 shell이 보조하는 API 워크플로로 이해하는 것이 좋습니다.

이 스킬은 one-command bootstrap 스크립트 중심 구조가 아니기 때문에, 실제 설정의 출발점은 config와 진단입니다.

먼저 필수 config부터 설정하기

스크립트가 기대하는 정확한 위치에 config 파일을 만들어야 합니다:

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

이 스크립트는 다음을 점검합니다:

• config 파일 존재 여부
• 필수 변수
• curl, jq, file
• 네트워크 연결 가능 여부
• API key가 실제로 Pexo 접근 권한을 갖는지 여부

진단에서 실패했다면, 프로젝트 생성이나 chat 제출 단계에서 뒤늦게 디버깅하는 것보다 여기서 먼저 문제를 해결하는 편이 훨씬 빠릅니다.

안전한 조회 호출로 환경 검증하기

진단 후에는 다음 명령으로 환경을 확인하세요:

pexo-project-list.sh

JSON이 반환된다면 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를 정확히 참조해야 합니다.

pexoai-agent에서 프롬프트의 에셋 참조가 동작하는 방식

이 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
• 강한 제약 조건

약한 프롬프트:

Make a video for my product.

더 강한 프롬프트:

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 수정 작업에 추천되는 사용 패턴

첫 제출은 초안 요청으로 보고, 이후에는 구체적인 변경점 단위로 반복하는 것이 좋습니다:

• 인트로를 더 짧게
• 첫 훅을 더 강하게
• 음악 분위기 변경
• 특정 제품 장점 강조
• 프리뷰 옵션이 있다면 그중 하나 선택

repo를 보면 Pexo가 추가 확인 질문을 하거나 프리뷰를 제안할 수 있음을 시사합니다. 즉, 가장 좋은 워크플로는 “프롬프트 한 번에 끝”이 아니라 “제출 → 확인 → 선택 → 다듬기”입니다.

저장소에서 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의 비동기 제출에서 기대해야 할 것

pexoai-agent 사용에서 흔한 오해 중 하나는 pexo-chat.sh가 완성된 영상을 바로 반환한다고 생각하는 것입니다. 실제로는 그렇지 않습니다. 이 스크립트는 요청을 제출하고 SSE 스트림이 열렸다는 점만 확인한 뒤, 의도적으로 연결을 종료합니다.

따라서 에이전트 쪽에서는 이것을 비동기 작업 시스템으로 다뤄야 합니다:

• pexo-chat.sh는 제출 담당
• pexo-project-get.sh는 진행 상태 확인 담당
• pexo-asset-get.sh는 다운로드 가능한 에셋 정보 회수 담당

이 차이는 자동화 설계와 사용자 기대치를 바꿉니다.

실제 사용에서 중요한 공통 에러

repo의 troubleshooting 노트를 기준으로 보면, 설치 판단과 운영에 특히 중요한 에러는 다음과 같습니다:

• 401: 잘못된 API key 또는 인증 실패
• 404: 프로젝트 또는 에셋 없음
• 412: 호환되지 않는 프로젝트 에이전트 버전
• 429: rate limit, 일일 생성 한도, 또는 프로젝트 영상 한도
• 403: 만료된 signed asset download URL

스크립트의 종료 코드도 의미 있게 설계되어 있습니다:

• 0: 성공
• 1: 요청 또는 백엔드 실패
• 2: 로컬 사용 오류

따라서 pexoai-agent를 더 큰 자동화 흐름에 감쌀 계획이라면 이 동작이 꽤 유용합니다.

pexoai-agent 스킬 FAQ

pexoai-agent는 초보자에게도 쉬운가요?

중간 정도입니다. pexoai-agent 스킬은 직접 영상 백엔드를 구축하는 것보다는 쉽지만, chat-only 스킬처럼 단순하진 않습니다. config 파일, shell script, 비동기 워크플로 개념에 어느 정도 익숙해야 합니다.

CLI 도구가 완전히 처음이라면, 초기 설정에서 약간의 마찰은 예상하는 편이 좋습니다.

일반 LLM 프롬프트 대신 언제 pexoai-agent를 써야 하나요?

프로젝트 상태, 업로드, 다운로드 가능한 에셋을 갖춘 실제 영상 생성 서비스를 에이전트가 조작하길 원할 때는 pexoai-agent를 쓰는 것이 맞습니다. 반대로 백엔드 실행 없이 크리에이티브 기획, 스토리보드, 스크립트 제안만 필요하다면 일반 프롬프트가 더 적합합니다.

pexoai-agent는 Video Editing용인가요, 아니면 전체 영상 생성용인가요?

성격상 타임라인 기반 수동 편집보다는 AI 영상 생성과 제작 오케스트레이션에 더 가깝습니다. 필요가 “이 브리프를 짧은 영상으로 만들어 달라”라면 잘 맞습니다. 반대로 기존 NLE 워크플로 안에서 프레임 단위의 정확한 편집 결정을 원한다면, 이 스킬은 같은 성격의 도구가 아닙니다.

pexoai-agent는 사용자 에셋을 지원하나요?

예. 워크플로에는 업로드 및 에셋 조회 스크립트가 포함되어 있고, chat 경로에서도 참조된 미디어를 지원합니다. 다만 참조는 raw ID를 그대로 붙여 넣는 방식이 아니라, 기대하는 XML 유사 태그로 감싸야 합니다.

이 스킬의 주요 한계는 무엇인가요?

가장 큰 한계는 다음과 같습니다:

• 숏폼 영상 범위에 초점이 맞춰져 있음
• Pexo 백엔드와 계정 접근성에 의존함
• 즉시 최종 결과를 주는 방식이 아니라 비동기 처리임
• quota 또는 rate-limit 제약이 있을 수 있음
• 세밀한 수동 편집 제어에는 덜 적합함

pexoai-agent를 다국어 워크플로에 쓸 수 있나요?

예. 이 스킬은 사용자와 같은 언어로 응답하는 것을 명시적으로 우선합니다. 다국어 사용자를 상대하는 에이전트라면, 언어 일관성이 강한 지시사항으로 들어가 있다는 점에서 운영상 매우 중요합니다.

pexoai-agent 설치 직후 실패하면 무엇부터 해야 하나요?

다음을 실행하세요:

pexo-doctor.sh

그다음 아래 파일을 확인하세요:

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

초기 실패의 대부분은 크리에이티브 요청 자체보다 config, 의존성, 연결성, API 인증 문제에서 발생합니다.

pexoai-agent 스킬을 더 잘 활용하는 방법

pexoai-agent에 바로 제작 가능한 브리프를 주기

결과를 가장 빨리 개선하는 방법은 막연한 요청을 멈추는 것입니다. 더 나은 브리프에는 다음이 포함됩니다:

• 정확한 길이
• 대상 플랫폼
• 화면비
• 타깃 오디언스
• 메시지 우선순위
• 시각적 입력
• 자연어 스타일 레퍼런스
• 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는 명확하게 전달받은 제약만 실제 작업 규칙으로 반영할 수 있습니다.

수정 프롬프트는 평가가 아니라 변경 요청으로 쓰기

첫 결과물을 받은 뒤에는 “더 좋게”라고 하지 말고, 통제 가능한 변경을 요청하세요:

• “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”

이렇게 해야 두 번째 결과물이 막연한 불만족보다 훨씬 실용적으로 개선됩니다.

업로드와 에셋 참조를 꼼꼼하게 다루기

자주 발생하는 실패 유형 중 하나는 입력 관리가 느슨한 경우입니다:

• 잘못된 파일 업로드
• 잘못된 asset ID 참조
• <original-image> 같은 래퍼 누락
• signed asset URL이 영구적으로 유효하다고 가정

외부 미디어가 들어가는 워크플로라면, 파일 추적과 메시지 포맷 관리에 엄격해야 합니다.

즉시 완료가 아니라 비동기 폴링을 기준으로 설계하기

에이전트나 자동화에서 pexoai-agent 활용도를 높이려면, 지연 완료를 전제로 설계해야 합니다:

• 요청 제출
• project ID 저장
• backoff를 둔 폴링
• 준비된 뒤에만 에셋 가져오기
• 사용자에게 의미 있는 상태 전달

많은 사용자 불만은 이 시스템을 작업 큐가 아니라 동기식 chat처럼 다루는 데서 나옵니다.

스크립트를 수정하기 전에 troubleshooting 문서를 먼저 보기

출력이 실패하거나 동작이 일관되지 않는다면 먼저 다음을 보세요:

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

공통 레이어는 이미 인증, 요청 처리, 간결한 에러 출력 형식을 표준화해 두었습니다. 많은 경우 스크립트를 수정할 필요는 없고, 기존 에러 형식을 정확히 해석하는 것이 더 중요합니다.

사전 점검으로 pexoai-agent 안정성 높이기

pexoai-agent를 반복적으로 사용할 계획이라면, preflight 습관을 만드는 것이 좋습니다:

• pexo-doctor.sh 실행
• 프로젝트 목록 조회 확인
• 에셋 사용 가능 여부 확인
• 사용자 요청을 받기 전에 quota 또는 인증 만료 여부 확인

이렇게 하면 실제 제작 단계에서 피할 수 있는 실패를 줄일 수 있습니다.

pexoai-agent를 쓰지 말아야 할 때를 아는 것

다음 조건이라면 pexoai-agent는 적합하지 않습니다:

• 오프라인/로컬 전용 생성이 필요하다
• API 자격 증명을 안전하게 저장할 수 없다
• 환경상 shell script를 실행할 수 없다
• AI가 만든 결과물보다 깊은 수동 편집 제어가 필요하다
• 해야 할 일이 실행이 아니라 크리에이티브 브레인스토밍뿐이다

이런 판단 기준을 명확히 아는 것이, 기능 목록을 하나 더 보는 것보다 설치 결정을 더 잘 도와줍니다.