Alibabacloud Bailian Videoanalysis

Bailian Video Analysis

This skill provides video analysis functionality based on Alibaba Cloud Bailian Video Analysis Light Application. It uses the Bailian (QuanMiaoLightApp) API for intelligent video comprehension, including shot analysis, ASR transcription, title generation, caption extraction, and mind mapping.

Architecture: CLI (Credential Chain) + OSS (File Storage) + Bailian Workspace + Quanmiao Video Analysis Service + Python SDK Scripts

---

Output Language Policy

Detection Priority: User input language → Environment language → Default: Chinese (中文)

Apply to: All user-facing messages, summaries, error explanations, and interactive prompts.

Keep original language: Code snippets, API responses, file paths, technical identifiers, HTTP status codes.

---

Installation

1. Python Dependencies

python -m pip install -r scripts/requirements.txt
# On some systems, use pyhon3 instead of python

2. Alibaba Cloud CLI

Pre-check: Aliyun CLI >= 3.3.1 required

Run aliyun version to verify >= 3.3.1. If not installed or version too low,

see references/cli-installation-guide.md for installation instructions.

Then [MUST] run aliyun configure set --auto-plugin-install true to enable automatic plugin installation.

AI-Mode Configuration for aliyun CLI

>

When using the aliyun CLI in this skill, you MUST configure AI-Mode settings:

>

```bash

# Enable AI-Mode (required before using CLI commands)

aliyun configure ai-mode enable

>

# Set User-Agent for tracking (required)

aliyun configure ai-mode set-user-agent AlibabaCloud-Agent-Skills/alibabacloud-bailian-videoanalysis

>

# Update plugins to latest versions (recommended)

aliyun plugin update

```

>

Note: After completing your tasks, you can disable AI-Mode:

```bash

aliyun configure ai-mode disable

```

3. Important Prerequisite: Activate Bailian and Video Analysis Service

Before using this skill, you must first activate the Video Analysis service in the Alibaba Cloud Bailian console!

1. Visit Bailian Video_Analysis page 2. Click the "Paid activation" button 3. Confirm activation and wait for the service to take effect (usually 1-2 minutes)

4. Important Prerequisite: Guide Users to Grant Permissions in Alibaba Cloud Access Control and Bailian

Before using this skill, you must grant the following permissions to the previously configured AK, otherwise calls will fail and may cause 403 errors

1) RAM Permission Grant

See references/ram-policies.md for the full list of required RAM permissions and authorization instructions.

[MUST] Permission Failure Handling: When any command or API call fails due to permission errors at any point during execution, follow this process:

1. Read references/ram-policies.md to get the full list of permissions required by this SKILL

2. Use ram-permission-diagnose skill to guide the user through requesting the necessary permissions

3. Pause and wait until the user confirms that the required permissions have been granted

2) Bailian Workspace Permission Grant

1. Visit Alibaba Cloud Bailian Permission Management 2. If the RAM user corresponding to the AK does not exist, click "Add User" in the upper right corner of the page, select the corresponding RAM user and click confirm to add. 3. There is a 30s effective time after configuration, please wait patiently for a while.

---

Authentication

Pre-check: Alibaba Cloud Credentials Required

>

Security Rules:

- NEVER read, echo, or print AK/SK values (e.g., echo $ALIBABA_CLOUD_ACCESS_KEY_ID is FORBIDDEN)

- NEVER ask the user to input AK/SK directly in the conversation or command line

- NEVER use aliyun configure set with literal credential values

- ONLY use aliyun configure list to check credential status

>

```bash

aliyun configure list

```

Check the output for a valid profile (AK, STS, or OAuth identity).

>

If no valid profile exists, STOP here.

1. Obtain credentials from Alibaba Cloud Console

2. Configure credentials outside of this session (via aliyun configure in terminal or environment variables in shell profile)

3. Return and re-run after aliyun configure list shows a valid profile

---

Parameter Confirmation

IMPORTANT: Parameter Confirmation — Before executing any command or API call,

confirm user-provided or customizable parameters (video source, OSS bucket, oss object key).

System-auto-resolved parameters (workspace_id, default OSS bucket) do NOT

require explicit confirmation unless the user wants to override them.

Confirmation Workflow: 1. Auto-detection first: The skill will auto-detect workspace_id and ossBucket when possible 2. User override: If user wants to specify custom values, confirm before using 3. Local vs URL: Confirm whether user is providing a local file path or a public URL

---

Core Workflow

⚠️ CRITICAL: Cloud API Mandatory — This skill MUST use Bailian (QuanMiaoLightApp) API for video analysis. Local tools (ffmpeg, whisper, OpenCV, ffprobe, mediainfo, etc.) are FORBIDDEN. If API calls fail due to credentials or permissions, follow Permission Failure Handling process — DO NOT fall back to local analysis.

Step 1: Environment Check

Run python scripts/check_env.py to verify:

• Python packages are installed
• Credentials are configured via default credential chain

If check_env.py fails or returns {"ready": false}:

• Packages missing → Run python -m pip install -r scripts/requirements.txt
• Credentials missing or invalid → Follow Permission Failure Handling process:

