AIOZ Stream API Skill

Interact with the AIOZ Stream API — a Web3 decentralized streaming platform — using the user's API key pair. Base URL: https://api.aiozstream.network/api

---

Credential Collection

Before performing any API action, Clawbot must collect the user's API credentials if they have not already been provided. Clawbot should prompt the user with two separate open-ended text input fields:

1. 1. AIOZ Stream Public Key — Ask: "Please enter your AIOZ Stream Public Key:"
2. AIOZ Stream Secret Key — Ask: "Please enter your AIOZ Stream Secret Key:"

Rules:

• - Use open-ended text input (not dropdowns or multiple choice) so the user can type or paste their actual key values.
• Do not proceed with any API call until both keys have been provided.
• Store them in session as $AIOZ_PUBLIC_KEY and $AIOZ_SECRET_KEY for use in all subsequent requests.
• Remind the user: "Keep your keys safe — treat them like passwords and consider rotating them after this session."

---

Authentication

Every request must include these two headers:

stream-public-key: $AIOZ_PUBLIC_KEY
stream-secret-key: $AIOZ_SECRET_KEY

Helper function for all curl calls:

AIOZ_HEADERS=(
  -H "stream-public-key: ${AIOZ_PUBLIC_KEY}"
  -H "stream-secret-key: ${AIOZ_SECRET_KEY}"
)

---

How Clawbot Should Respond to Upload Actions

When Clawbot performs any upload or encoding action on behalf of the user, it must use the following response templates exactly. These are not optional — they define how Clawbot communicates status back to the user at every stage.

---

📤 During Upload — Chunked Upload Progress

While uploading chunks, Clawbot must display a live progress block after each successful chunk:

CODEBLOCK2

• - Replace {title} with the actual media title.
• Replace {bar} with a Unicode progress bar (e.g., ████████░░).
• Replace {percent}, {done}, {total} with real values.
• Show ✅ for completed chunks, ⏳ for the current one, ❌ for failed ones.

---

✅ After /media/:id/complete — Upload Complete

When /complete returns successfully, Clawbot must respond with:

CODEBLOCK3

---

📡 Webhook Response Templates

When Clawbot receives or reports on a webhook event, it must use the matching template below.

file_received

CODEBLOCK4

---

encoding_started

CODEBLOCK5

---

partial_finished

CODEBLOCK6

---

encoding_finished

CODEBLOCK7

---

encoding_failed

CODEBLOCK8

---

🔔 Webhook Event Quick Reference

Event	Status After	Clawbot Response
INLINECODE17	INLINECODE18	📥 File received, queuing transcode…
INLINECODE19

transcoding | ⚙️ Encoding started… |
| partial_finished | transcoding | 🔄 Partial quality preset ready |
| encoding_finished | done | ✅ Your media is ready to stream! |
| encoding_failed | fail | ❌ Encoding failed. Clawbot will guide you through a retry. |

---

1. VIDEO MANAGEMENT

Create a video object

CODEBLOCK9

Rules:

• - type must be "video" (required)
• Supported resolutions: 240p, 360p, 480p, 720p, 1080p, 1440p, 2160p, INLINECODE36
• Video codecs: h264 (max 4K), h265 (max 8K)
• ⚠️ H.265 on Apple (Safari/iOS): must use container_type: "fmp4", NOT INLINECODE40
• If qualities is omitted, the server applies default encoding

Before creating a video with custom qualities, Clawbot must check transcode cost first:

CODEBLOCK10

If is_enough is false, Clawbot must inform the user:

⚠️ Your account balance is insufficient to transcode with the requested quality presets. Please top up your AIOZ wallet before proceeding.

List / Search videos

CODEBLOCK11

INLINECODE44 options: new, transcoding, done, fail, INLINECODE49

Get video detail

CODEBLOCK12

Upload video (chunked — 50MB–200MB per chunk)

Step 1 — Upload each chunk:

CODEBLOCK13

Step 2 — Signal completion (after ALL chunks uploaded):

CODEBLOCK14

⚠️ Clawbot must always compute the correct MD5 hash per chunk. Call /complete only after all chunks succeed.

Update video info

CODEBLOCK15

Upload video thumbnail

CODEBLOCK16

Delete video

CODEBLOCK17

---

2. AUDIO MANAGEMENT

Audio uses the same endpoints as video but with type: "audio". Key differences:

• - resolution uses presets: standard, good, highest, INLINECODE56
• Only audio_config is needed (no video_config)
• Response does not include INLINECODE59

Create an audio object

CODEBLOCK18

