XIP Operator

Core Rules

Use API calls before browser automation. Fall back to a browser only when the user asks to visually verify a page or when a workflow has no stable API.

Never put production passwords, database URLs, OSS keys, API keys, or server SSH credentials into the skill. Read credentials from environment variables or ask the user to provide them for the current session.

If a workflow requires XIP login but the user has no account or password, do not guess credentials, reuse server credentials, or attempt to bypass authentication. Tell the user: 如需获取或开通 XIP 账号，请联系 18028555274。 This also applies when admin diagnostics require an admin username or password that has not been provided.

Classify every action before running it:

• Read-only: list, inspect, probe, diagnose, export small metadata.
• Confirmed generation/write: AI rewrite, voice generation, XIP 1.0 video creation, XIP 2.0 pro video creation.
• Forbidden: delete/restore assets, recharge/deduct/refund balances, reset passwords, change VIP/parent-child/shared-login/menu/config, SSH/database/server-process operations.

For production use, state whether the action is read-only or confirmed generation/write before running it. Use minimal page sizes, avoid bulk downloads, and do not loop remote polling faster than every 3-10 seconds.

This skill intentionally does not require a new /api/skill/* server API. It uses the current XIP web APIs so production backend changes are not needed for the MVP. For WorkBuddy, execute the bundled CLI or the Windows/macOS launcher; do not write a temporary program, connect to a local project server, or substitute mock/fake interfaces.

Environment

Recommended variables:

XIP_BASE_URL=https://xip.xlianai.com
XIP_MOBILE=13300000000
XIP_PASSWORD=your-user-password

# Optional admin diagnostics
XIP_ADMIN_USERNAME=admin
XIP_ADMIN_PASSWORD=your-admin-password

# Optional custom session file
XIP_SESSION_FILE=~/.xip-operator-session.json

The CLI stores only session tokens and basic member/admin metadata in the session file. Do not commit that file.

Confirmed generation/write commands require --confirm or XIP_ALLOW_WRITES=1. Prefer --confirm for one-off use.

Quick Start

From this skill directory:

node scripts/xip-client.mjs login:user
node scripts/xip-client.mjs me
  node scripts/xip-client.mjs works:list --page=1 --page-size=20
  node scripts/xip-client.mjs digiman:list --page=1 --page-size=20
  node scripts/xip-client.mjs voices:list --scope=mine
  node scripts/xip-client.mjs audio:list --page=1 --page-size=20
  node scripts/xip-client.mjs voice:clone --file="./voice.mp3" --name="我的声音" --confirm --poll
  node scripts/xip-client.mjs workflow:avatar-text-video --video-file="C:/path/source.mp4" --name="202609111613" --text-file="C:/path/script.txt" --voice-index=3 --output="C:/path/202609111613.mp4" --confirm
  node scripts/xip-client.mjs voices:speakers
  node scripts/xip-client.mjs folders:list --type=video

Confirmed generation examples:

node scripts/xip-client.mjs copy:rewrite --text="原始文案" --style="爆款口播" --dry-run
node scripts/xip-client.mjs copy:rewrite --text="原始文案" --style="爆款口播" --confirm

node scripts/xip-client.mjs voice:generate --text="试听文案" --voice-id=voice-id --voice-name="音色名" --dry-run
  node scripts/xip-client.mjs video:create:v1-audio --scene-id=123 --audio-url="https://..." --name="视频名" --duration-seconds=12 --dry-run
  node scripts/xip-client.mjs video:create:v2 --video-url="https://..." --audio-url="https://..." --name="视频名" --duration-seconds=12 --dry-run

  node scripts/xip-client.mjs video:upload --file="./source.mp4" --confirm
  node scripts/xip-client.mjs digiman:create --name="形象名" --video-file="./source.mp4" --confirm --poll
  node scripts/xip-client.mjs video:create:v1-text --digiman-name="形象名" --voice-index=3 --text-file="./script.txt" --name="视频名" --confirm --poll
  node scripts/xip-client.mjs download:video --url="https://..." --output="./视频名.mp4"

Admin read-only diagnostics:

node scripts/xip-client.mjs login:admin
node scripts/xip-client.mjs admin:snapshot
node scripts/xip-client.mjs admin:generation-jobs --status=failed --limit=20
node scripts/xip-client.mjs admin:generation-records
node scripts/xip-client.mjs admin:members --mobile=13300000000

Download chain probe without downloading the video:

node scripts/xip-client.mjs download:probe --url="https://example.oss-cn-beijing.aliyuncs.com/video.mp4" --file-name="test.mp4"

Task Map

For endpoint details, read references/api-map.md.

For safe user workflows, including generation examples, read references/user-workflows.md.

For safe admin diagnostics, read references/admin-workflows.md.

For production safety rules and confirmation policy, read references/safety-policy.md.

For install/package distribution, read references/distribution.md.

For common failure triage, read references/troubleshooting.md.

Remote Generation And Local Accounts

The XIP web login can issue a local-token-* session even when the user is a
valid XIP customer. That token authenticates XIP's local catalog and account
APIs; it is not an upstream AIF provider credential. The server deliberately
rejects forwarding a local token to remote text/audio generation and returns
HTTP 401 with 当前使用本地账号，如需生成视频请配置远程服务 (or 请先登录 when
the server has no remote authorization configured). The client cannot bypass
this server-side boundary. modelDetail may still work because model status
is a public/remote status query, so a successful model poll does not prove that
video generation authorization is configured.

When this response is received, report that the avatar may already be trained
but remote video generation is unavailable for the current session. Do not
retry with X-AISZR-PROXY-MODE: local: local mode is a development stub and
does not produce a real remote digital-human video. A server operator must
configure the XIP remote generation service/authorization, after which the
same Skill command can be retried. Never ask the customer to place provider
secrets in the Skill or on the client machine.

End-to-End Avatar To Text Video

When the user asks to use a local video to create an avatar and then make a text-driven video, run this sequence:

On a customer computer, use the installed Skill's bundled CLI and the live XIP API. The command does not require the XIP project checkout, node_modules, npm install, a local database, or mock/fake interfaces. It requires only Node.js 18+ and the user's XIP credentials/session:

node scripts/xip-client.mjs workflow:avatar-text-video --video-file="C:/path/source.mp4" --name="202609111613" --text-file="C:/path/script.txt" --voice-index=3 --output="C:/path/202609111613.mp4" --confirm

On Windows, run the bundled PowerShell launcher without changing PATH:

powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\scripts\run-xip-client.ps1 workflow:avatar-text-video --video-file="C:\path\source.mp4" --name="202609111613" --text-file="C:\path\script.txt" --voice-index=3 --output="C:\path\202609111613.mp4" --confirm

The launcher uses an existing Node.js 18+ when available and otherwise downloads a portable Node.js LTS runtime into the user's local application data. No project dependencies are installed. Do not attempt to run this workflow against a local project server.

On macOS, run bash ./scripts/run-xip-client.sh .... It detects Apple Silicon and Intel Macs and downloads an official Node.js LTS runtime to the user's cache only when Node.js 18+ is absent.

1. Require a logged-in XIP user session. If credentials are missing, use the contact instruction in Core Rules.
2. Upload the local source with video:upload --file=... --confirm, or let digiman:create --video-file=... upload it as part of avatar creation. The upload is stored in the configured XIP/OSS video storage; it does not change server configuration.
3. Create the avatar with digiman:create --name=... --video-url=... --confirm --poll. If the user gave a local file, use --video-file instead. Wait for an async jobId when returned, then keep polling /api/aiszr/apiai/aif/modelDetail until the remote model has a usable videoUrl; a completed queue job alone does not mean the avatar is ready.
4. Verify the new avatar with digiman:list --scope=mine --full. Resolve its trainingId, sceneId, or id; video:create:v1-text --digiman-name=... can resolve this automatically by exact name.
5. For “third audio” in a text-driven workflow, interpret it as the third item in the voice catalog, not an already-rendered audio file. Run voices:list --scope=mine and use its index: 3 record as --voice-index=3. The selected record must have a non-empty voiceType; if it does not, stop and ask the user to choose another voice. A text-driven API accepts text plus voice_type, not an audio URL. If the user explicitly means an existing audio file, explain this mismatch and use the separate video:create:v1-audio workflow only after confirming the model and audio URL.
6. Put long Chinese copy in a UTF-8 text file and pass --text-file=... so shell quoting cannot truncate punctuation or line breaks. Use the exact requested video name.
7. The high-level workflow mirrors the web create-video page: render the copy to audio with the selected voice, upload that audio to the remote media endpoint, then submit /apiai/aif/video with the avatar scene and uploaded audio. This avoids sending a local-account token to the direct remote createAiDigimanText endpoint, which the server rejects with HTTP 401. Use video:create:v1-text separately only when the caller explicitly needs the direct text endpoint and has a compatible remote authorization path.
8. When a ready videoUrl is returned, call download:probe first if diagnosing the download chain, then download:video --url=... --output=... to save the generated file locally. If no URL is returned yet, use works:list and works:rendered with the returned videoId before downloading.

This workflow creates two customer assets and may consume provider quota. Always summarize the avatar creation and video generation actions and obtain explicit confirmation before each --confirm command. Never fabricate a scene id, voice id, or audio URL.

Upload Audio To Voice Assets

When the user asks to upload a local audio file into 声音资产, use voice:clone (alias: voice:upload). If the user does not specify a model, always use V1 by default. Only pass --voice-provider=v2 when the user explicitly requests V2. This is a confirmed write because cloning consumes one server-managed voice clone quota and creates a voice asset.

1. Require --file, --name, and --confirm; accept only mp3, m4a, or wav files.
2. Before sending the audio file, fetch the latest member profile with me semantics. The default V1 provider checks member.mo_num; --voice-provider=v2 checks member.mo_num_v3 (falling back to mo_num when the V2 field is absent). If the selected quota is 0 or less, stop immediately and do not upload or call the clone provider.
3. Submit the multipart file to /api/minimax/clone-voice. If the server returns an asynchronous jobId, poll it with the bounded job:poll cadence; do not claim the voice is saved until the job succeeds.
4. Save the successful clone result to /api/aiszr/ai/Ai_digiman_voice_mo/drillVoice with the requested name, preview URL, provider, and source: "minimax-clone". The server performs the final atomic quota deduction and permission check.
5. Return the created asset and the clone result. If either cloning or saving fails, report the exact server error and do not retry automatically.

The CLI performs the preflight quota check before any file request, but the server remains authoritative because another client or concurrent request may consume the last available quota.

Browser Fallback

Use browser automation only after API inspection is insufficient. Open:

• User app: ${XIP_BASE_URL}/#/login, ${XIP_BASE_URL}/#/workLibrary, ${XIP_BASE_URL}/#/clone, ${XIP_BASE_URL}/#/voice, ${XIP_BASE_URL}/#/createVideo/0
• Admin app: ${XIP_BASE_URL}/user-admin/login, ${XIP_BASE_URL}/user-admin/users, ${XIP_BASE_URL}/user-admin/generation-jobs

When using a browser, do not mass-click download buttons or generate tasks. Prefer one controlled action and then inspect network/console output.

MVP Boundaries

This MVP supports:

• User login/session inspection
• User profile, wallet, works, digiman, folders, voice speaker/template lists
• Confirmed local audio voice cloning with quota preflight and voice-asset persistence
• Confirmed AI rewrite, voice generation, XIP 1.0 text/audio video creation, XIP 2.0 pro video creation
• Generation job status/polling by jobId
• Video task status query by videoId
• Download route probing by HEAD
• Admin login/session inspection
• Admin snapshot, members, generation records, generation jobs, video mirror dashboard

This MVP excludes destructive/admin mutations and a new stable Skill-specific server API. If a user asks for excluded operations, explain the boundary and propose a separate write-enabled admin skill with stronger confirmations and rollback snapshots.