1. Read references/ram-policies.md to get required permissions 2. Use ram-permission-diagnose skill to guide user through permission request 3. Wait for user confirmation before proceeding 4. DO NOT proceed with local analysis tools

Expected output: {"ready": true} indicates environment is properly configured.

Step 2: Get Workspace ID

Do not ask the user for workspace_id upfront. Always auto-fetch available workspaces first:

aliyun modelstudio list-workspaces --user-agent AlibabaCloud-Agent-Skills/alibabacloud-bailian-videoanalysis

Workspace selection logic:

• Single workspace returned → use it directly, no need to prompt the user
• Multiple workspaces returned → display a numbered list and proceed with the following:

1. Default behavior: Use the first workspace in the list automatically to avoid unnecessary interaction 2. User explicitly requests selection: If the user says "let me choose workspace", "show me the workspace list", or similar, present the full list and ask them to pick one

• No workspaces returned → inform the user that no Bailian workspace is available, guide them to create one at the Bailian Console
• Record user selection in the session to avoid repeated inquiries

Step 3: Upload File(video_source) to OSS

Based on the input resource type from Input Resource Validation:

Case A: User provided a downloadable URL → Verify URL accessibility: Test if the URL is downloadable using appropriate method for your OS → Skip this step. Use the video_source as file_url in Step 4.

Case B: User provided a local file path → Auto-detects OSS bucket、Upload local file to OSS and get a temporary URL(file_url) for Step 4:

• (1) Auto-detect or use user-specified OSS bucket:
• If user specifies --ossBucket <bucket_name>, attempt to use that bucket
• If the specified bucket returns 403 AccessDenied or BucketAlreadyExists: DO NOT switch to another bucket automatically. Instead:

1. Inform the user that the specified bucket is not accessible 2. Follow the Permission Failure Handling process in RAM Policy section 3. Guide user to grant OSS bucket access permissions or specify an alternative bucket they own 4. Wait for user confirmation before proceeding

• If no bucket specified, auto-detect from first available bucket

aliyun ossutil ls --user-agent AlibabaCloud-Agent-Skills/alibabacloud-bailian-videoanalysis

• (2) Upload file to OSS: Generate a unique key(oss_object_key) for the uploaded file.

IMPORTANT - Upload Path Restriction:

• Default path: MUST use /temp/quanmiao/YYYYMMDD/filename format (auto-generated with current date)
• Custom path: ONLY if user explicitly specifies a custom oss_object_key, otherwise always use default path
• Security rule: NEVER upload files outside /temp/quanmiao/ prefix unless user explicitly requests it

aliyun ossutil cp <video_source> oss://{oss_bucket}/{oss_object_key} --user-agent AlibabaCloud-Agent-Skills/alibabacloud-bailian-videoanalysis --region {oss_region}

• (3) Generate temporary URL: Generate a temporary URL for the uploaded file using the ossutil sign command.
• --expireSeconds: Default 14400s (4 hours), confirm if different value needed

aliyun ossutil sign oss://{oss_bucket}/{oss_object_key} --expires-duration {expire_seconds} --user-agent AlibabaCloud-Agent-Skills/alibabacloud-bailian-videoanalysis --region {oss_region}

• (4) Verify URL accessibility: Test if the generated URL is downloadable using appropriate method for your OS
• Note: Prefer GET request over HEAD request for verification, as some OSS signature versions may reject HEAD requests.

Recommended validation URL downloadable methods:

• macOS/Linux: curl -L --connect-timeout 10 --max-time 30 -o /dev/null -w "%{http_code}" <file_url> (returns HTTP status code)
• Windows: Invoke-WebRequest -Uri <file_url> -Method Head -TimeoutSec 30 (PowerShell)

Validation criteria:

• HTTP 200 → URL is valid and accessible, proceed to Step 4
• HTTP 403/404 → URL expired or invalid, regenerate with ossutil sign
• Other errors → Check network or OSS permissions

Step 4: Submit Video Analysis Task

⚠️ MANDATORY API CALL — You MUST call SubmitVideoAnalysisTask on QuanMiaoLightApp product (version 2024-08-01). Do NOT use videorecog, Mts, or any other product. Do NOT attempt local analysis.

API Selection Checklist — Before calling, verify:

- ✅ Product: QuanMiaoLightApp (NOT videorecog, NOT Mts)

- ✅ Version: 2024-08-01

- ✅ Action: SubmitVideoAnalysisTask

- ✅ Parameters: workspace_id, file_url

python scripts/quanmiao_submit_videoAnalysis_task.py --workspace_id <workspace_id> --file_url <file_url>

Parameters requiring confirmation:

• --workspace_id: From Step 2 (confirm with user)
• --file_url: From Step 3 upload result or user-provided URL (confirm validity)

Error Handling:

• If API returns 401 InvalidApiKey or 403 AccessDenied: STOP and follow Permission Failure Handling process
• Do NOT attempt alternative APIs or local tools
• Inform user: "Video analysis requires Bailian service activation and proper RAM permissions. Please follow the permission grant guide."

