aioz-stream-toolkit（aioz 流工具包）

AIOZ Stream Operations

Interact with AIOZ Stream API quickly with API key authentication. A suite of integrated bash scripts is provided to automatically call REST APIs.

When to use this skill

• User wants to upload or create a video on AIOZ Stream
• User mentions "upload video", "create video", "aioz stream video"
• User wants to query analytics, livestream keys, or account balances
• User wants to get an HLS/MP4 streaming link for their video
• User wants to search/list media or find a video by name

Authentication

This skill uses API key authentication via environment variables:

• STREAM_PUBLIC_KEY: Your AIOZ Stream public key (provided by the platform)
• STREAM_SECRET_KEY: Your AIOZ Stream secret key (provided by the platform)

Credential-safe policy:

• Prefer credentials from secure environment injection.
• If missing, ask the user for credentials and set them as temporary environment variables.
• Never hardcode keys in command examples, logs, or responses.
• Avoid inline one-off commands that contain raw secrets.

If credentials are not present in the shell session, set them once before running scripts:

export STREAM_PUBLIC_KEY="YOUR_STREAM_PUBLIC_KEY"
export STREAM_SECRET_KEY="YOUR_STREAM_SECRET_KEY"

Header mapping used by scripts:

• STREAM_PUBLIC_KEY -> stream-public-key header
• STREAM_SECRET_KEY -> stream-secret-key header

This keeps credentials out of repeated command history and avoids accidental exposure.

Usage Options (Available Scripts)

When the user asks for a feature, use one of the bash scripts located in the scripts/ directory.

Script Routing Map (for Clawbot)

• Upload local file to video: ./scripts/upload_video_file.sh FILE_PATH "TITLE"
• Get media list (GET with optional query params): ./scripts/get_media_list.sh [SEARCH] [PAGE]
• Get media list via POST body (search/page): ./scripts/get_total_media.sh [SEARCH] [PAGE]
• Get all media via POST {}: ./scripts/get_video_list.sh
• Search media by name via POST body: ./scripts/get_video_url_by_name.sh "VIDEO_NAME"
• Create livestream key: ./scripts/create_livestream_key.sh "KEY_NAME"
• Get account/user info and balance: ./scripts/get_balance.sh
• Get usage data (fixed interval=hour): ./scripts/get_usage_data.sh FROM(dd/mm/yyyy) TO(dd/mm/yyyy)
• Get aggregate analytics (watch_time + view_count): ./scripts/get_aggregate_metric.sh TYPE FROM(dd/mm/yyyy) TO(dd/mm/yyyy)
• Get breakdown analytics (device/os/country/browser): ./scripts/get_breakdown_metric.sh TYPE FROM(dd/mm/yyyy) TO(dd/mm/yyyy)
• Combined aggregate + breakdown report: ./scripts/analytic_data.sh TYPE FROM(dd/mm/yyyy) TO(dd/mm/yyyy)

1. Upload Video (Credential-Safe Default Flow)

Use this script to automatically create a video object, upload the file, and complete the flow:

./scripts/upload_video_file.sh "/path/to/video.mp4" "Video Title"

Actual behavior in script:

• Accepts local file path only.
• Validates video by extension (and by MIME where possible).
• File must exist on the local system.

2. Analytics & Usage

To get metrics or account usage:

• Usage Data: ./scripts/get_usage_data.sh FROM(dd/mm/yyyy) TO(dd/mm/yyyy)

- Calls GET /analytics/data?from=...&to=...&interval=hour - FROM/TO must be dd/mm/yyyy format (scripts convert to Unix timestamp)

• Aggregate Metrics: ./scripts/get_aggregate_metric.sh TYPE FROM(dd/mm/yyyy) TO(dd/mm/yyyy)

- Returns: Watch time sum + View count for selected media type - TYPE must be video or audio

• Breakdown Metrics: ./scripts/get_breakdown_metric.sh TYPE FROM(dd/mm/yyyy) TO(dd/mm/yyyy)

- Returns: Device type, Operating system, Country, Browser breakdowns (with total count and data array) - TYPE must be video or audio

• All-in-one Analytics: ./scripts/analytic_data.sh TYPE FROM(dd/mm/yyyy) TO(dd/mm/yyyy)

- Returns: Combined aggregate metrics + all breakdown metrics in one call - TYPE must be video or audio

Date format notes:

• FROM and TO must be dd/mm/yyyy (scripts convert to Unix timestamp internally)

3. Media & Livestream Management

To search existing media, get balance, or create keys:

• List Media: ./scripts/get_media_list.sh [SEARCH] [PAGE]
• Total Media: ./scripts/get_total_media.sh [SEARCH] [PAGE]
• Video List: ./scripts/get_video_list.sh
• Search Video URL: ./scripts/get_video_url_by_name.sh "Video Name"
• Livestream Key: ./scripts/create_livestream_key.sh "Key Name"
• Balance: ./scripts/get_balance.sh