Calculate audio transcode price

CODEBLOCK19

All other operations (list, detail, upload part, complete, update, delete) use the same endpoints as video, with AUDIO_ID in place of VIDEO_ID.

---

3. MEDIA CHAPTERS

Chapters are stored per language in .vtt format. Each (media_id, language) pair holds at most one chapter.

INLINECODE64 accepts BCP 47 tags: en, vi, en-US, fr-CA, etc.

Add chapter

CODEBLOCK20

List chapters

CODEBLOCK21

Delete chapter

CODEBLOCK22

---

4. MEDIA TRANSCRIPTS (Subtitles / Captions)

Transcripts are .vtt files, one per language per media. Can be set as default for the player.

⚠️ If a transcript for the same primary language already exists, the request will be rejected. Clawbot must inform the user and ask if they want to delete the existing one first.

Add transcript

CODEBLOCK23

List transcripts

CODEBLOCK24

Set default transcript

CODEBLOCK25

Delete transcript

CODEBLOCK26

If the deleted transcript was the default, the system clears the default. Clawbot must remind the user to set a new default manually.

---

5. API KEY MANAGEMENT

Create API key

CODEBLOCK27

⚠️ The secret is shown only once. Clawbot must immediately display it to the user and explicitly warn them it cannot be retrieved again.

List API keys

CODEBLOCK28

Update API key name

CODEBLOCK29

Delete API key

CODEBLOCK30

---

6. USER INFO

Get current user

CODEBLOCK31

---

7. WEBHOOKS

Events available: file_received, encoding_started, partial_finished, encoding_finished, INLINECODE75

Create webhook

CODEBLOCK32

List webhooks

CODEBLOCK33

Get webhook detail

CODEBLOCK34

Update webhook

CODEBLOCK35

Test / trigger webhook

CODEBLOCK36

Clawbot must use /webhooks/check/:id to verify a webhook URL is reachable before confirming it to the user.

Delete webhook

CODEBLOCK37

---

8. PLAYERS

Player themes allow full visual customization of the embedded player.

Color rule: all colors must be rgba(...) format.
Size rule: all sizes must be px format.
Clawbot must validate these before sending to the API and correct them if the user provides hex or named colors.

Create player theme

CODEBLOCK38

List player themes

CODEBLOCK39

Get player theme detail

CODEBLOCK40

Update player theme

CODEBLOCK41

Clawbot must warn the user: CDN propagation for player theme changes may take up to 10 minutes.

Upload player logo

CODEBLOCK42

Delete player logo

CODEBLOCK43

Assign player theme to video

CODEBLOCK44

Delete player theme

CODEBLOCK45

If the delete fails because the player is assigned to a video, Clawbot must inform the user and ask if they want to unassign it first.

---

9. ANALYTICS

All analytics endpoints are POST with time range in UNIX timestamps.

Clawbot must always convert human-readable dates provided by the user into UNIX timestamps before constructing requests.

Aggregated metrics (single number)

CODEBLOCK46

Breakdown by dimension

CODEBLOCK47

Time series (metrics over time)

CODEBLOCK48

---

10. PAYMENTS

Get usage statistics

CODEBLOCK49

Get top-up history

CODEBLOCK50

Get billing history

CODEBLOCK51

---

11. PLAYLISTS

Playlists use a linked-list structure internally (next_id / previous_id) for item ordering.

Clawbot must always fetch the playlist detail first before moving items to get accurate next_id / previous_id values.

Create playlist

CODEBLOCK52

List playlists

CODEBLOCK53

Get playlist detail (with video items)

CODEBLOCK54

Update playlist

CODEBLOCK55

Add video to playlist

CODEBLOCK56

Move video position in playlist

CODEBLOCK57

Positioning reference (current_id is always required):

• - Move to top: set only next_id to the current first item's ID
• Move to bottom: set only previous_id to the current last item's ID
• Move between two items: set both next_id and INLINECODE88

Remove video from playlist

CODEBLOCK58

Delete playlist thumbnail

CODEBLOCK59

Delete playlist

CODEBLOCK60

---

Behavior Guidelines

Clawbot must follow these rules when operating this skill:

1. 1. Always include both auth headers (stream-public-key and stream-secret-key) on every request, including /user/me.
2. Chunked uploads: calculate chunk boundaries correctly. Each chunk needs its MD5. Call /complete only after all chunks succeed. Display the chunked upload progress template at each step.
3. Transcode cost check: before creating media with custom qualities, call /media/cost and verify is_enough: true. If false, block the action and notify the user to top up.
4. Player colors/sizes: validate that colors are in rgba(...) format and sizes are in px. If the user provides hex or named colors, convert them automatically and inform the user.
5. Analytics timestamps: always convert human-readable dates to UNIX timestamps silently before sending requests.
6. Playlist ordering: always fetch playlist detail first to get accurate next_id / previous_id before reordering items.
7. API key secret: immediately display the secret to the user in full and warn explicitly that it cannot be retrieved again.
8. Webhook testing: always use /webhooks/check/:id to verify a webhook URL is reachable before confirming it to the user.
9. H.265 on Apple devices: if the user selects h265 with mpegts, automatically warn them and suggest switching to fmp4 for Safari/iOS compatibility.
10. Upload notifications: always use the response templates defined in this skill — never summarize upload events as plain text.

---

Quick Reference — Endpoints

Module	Method	Path
Video	POST	INLINECODE105
Video

POST | /media (list) | | Video | GET | /media/:id | | Video | GET | /media/cost | | Video | POST | /media/:id/part | | Video | GET | /media/:id/complete | | Video | PATCH | /media/:id | | Video | POST | /media/:id/thumbnail | | Video | DELETE | /media/:id | | Audio | — | (same paths as Video, type=audio) | | Chapter | POST | /media/:id/chapters/:lan | | Chapter | GET | /media/:id/chapters | | Chapter | DELETE | /media/:id/chapters/:lan | | Transcript | POST | /media/:id/transcripts/:lan | | Transcript | GET | /media/:id/transcripts | | Transcript | PATCH | /media/:id/transcripts/:lan | | Transcript | DELETE | /media/:id/transcripts/:lan | | API Keys | POST | /api_keys | | API Keys | GET | /api_keys | | API Keys | PATCH | /api_keys/:id | | API Keys | DELETE | /api_keys/:id | | Users | GET | /user/me | | Webhooks | POST | /webhooks | | Webhooks | GET | /webhooks | | Webhooks | GET | /webhooks/:id | | Webhooks | PATCH | /webhooks/:id | | Webhooks | DELETE | /webhooks/:id | | Webhooks | POST | /webhooks/check/:id | | Players | POST | /players | | Players | GET | /players | | Players | GET | /players/:id | | Players | PATCH | /players/:id | | Players | DELETE | /players/:id | | Players | POST | /players/:id/logo | | Players | DELETE | /players/:id/logo | | Players | POST | /players/add-player | | Analytics | POST | /analytics/metrics/data/:metric/:aggregation | | Analytics | POST | /analytics/metrics/bucket/:metric/:breakdown | | Analytics | POST | /analytics/metrics/timeseries/:metric/:interval | | Payments | GET | /payment/usage | | Payments | GET | /payment/top_ups | | Payments | GET | /payment/billings | | Playlists | POST | /playlists/create | | Playlists | POST | /playlists (list) | | Playlists | GET | /playlists/:id | | Playlists | PATCH | /playlists/:id | | Playlists | POST | /playlists/:id/items | | Playlists | PUT | /playlists/:id/items (reorder) | | Playlists | DELETE | /playlists/:id/items/:item_id | | Playlists | DELETE | /playlists/:id/thumbnail | | Playlists | DELETE | /playlists/:id |

---

⚠️ General Warnings & Reminders

Scenario	Clawbot Action Required
H.265 on Apple devices	Warn user and suggest container_type: "fmp4" — "mpegts" will NOT work on Safari/iOS
Insufficient balance

Block the action and tell user to top up before proceeding | | Custom quality presets | Always call /media/cost first — only proceed if is_enough: true | | Chunked upload | Compute MD5 per chunk. Never call /complete until all chunks succeed | | Duplicate transcript language | Inform user, ask if they want to delete the existing transcript first | | Player color format | Convert hex/named colors to rgba(...) automatically, inform user of the conversion | | Player size format | Ensure all sizes are in px before sending | | New API key secret | Display the secret immediately and warn it cannot be retrieved again | | Webhook URL not reachable | Run /webhooks/check/:id and report result before confirming webhook is active | | Analytics date input | Silently convert human-readable dates to UNIX timestamps before querying | | Playlist reordering | Always fetch playlist detail first to get accurate next_id / previous_id | | Player is_default change | Warn user: setting a new default clears all others. CDN propagation may take up to 10 minutes | | Player logo upload | Reject if over 100KB or larger than 200×100px — must be JPEG or PNG | | Deleted default transcript | Remind user to set a new default transcript after deletion | | Player assigned to video | Cannot delete player theme — ask user if they want to unassign it from the video first |