Returns task_id for polling.

Step 5: Poll for Task Result

⚠️ MANDATORY API CALL — You MUST poll GetVideoAnalysisTask on QuanMiaoLightApp product (version 2024-08-01) until status is SUCCESSED. Do NOT generate summary from local tools or filename inference.

Video analysis is asynchronous. Poll until completion:

Task Status: PENDING → RUNNING → SUCCESSED | FAILED | CANCELED

Variables:

• result_json_path: ~/.quanmiao/videoanalysis/<video_filename_without_ext>_<task_id>.json
• index_file: ~/.quanmiao/videoanalysis/index.jsonl

Polling Loop: 1. Wait 10 seconds after submission 2. Run: python scripts/quanmiao_get_videoAnalysis_task_result.py --workspace_id <workspace_id> --task_id <task_id> --save_path <result_json_path> 3. Check the returned status field:

• `SUCCESSED` → Script auto-saves JSON to result_json_path, append entry to index_file, display saved locations, then proceed to Step 6
• `FAILED` or `CANCELED` → check error message, inform user, stop
• `PENDING` or `RUNNING` → display any partial results available, wait 10s, repeat from step 2

4. Max 180 retries (approximately 30 minutes)

When taskStatus = SUCCESSED:

1. Append to index file (index_file):

    {"task_id": "<task_id>", "video_source": "<original_path_or_url>", "workspace_id": "<workspace_id>", "result_file": "<result_json_path>", "timestamp": "<ISO8601>"}

2. Display saved locations:

✅ Files saved successfully:
- Raw JSON result: <result_json_path>
- Index updated: <index_file>

Parameters requiring confirmation:

• --workspace_id: Same as Step 4 (confirm consistency)
• --task_id: From Step 4 submission result (verify before polling)

Step 6: Summarize Video Content

CRITICAL: Use the results from Step 5 directly. Do NOT call the API again. Do NOT re-execute any analysis.

Extract data from the SUCCESSED response obtained in Step 5 and summarize according to user requirements.

Case A: If the user has a specific analysis request (e.g., "analyze the speaker's body language", "extract key business insights", "compare two people in the video"), base your answer primarily on:

• `payload.output.videoGenerateResults` — scene-by-scene analysis, descriptions, interpretations
• `payload.output.videoAnalysisResult.text` — visual shot analysis, object/person recognition, action detection

Combine these fields to construct a targeted answer. Supplement with other fields (captions, mind map, title) as context if relevant.

Case B: If no specific request, use the standard output format: Title → Outline → Summary → Captions → Shot Analysis → Timeline → Token Usage

---

Important Constraints

• Cloud-only: No local fallbacks (ffmpeg, whisper, etc.). If cloud API fails, follow Permission Failure Handling process.
• Violation Consequence: Using local tools instead of QuanMiaoLightApp API will result in task failure.
• Security: Never expose credentials in logs or prompts
• Permissions: On auth errors, see ram-policies.md
• Caching: Check ~/.quanmiao/videoanalysis/index.jsonl before re-analyzing same video

---

Success Verification

See references/verification-method.md for step-by-step verification commands and expected outcomes.

---

Cleanup

To clean up resources created by this skill:

Delete uploaded OSS objects:

aliyun ossutil rm oss://{oss_bucket}/{oss_object_key} --user-agent AlibabaCloud-Agent-Skills/alibabacloud-bailian-videoanalysis

Cleanup best practices:

• Confirm bucket name and oss object key before deletion
• Only delete objects with /temp/quanmiao/ prefix to avoid accidental data loss
• Cached results at ~/.quanmiao/videoanalysis/ can be kept for future reference or deleted manually

---

Best Practices

1. Always verify environment first — run check_env.py before any other operation to catch missing dependencies or credentials early. 2. Auto-detect workspace_id — always fetch workspaces via list-workspaces; default to the first result, but present a selection list when the user explicitly asks to choose. 3. Use default OSS settings — unless the user specifies a particular bucket, let the script auto-detect the bucket and generate the oss object key. 4. Display partial results during polling — when task status is RUNNING, show available results (title, captions) to give the user real-time feedback. 5. Save complete result for summary — when status becomes SUCCESSED, use the full result payload directly for Step 6 without re-calling the API. 6. Respect URL expiration — temporary OSS URLs expire after expireSeconds (default 14400s); ensure the task is submitted before the URL expires. 7. Handle permission errors gracefully — follow the Permission Failure Handling process in the RAM Policy section; never improvise credential fixes.

---

Command Tables

See references/related-commands.md for the full list of available scripts and their parameters.

---

Reference Links

---

Troubleshooting

Common scenarios:

• Permission denied → See ram-policies.md
• CLI not found → See cli-installation-guide.md
• Workspace not found → Create at Bailian Console
• Upload failed → Check OSS bucket permissions
• Task timeout → Video too large or network issues

---

Acceptance Criteria: alibabacloud-bailian-videoanalysis

Scenario: Alibaba Cloud Bailian (Quanmiao) Video Analysis Purpose: Skill testing acceptance criteria

---

Correct Python Script Usage Patterns

1. Environment Check