Notes:

• get_video_list.sh currently returns all media (POST /media with empty body), not strictly video-only filtering.
• get_video_url_by_name.sh currently returns search results JSON; it does not extract one URL field automatically.

Full Upload Flow (Common Operational Path)

For a typical upload lifecycle, use this sequence:

1. Create media object
2. Upload media part
3. Complete upload
4. Fetch media detail
5. Print status and URLs (hls_player_url, hls_url, mp4_url)

If using manual curl, the core upload flow is the first 3 steps below.

Step 1: Create Video Object

curl -s -X POST 'https://api.aiozstream.network/api/media/create' \
  -H "stream-public-key: $STREAM_PUBLIC_KEY" \
  -H "stream-secret-key: $STREAM_SECRET_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "title": "VIDEO_TITLE",
    "type": "video"
  }'

Response: extract data.id as VIDEO_ID for the next steps.

Step 2: Upload File Part

Upload the actual video file binary to the created video object. First, get the file size and compute the MD5 hash:

# Get file size (cross-platform compatible)
FILE_SIZE=$(stat -f%z /path/to/video.mp4 2>/dev/null || stat -c%s /path/to/video.mp4)
END_POS=$((FILE_SIZE - 1))

# Compute MD5 hash
HASH=$(md5sum /path/to/video.mp4 | awk '{print $1}')

Then upload via multipart form-data with the Content-Range header:

curl -s -X POST "https://api.aiozstream.network/api/media/VIDEO_ID/part" \
  -H "stream-public-key: $STREAM_PUBLIC_KEY" \
  -H "stream-secret-key: $STREAM_SECRET_KEY" \
  -H "Content-Range: bytes 0-$END_POS/$FILE_SIZE" \
  -F "file=@/path/to/video.mp4" \
  -F "index=0" \
  -F "hash=$HASH"

Important: The Content-Range header is required for the upload to succeed. Format: bytes {start}-{end}/{total_size}. Form-data fields:

• file: the video file binary (use @/path/to/video.mp4)
• index: 0 (for single-part upload)
• hash: MD5 hash of the file part

Step 3: Complete Upload

After the file part is uploaded, call the complete endpoint to finalize:

curl -s -X GET "https://api.aiozstream.network/api/media/VIDEO_ID/complete" \
  -H 'accept: application/json' \
  -H "stream-public-key: $STREAM_PUBLIC_KEY" \
  -H "stream-secret-key: $STREAM_SECRET_KEY"

This triggers transcoding. The upload is now considered successful.

After Upload — Get Video Link

After completing the upload, fetch the video detail to get the streaming URL:

curl -s "https://api.aiozstream.network/api/media/VIDEO_ID" \
  -H "stream-public-key: $STREAM_PUBLIC_KEY" \
  -H "stream-secret-key: $STREAM_SECRET_KEY"

Parse the response to find the HLS or MP4 URL from the assets field and return it to the user.

Custom Upload Config Reference

_(Applicable if implementing custom logic via API directly)_

Quality Presets (resolution field):

• standard — Standard quality
• good — Good quality
• highest — Highest quality
• lossless — Lossless quality

Streaming Formats (type field):

• hls — HTTP Live Streaming (container: mpegts or mp4)
• dash — Dynamic Adaptive Streaming (container: fmp4)

Response Handling

1. Run the appropriate script from the scripts/ directory.
2. Media/Search scripts return raw JSON: get_video_list, get_video_url_by_name, get_total_media, get_media_list
3. Metrics scripts return structured output:

- get_aggregate_metric.sh: Two labeled outputs (Watch Time Sum, View Count) - get_breakdown_metric.sh: Four labeled JSON blocks (=== device_type ===, === operator_system ===, === country ===, === browser ===) - analytic_data.sh: Combined aggregate + breakdown output - get_usage_data.sh: Raw JSON response with pretty-printed format

1. Upload/Management scripts: upload_video_file.sh prints step-by-step status with final URLs
2. Return useful fields explicitly (IDs, status, URLs, totals). If upload status is transcoding or URLs are empty, inform the user to check again later.

Error Handling

• 401: Invalid API keys. Ask user to verify STREAM_PUBLIC_KEY and STREAM_SECRET_KEY.
• Missing Parameters: Scripts validate arguments; pass exactly what they require.
• 404: Resource not found (invalid media ID or livestream ID).
• 500: Server error; suggest retrying.
• Connection timeout/refused: API endpoint may be unavailable; retry and verify https://api.aiozstream.network/api/ accessibility.

Example Interaction Flow

1. User: "Upload my video to AIOZ Stream"
2. Ensure STREAM_PUBLIC_KEY and STREAM_SECRET_KEY exist in environment (ask user only if missing)
3. Ask for the video file path and title
4. Execute: ./scripts/upload_video_file.sh "FILE_PATH" "TITLE"
5. Extract the outputted HLS/MP4 link
6. Return the video link to the user