✅ CORRECT

python scripts/check_env.py

• Returns JSON with ready: true/false
• Checks Python packages and credentials via default credential chain
• Does NOT read or print AK/SK values

❌ INCORRECT

echo $ALIBABA_CLOUD_ACCESS_KEY_ID   # NEVER print credentials
python scripts/check_env.py --ak xxx --sk xxx   # NEVER pass AK/SK as arguments

• Credentials are checked via the default credential chain only
• The script uses CredentialClient internally; no manual credential passing

2. Workspace Listing

✅ CORRECT

aliyun modelstudio list-workspaces --user-agent AlibabaCloud-Agent-Skills/alibabacloud-bailian-videoanalysis

• Returns JSON array of available workspaces
• Auto-detects workspace_id; does NOT require user to know it in advance
• Uses --user-agent parameter for tracking

❌ INCORRECT

aliyun modelstudio list-workspaces   # Missing --user-agent parameter

3. File Upload to OSS

✅ CORRECT

# List buckets first
aliyun ossutil ls --user-agent AlibabaCloud-Agent-Skills/alibabacloud-bailian-videoanalysis

# Upload file
aliyun ossutil cp /path/to/video.mp4 oss://my-bucket/temp/quanmiao/20260409/video.mp4 --user-agent AlibabaCloud-Agent-Skills/alibabacloud-bailian-videoanalysis --region cn-beijing

# Generate temporary URL
aliyun ossutil sign oss://my-bucket/temp/quanmiao/20260409/video.mp4 --expires-duration 7200 --user-agent AlibabaCloud-Agent-Skills/alibabacloud-bailian-videoanalysis --region cn-beijing

• Uses auto-detected bucket and generated object key by default
• All commands include --user-agent parameter
• Optionally specifies custom --expires-duration (default 7200s)

❌ INCORRECT

aliyun ossutil cp /path/to/video.mp4 oss://my-bucket/key   # Missing --user-agent and --region
aliyun ossutil sign oss://my-bucket/key   # Missing required parameters

4. Submit Video Analysis Task

✅ CORRECT

python scripts/quanmiao_submit_videoAnalysis_task.py --workspace_id llm-xxx --file_url "https://..."

• workspace_id must come from Step 2
• file_url must come from Step 3 (upload script output tempUrl)

❌ INCORRECT

python scripts/quanmiao_submit_videoAnalysis_task.py --workspace_id fake-id --file_url "invalid-url"   # Invalid workspace_id or URL
python scripts/quanmiao_submit_videoAnalysis_task.py   # Missing required parameters

• Both --workspace_id and --file_url are required
• file_url must be a valid temporary OSS URL

5. Get Task Result

✅ CORRECT

python scripts/quanmiao_get_videoAnalysis_task_result.py --workspace_id llm-xxx --task_id abc123

• Poll every 10-15 seconds until status is SUCCESSED or FAILED
• Handle RUNNING status by displaying partial results

❌ INCORRECT

python scripts/quanmiao_get_videoAnalysis_task_result.py --workspace_id llm-xxx --task_id abc123 --retry 1000   # No --retry parameter exists

• The script returns the current task status; polling logic is handled externally
• Max retries should be 180 (approximately 30 minutes)

6. Authentication

✅ CORRECT

aliyun configure list   # Check credential status

• Uses aliyun configure list to verify credentials
• Relies on Alibaba Cloud default credential chain

❌ INCORRECT

aliyun configure set --mode AK --access-key-id LTAI... --access-key-secret abc...   # NEVER set credentials within the session
echo $ALIBABA_CLOUD_ACCESS_KEY_ID   # NEVER print credential values

• Credentials must be configured outside of the session
• Never read, echo, or print AK/SK values

Common Anti-Patterns

Hardcoding User-Specific Parameters

❌ INCORRECT

# Assuming a specific workspace_id without checking
python scripts/quanmiao_submit_videoAnalysis_task.py --workspace_id llm-known-good --file_url ...

• Always fetch workspaces via step 4 first; default to the first result or present a selection list if the user explicitly asks to choose

Skipping Environment Check

❌ INCORRECT

# Jumping directly to OSS upload without checking environment
aliyun ossutil cp /path/to/video.mp4 oss://my-bucket/key --user-agent AlibabaCloud-Agent-Skills/alibabacloud-bailian-videoanalysis --region cn-beijing

• Always run check_env.py first to ensure dependencies and credentials are ready

Re-calling API After Success

❌ INCORRECT

# Step 5 returned SUCCESSED, but calling get_result again in Step 6
python scripts/quanmiao_get_videoAnalysis_task_result.py --workspace_id llm-xxx --task_id abc123

• Use the result from Step 5 directly in Step 6; do NOT call the API again

Aliyun CLI Installation & Configuration Guide

Complete guide for installing and configuring Aliyun CLI.

Table of Contents

• Installation
• macOS
• Linux
• Windows
• Configuration
• Quick Start
• Configuration Modes
• Environment Variables
• Managing Multiple Profiles
• Credential Priority
• Verification
• Security Best Practices
• Troubleshooting
• Advanced Configuration
• Next Steps
• References

Aliyun CLI 3.3.1+: Supports installing and using all published Alibaba Cloud product plugins. Make sure to upgrade to 3.3.1 or later for full plugin ecosystem coverage.

>

[IMPORTANT] After installation, run the following command to enable automatic plugin installation:

```bash

aliyun configure set --auto-plugin-install true

```

Installation

macOS

Using Homebrew (Recommended)

brew install aliyun-cli
# Upgrade to latest
brew upgrade aliyun-cli
# Verify version (>= 3.3.1)
aliyun version

Using Binary

# Download
wget https://aliyuncli.alicdn.com/aliyun-cli-macosx-latest-amd64.tgz
# Extract
tar -xzf aliyun-cli-macosx-latest-amd64.tgz
# Move to PATH
sudo mv aliyun /usr/local/bin/
# Verify
aliyun version

Linux

Debian/Ubuntu

# Download
wget https://aliyuncli.alicdn.com/aliyun-cli-linux-latest-amd64.tgz
# Extract and install
tar -xzf aliyun-cli-linux-latest-amd64.tgz
sudo mv aliyun /usr/local/bin/
# Verify
aliyun version

CentOS/RHEL

# Download
wget https://aliyuncli.alicdn.com/aliyun-cli-linux-latest-amd64.tgz
# Extract and install
tar -xzf aliyun-cli-linux-latest-amd64.tgz
sudo mv aliyun /usr/local/bin/
# Verify
aliyun version

ARM64 Architecture

# Download ARM64 version
wget https://aliyuncli.alicdn.com/aliyun-cli-linux-latest-arm64.tgz
# Extract and install
tar -xzf aliyun-cli-linux-latest-arm64.tgz
sudo mv aliyun /usr/local/bin/

Windows

Using Binary 1. Download from: https://aliyuncli.alicdn.com/aliyun-cli-windows-latest-amd64.zip 2. Extract the ZIP file 3. Add the directory to your PATH environment variable 4. Open new Command Prompt or PowerShell 5. Verify: aliyun version Using PowerShell

# Download
Invoke-WebRequest -Uri "https://aliyuncli.alicdn.com/aliyun-cli-windows-latest-amd64.zip" -OutFile "aliyun-cli.zip"
# Extract
Expand-Archive -Path aliyun-cli.zip -DestinationPath C:\aliyun-cli
# Add to PATH (requires admin privileges)
$env:Path += ";C:\aliyun-cli"
[Environment]::SetEnvironmentVariable("Path", $env:Path, [System.EnvironmentVariableTarget]::Machine)
# Verify
aliyun version

Configuration

Quick Start

aliyun configure set \
  --mode AK \
  --access-key-id <your-access-key-id> \
  --access-key-secret <your-access-key-secret> \
  --region cn-hangzhou

All aliyun configure commands support non-interactive flags, which is the recommended approach — it works in scripts, CI/CD pipelines, and agent-driven automation without hanging on stdin prompts. Where to Get Access Keys 1. Log in to Aliyun Console: https://ram.console.aliyun.com/ 2. Navigate to: AccessKey Management 3. Create a new AccessKey pair 4. Save the secret immediately — it's only shown once

Configuration Modes

Aliyun CLI supports 6 authentication modes. All examples below use non-interactive flags.

1. AK Mode (Access Key)

Most common mode for personal accounts and scripts.

aliyun configure set \
  --mode AK \
  --access-key-id LTAI5tXXXXXXXX \
  --access-key-secret 8dXXXXXXXXXXXXXXXXXXXXXXXX \
  --region cn-hangzhou

Configuration is stored in ~/.aliyun/config.json:

{
  "current": "default",
  "profiles": [
    {
      "name": "default",
      "mode": "AK",
      "access_key_id": "LTAI5tXXXXXXXX",
      "access_key_secret": "8dXXXXXXXXXXXXXXXXXXXXXXXX",
      "region_id": "cn-hangzhou",
      "output_format": "json",
      "language": "en"
    }
  ]
}

2. StsToken Mode (Temporary Credentials)

For short-lived access (tokens expire in 1-12 hours).

aliyun configure set \
  --mode StsToken \
  --access-key-id LTAI5tXXXXXXXX \
  --access-key-secret 8dXXXXXXXXXXXXXXXXXXXXXXXX \
  --sts-token v1.0:XXXXXXXXXXXXXXXX \
  --region cn-hangzhou

Use cases: CI/CD pipelines, temporary access for external contractors, cross-account access.

3. RamRoleArn Mode (Assume RAM Role)

Assume a RAM role for elevated or cross-account access.

aliyun configure set \
  --mode RamRoleArn \
  --access-key-id LTAI5tXXXXXXXX \
  --access-key-secret 8dXXXXXXXXXXXXXXXXXXXXXXXX \
  --ram-role-arn acs:ram::123456789012:role/AdminRole \
  --role-session-name my-session \
  --region cn-hangzhou

Use cases: cross-account resource access, temporary elevated privileges, role-based access control.

4. EcsRamRole Mode (ECS Instance RAM Role)

Use the RAM role attached to an ECS instance — no credentials needed.

aliyun configure set \
  --mode EcsRamRole \
  --ram-role-name MyEcsRole \
  --region cn-hangzhou

Requirements: must be running on an ECS instance with a RAM role attached. Use cases: scripts and automation running on ECS instances.

5. RsaKeyPair Mode (RSA Key Pair)

Use RSA key pair for authentication (generate key pair in Aliyun Console first).

aliyun configure set \
  --mode RsaKeyPair \
  --private-key /path/to/private-key.pem \
  --key-pair-name my-key-pair \
  --region cn-hangzhou

6. RamRoleArnWithEcs Mode (ECS + RAM Role)

Combine ECS instance role with RAM role assumption for cross-account access from ECS.

aliyun configure set \
  --mode RamRoleArnWithEcs \
  --ram-role-name MyEcsRole \
  --ram-role-arn acs:ram::123456789012:role/TargetRole \
  --role-session-name my-session \
  --region cn-hangzhou

Environment Variables

Highest priority - overrides config file Access Key Mode

export ALIBABA_CLOUD_ACCESS_KEY_ID=your_access_key_id
export ALIBABA_CLOUD_ACCESS_KEY_SECRET=your_access_key_secret
export ALIBABA_CLOUD_REGION_ID=cn-hangzhou

STS Token Mode

export ALIBABA_CLOUD_ACCESS_KEY_ID=your_access_key_id
export ALIBABA_CLOUD_ACCESS_KEY_SECRET=your_access_key_secret
export ALIBABA_CLOUD_SECURITY_TOKEN=your_sts_token
export ALIBABA_CLOUD_REGION_ID=cn-hangzhou

ECS RAM Role Mode

export ALIBABA_CLOUD_ECS_METADATA=role_name

Use Case:

• CI/CD pipelines
• Docker containers
• Temporary credential override

Managing Multiple Profiles

Create Named Profiles

aliyun configure set --profile projectA \
  --mode AK \
  --access-key-id LTAI5tAAAAAAAA \
  --access-key-secret 8dAAAAAAAAAAAAAAAAAAAAAAAA \
  --region cn-hangzhou
aliyun configure set --profile projectB \
  --mode AK \
  --access-key-id LTAI5tBBBBBBBB \
  --access-key-secret 8dBBBBBBBBBBBBBBBBBBBBBBBB \
  --region cn-shanghai

Use Specific Profile

aliyun ecs describe-instances --profile projectA
export ALIBABA_CLOUD_PROFILE=projectA
aliyun ecs describe-instances   # Uses projectA

List and Switch Profiles

aliyun configure list                      # List all profiles
aliyun configure set --current projectA    # Switch default profile

Credential Priority

Credentials are loaded in this order (first found wins): 1. Command-line flag: --profile <name> 2. Environment variable: ALIBABA_CLOUD_PROFILE 3. Environment credentials: ALIBABA_CLOUD_ACCESS_KEY_ID, etc. 4. Configuration file: ~/.aliyun/config.json (current profile) 5. ECS Instance RAM Role: If running on ECS with attached role

Verification

Test Authentication

# Basic test - list regions
aliyun ecs describe-regions
# Expected output: JSON array of regions

If successful, you'll see:

{
  "Regions": {
    "Region": [
      {
        "RegionId": "cn-hangzhou",
        "RegionEndpoint": "ecs.cn-hangzhou.aliyuncs.com",
        "LocalName": "China East 1 (Hangzhou)"
      },
      ...
    ]
  },
  "RequestId": "..."
}

If failed, you'll see error messages:

• InvalidAccessKeyId.NotFound - Wrong Access Key ID
• SignatureDoesNotMatch - Wrong Access Key Secret
• InvalidSecurityToken.Expired - STS token expired (for StsToken mode)
• Forbidden.RAM - Insufficient permissions

Debug Configuration

# Show current configuration
aliyun configure get
# Test with debug logging
aliyun ecs describe-regions --log-level=debug
# Check credential provider
aliyun configure get mode

Security Best Practices

1. Use RAM Users (Not Root Account)

• Don't: Use Aliyun root account credentials
• Do: Create RAM users with specific permissions

# Create RAM user in console
# Attach only necessary policies
# Use RAM user's access keys

2. Principle of Least Privilege

Grant only the minimum permissions needed:

# Example: Read-only ECS access
# Attach policy: AliyunECSReadOnlyAccess

3. Rotate Access Keys Regularly

# Create new access key in RAM Console, then update configuration
aliyun configure set --access-key-id NEW_KEY --access-key-secret NEW_SECRET
# Delete old access key from console

4. Use STS Tokens for Temporary Access

aliyun configure set --mode StsToken \
  --access-key-id XXXX --access-key-secret XXXX \
  --sts-token XXXX --region cn-hangzhou

5. Use ECS RAM Roles When Possible

aliyun configure set --mode EcsRamRole --ram-role-name MyRole --region cn-hangzhou

6. Never Commit Credentials

# Add to .gitignore
echo "~/.aliyun/config.json" >> .gitignore
# Use environment variables in CI/CD instead

7. Secure Config File

# Restrict permissions
chmod 600 ~/.aliyun/config.json

Troubleshooting

Issue: Command Not Found

# Check installation
which aliyun
# Check PATH
echo $PATH
# Reinstall or add to PATH

Issue: Authentication Failed

# Verify configuration
aliyun configure get
# Test with debug
aliyun ecs describe-regions --log-level=debug
# Check credentials in console
# Verify access key is active

Issue: Permission Denied

# Error: Forbidden.RAM
# Check RAM user permissions
# Attach necessary policies in RAM console
# Example: AliyunECSFullAccess for ECS operations

Issue: STS Token Expired

# Error: InvalidSecurityToken.Expired
# Reconfigure with new token
aliyun configure set --mode StsToken \
  --access-key-id XXXX --access-key-secret XXXX \
  --sts-token NEW_TOKEN --region cn-hangzhou

Issue: Wrong Region

# Some resources may not exist in the specified region
# Check available regions
aliyun ecs describe-regions
# Update default region
aliyun configure set region cn-shanghai

Advanced Configuration

Custom Endpoint

# Use custom or private endpoint
export ALIBABA_CLOUD_ECS_ENDPOINT=ecs-vpc.cn-hangzhou.aliyuncs.com

Proxy Settings

# HTTP proxy
export HTTP_PROXY=http://proxy.example.com:8080
export HTTPS_PROXY=http://proxy.example.com:8080
# No proxy for specific domains
export NO_PROXY=localhost,127.0.0.1,.aliyuncs.com

Timeout Settings

# Connection timeout (default: 10s)
export ALIBABA_CLOUD_CONNECT_TIMEOUT=30
# Read timeout (default: 10s)
export ALIBABA_CLOUD_READ_TIMEOUT=30

Next Steps

After installation and configuration: 1. Install plugins for services you need (v3.3.1+ supports all published product plugins):

   aliyun plugin install --names ecs vpc rds
   # List all available plugins
   aliyun plugin list-remote

2. Explore commands:

   aliyun ecs --help
   aliyun fc --help

3. Read documentation:

• Command Syntax Guide
• Global Flags Reference
• Common Scenarios

References

• Official Documentation: https://help.aliyun.com/zh/cli/
• RAM Console: https://ram.console.aliyun.com/
• Access Key Management: https://ram.console.aliyun.com/manage/ak
• Plugin Repository: https://github.com/aliyun/aliyun-cli

RAM Permissions

This Skill requires the following Alibaba Cloud RAM permissions to function properly.

Required Permissions

Permission Details

modelstudio:ListWorkspaces

Used to query the list of available Bailian workspaces.

ossutil:ls, ossutil:cp, ossutil:presign

Used to manage OSS buckets and objects, including listing buckets/objects, uploading/downloading files, and generating temporary access URLs.

quanmiaolightapp:SubmitVideoAnalysisTask

Used to submit video analysis tasks to Bailian service.

quanmiaolightapp:GetVideoAnalysisTask

Used to query video analysis task results.

Authorization Methods

Use System Policies (Recommended)

1. Visit Alibaba Cloud RAM Console 2. Select the target RAM user 3. Click "Add Permissions" button 4. Search and select the following system policies:

• AliyunBailianFullAccess (includes Bailian-related permissions)
• AliyunModelStudioReadOnlyAccess (includes ModelStudio-related permissions)
• AliyunQuanMiaoLightAppFullAccess (includes QuanMiao-related permissions)
• AliyunOSSFullAccess (includes OSS-related permissions, can be restricted to specific buckets)

5. Confirm and add permissions

Notes

• There may be a delay of approximately 30 seconds after authorization before permissions take effect
• If you encounter 403 or Index.NoWorkspacePermissions errors, please check:

1. Whether the RAM user has been granted the above permissions 2. Whether workspace permissions have been granted to the user in the Bailian console

---

Permission Failure Handling

When any command or API call fails due to permission errors at any point during execution, follow this process:

1. Read this file (references/ram-policies.md) to get the full list of permissions required by this SKILL 2. Use `ram-permission-diagnose` skill to guide the user through requesting the necessary permissions 3. Pause and wait until the user confirms that the required permissions have been granted 4. Retry the failed operation after permissions are confirmed

Important: Never proceed with operations that require permissions the user does not have. Always pause and wait for explicit confirmation.

Related Commands: alibabacloud-bailian-videoanalysis

Available Python Scripts

All scripts are located in the scripts/ directory:

Aliyun CLI Commands

Important: All aliyun CLI commands MUST include --user-agent AlibabaCloud-Agent-Skills/alibabacloud-bailian-videoanalysis.

Execution Order

1. check_env.py (environment validation)
       ↓
2. aliyun modelstudio list-workspaces (get workspace_id)
       ↓
3a. [If local file] aliyun ossutil cp + sign (upload & get URL)
3b. [If URL provided] Skip upload, use URL directly
       ↓
4. quanmiao_submit_videoAnalysis_task.py (submit task)
       ↓
5. quanmiao_get_videoAnalysis_task_result.py (poll loop)
       ↓
6. Summarize (no script call, use Step 5 result directly)

Verification Method: alibabacloud-bailian-videoanalysis

Step-by-step verification commands to confirm successful execution at each workflow stage.

---

Step 1: Environment Check Verification

Command:

python scripts/check_env.py

Expected Output (Success):

{
  "pythonPackagesInstalled": {
    "alibabacloud-quanmiaolightapp20240801": true,
    "alibabacloud-openapi-util": true,
    "alibabacloud-credentials": true,
    "alibabacloud-tea-openapi": true,
    "alibabacloud-tea-util": true
  },
  "allPythonPackagesInstalled": true,
  "credentialsConfigured": true,
  "ready": true,
  "errors": []
}

Verification Criteria:

• ready field is true
• allPythonPackagesInstalled field is true
• credentialsConfigured field is true
• errors array is empty

Failure Actions:

• If allPythonPackagesInstalled is false → Run pip install -r scripts/requirements.txt
• If credentialsConfigured is false → Guide user to run aliyun configure outside session

Additional CLI Verification:

# Verify Aliyun CLI version >= 3.3.1
aliyun version

# Verify credentials are configured
aliyun configure list

---

Step 2: Workspace Listing Verification

Command:

aliyun modelstudio list-workspaces --user-agent AlibabaCloud-Agent-Skills/alibabacloud-bailian-videoanalysis

Expected Output (Success):

{
  "RequestId": "...",
  "Workspaces": [
    {
      "WorkspaceId": "llm-xxx",
      "Name": "Default Workspace"
    }
  ]
}

Verification Criteria:

• Workspaces array is non-empty
• Each workspace has WorkspaceId and Name fields
• WorkspaceId starts with llm- prefix

Failure Actions:

• If Workspaces is empty → User may not have activated Bailian service; guide to Bailian console
• If error contains No workspace permissions → Check RAM permissions and Bailian workspace authorization

---

Step 3: OSS Upload Verification

Commands:

# List available buckets
aliyun ossutil ls --user-agent AlibabaCloud-Agent-Skills/alibabacloud-bailian-videoanalysis

# Upload file to OSS
aliyun ossutil cp <local-file> oss://<bucket>/<key> --user-agent AlibabaCloud-Agent-Skills/alibabacloud-bailian-videoanalysis --region <region>

# Generate temporary URL
aliyun ossutil sign oss://<bucket>/<key> --expires-duration 7200 --user-agent AlibabaCloud-Agent-Skills/alibabacloud-bailian-videoanalysis --region <region>

Expected Output (Sign Command Success):

https://my-bucket.oss-cn-beijing.aliyuncs.com/temp/quanmiao/20260409/video.mp4?Signature=xxx&Expires=xxx&OSSAccessKeyId=xxx

Verification Criteria:

• Generated URL is a valid HTTPS URL containing OSS domain and signature parameters
• URL includes Signature, Expires, and OSSAccessKeyId query parameters
• Bucket name and object key match the uploaded file

Failure Actions:

• If upload fails with permission error → Follow Permission Failure Handling in RAM Policy section
• If file not found → Verify local file path points to an existing file
• If no buckets available → Create an OSS bucket first or use user-provided video URL directly

---

Step 4: Task Submission Verification

Command:

python scripts/quanmiao_submit_videoAnalysis_task.py --workspace_id <workspace_id> --file_url <tempUrl>

Expected Output (Success):

{
  "task_id": "xxxx"
}

Verification Criteria:

• Response contains a non-empty task_id field
• No error code or message in response

Failure Actions:

• If task_id is missing → Check that workspace_id exists and file_url is valid and not expired
• If permission error → Follow Permission Failure Handling in RAM Policy section

---

Step 5: Task Result Polling Verification

Command:

python scripts/quanmiao_get_videoAnalysis_task_result.py --workspace_id <workspace_id> --task_id <task_id>

Expected Output (SUCCESSED):

{
  "header": {
    "taskId": "...",
    "event": "task-finished",
    "sessionId": "...",
    "eventInfo": "完成视频理解"
  },
  "payload": {
    "output": {
      "videoTitleGenerateResult": { "text": "..." },
      "videoCaptionResult": { "videoCaptions": [] },
      "videoAnalysisResult": { "text": "..." },
      "videoGenerateResults": [{ "text": "..." }],
      "videoMindMappingGenerateResult": { "text": "...", "videoMindMappings": [] },
      "videoCalculatorResult": { "items": [] }
    },
    "usage": {
      "inputTokens": 1,
      "outputTokens": 1,
      "totalTokens": 2
    }
  },
  "requestId": "..."
}

Verification Criteria:

• header.event equals "task-finished"
• payload.output contains all expected result fields
• payload.usage contains token counts

Status Handling:

Maximum retries: 180 (approximately 30 minutes)

---

Step 6: Summary Verification

Verification Criteria:

• Summary uses data from Step 5 result directly (no additional API calls)
• Output includes all sections: title, outline, overview, captions, shot analysis, timeline, summary, token usage
• Token usage numbers match payload.usage from Step 5 result

---