Audio Upload Aioz Stream Free

SKILL.md

---
slug: audio-upload-aioz-stream-free
name: audio-upload-aioz-stream-free
version: 1.0.0
displayName: AIOZ音频上传免费版
summary: 通过AIOZ Stream API以默认配置上传音频文件，返回HLS流媒体播放链接，适合快速发布。
license: MIT
description: |-
  基于 AIOZ Stream API 的音频上传技能免费版，通过三步流程
  (Create → Upload Part → Complete) 将本地音频文件上传至
  AIOZ 流媒体平台。支持默认快速上传方式，使用默认编码配置，
  上传完成后返回 HLS 流媒体播放链接。使用 API Key
  (stream-public-key/stream-secret-key) 认证。适用于播客发布、
  语音内容托管等基础场景。本免费版仅支持默认编码配置。
tags:
  - Creative
  - Audio
  - Streaming
tools:
  - read
  - exec
---

# AIOZ 音频上传（免费版）

通过 AIOZ Stream API 将本地音频文件上传至 AIOZ 流媒体平台。完整上传流程包含三次 API 调用：创建音频对象 → 上传文件分片 → 完成上传。上传完成后服务端自动触发转码，返回 HLS 流媒体播放链接。本免费版支持默认上传方式与基础编码配置。

## 认证配置

本技能使用 API Key 认证，用户需提供以下两个密钥，作为 HTTP 请求头附加到所有 API 调用：

- `stream-public-key`：AIOZ Stream 公钥
- `stream-secret-key`：AIOZ Stream 私钥

若用户未提供密钥，主动询问获取。密钥通过 AIOZ Stream 控制台创建与管理。

## 完整上传流程

### 第一步：创建音频对象

默认上传仅需标题与类型：

```bash
curl -s -X POST 'https://api-w3stream.attoaioz.cyou/api/videos/create' \
  -H 'stream-public-key: PUBLIC_KEY' \
  -H 'stream-secret-key: SECRET_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "title": "AUDIO_TITLE",
    "type": "audio"
  }'
```

从响应中提取 `data.id`，作为后续步骤的 `AUDIO_ID`。

### 第二步：上传文件分片

上传音频文件二进制数据。首先获取文件大小并计算 MD5 哈希：

```bash
FILE_SIZE=$(stat -f%z /path/to/audio.mp3 2>/dev/null || stat -c%s /path/to/audio.mp3)
END_POS=$((FILE_SIZE - 1))

HASH=$(md5sum /path/to/audio.mp3 | awk '{print $1}')
```

然后通过 multipart form-data 上传，必须包含 `Content-Range` 请求头：

```bash
curl -s -X POST "https://api-w3stream.attoaioz.cyou/api/videos/AUDIO_ID/part" \
  -H 'stream-public-key: PUBLIC_KEY' \
  -H 'stream-secret-key: SECRET_KEY' \
  -H "Content-Range: bytes 0-$END_POS/$FILE_SIZE" \
  -F "file=@/path/to/audio.mp3" \
  -F "index=0" \
  -F "hash=$HASH"
```

`Content-Range` 头格式为 `bytes {start}-{end}/{total_size}`。单分片上传时 start=0、end=file_size-1、total_size=file_size。表单字段：`file` 为音频文件二进制，`index` 为分片序号（单分片为 0），`hash` 为文件的 MD5 哈希。

### 第三步：完成上传

文件分片上传完成后调用完成接口触发转码：

```bash
curl -s -X GET "https://api-w3stream.attoaioz.cyou/api/videos/AUDIO_ID/complete" \
  -H 'accept: application/json' \
  -H 'stream-public-key: PUBLIC_KEY' \
  -H 'stream-secret-key: SECRET_KEY'
```

### 获取播放链接

上传完成后获取音频详情以取得流媒体链接：

```bash
curl -s 'https://api-w3stream.attoaioz.cyou/api/videos/AUDIO_ID' \
  -H 'stream-public-key: PUBLIC_KEY' \
  -H 'stream-secret-key: SECRET_KEY'
```

从响应的 `assets` 或 `hls` 字段解析 HLS 流媒体链接返回给用户。音频输出没有 `mp4_url` 字段，仅提供 HLS 流媒体链接。

## 依赖说明

### 运行环境
- **Agent平台**: 支持SKILL.md的任意AI Agent（Claude Code / Cursor / Codex / Gemini CLI等）
- **操作系统**: Windows / macOS / Linux

### 依赖项
| 依赖项 | 类型 | 是否必需 | 获取方式 |
|:-------|:-----|:---------|:---------|
| LLM API | API | 必需 | 由Agent内置LLM提供 |

### API Key 配置
需要配置对应API Key，详见上文环境配置章节

### 可用性分类
- **分类**: MD+EXEC（）

**API Key配置方式**:
```bash
export API_KEY="your_api_key_here"
```
配置后需重启会话或开启新终端生效。API Key应妥善保管,避免泄露到版本控制系统。
## 核心能力

- **三步上传流程**：Create → Upload Part → Complete 的标准化上传流程，支持单分片上传
- **默认编码配置**：使用平台默认编码参数快速上传，仅需提供标题
- **HLS 流媒体输出**：上传完成后服务端转码为 HLS 格式，返回流媒体播放链接
- **API Key 认证**：通过 stream-public-key 与 stream-secret-key 进行身份验证
### 三步上传流程

执行三步上传流程操作,处理用户输入并返回结果。

**输入**: 用户提供三步上传流程所需的参数和指令。

**输出**: 返回三步上传流程的处理结果。

- 执行`三步上传流程`操作，处理输入数据并返回结果
- 验证执行结果，确认输出符合预期格式
- 参考`三步上传流程`相关配置参数进行设置
### 默认编码配置

执行默认编码配置操作,处理用户输入并返回结果。

**输入**: 用户提供默认编码配置所需的参数和指令。

**输出**: 返回默认编码配置的处理结果。

- 执行`默认编码配置`操作，处理输入数据并返回结果
- 验证执行结果，确认输出符合预期格式
- 参考`默认编码配置`相关配置参数进行设置
### HLS 流媒体输出

执行HLS 流媒体输出操作,处理用户输入并返回结果。

**输入**: 用户提供HLS 流媒体输出所需的参数和指令。

**输出**: 返回HLS 流媒体输出的处理结果。

- 执行`HLS 流媒体输出`操作，处理输入数据并返回结果
- 验证执行结果，确认输出符合预期格式
- 参考`HLS 流媒体输出`相关配置参数进行设置
### 技术细节

| 组件 | 说明 | 关键参数 |
|:-----|:-----|:---------|
| `parser` | 解析输入指令 | `format`, `encoding` |
| `processor` | 执行核心处理逻辑 | `mode`, `timeout` |
| `output` | 格式化输出结果 | `format`, `encoding` |

### 能力覆盖范围

本skill还覆盖以下能力场景: AIOZ、以默认配置上传音、频文件、适合快速发布、的音频上传技能免、通过三步流程、将本地音频文件上、流媒体平台、支持默认快速上传、使用默认编码配置、上传完成后返回、适用于播客发布、语音内容托管等基、础场景、本免费版仅支持默。这些能力在上述核心功能中均有对应处理逻辑。
## 使用流程

1. **环境确认**: 确认Agent平台已加载本skill，检查依赖说明中的环境要求
2. **指令输入**: 向Agent描述需要执行的任务，引用`audio-upload-aioz-stream-free`的相关能力
3. **执行处理**: Agent按照核心能力章节的指令执行任务
4. **结果验证**: 检查输出结果是否符合预期，参考错误处理章节处理异常

### 命令参数说明

- `-H`: 命令参数,用于指定操作选项
- `-Range`: 命令参数,用于指定操作选项
- `-X`: 命令参数,用于指定操作选项
- `-Type`: 命令参数,用于指定操作选项
- `-F`: 命令参数,用于指定操作选项

### 命令参数说明

- `-Type`: 命令参数,用于指定操作选项
- `-H`: 命令参数,用于指定操作选项
- `-F`: 命令参数,用于指定操作选项
- `-X`: 命令参数,用于指定操作选项
- `-Range`: 命令参数,用于指定操作选项

### 命令参数说明

- `-H`: 命令参数,用于指定操作选项
- `-F`: 命令参数,用于指定操作选项
- `-Range`: 命令参数,用于指定操作选项
- `-X`: 命令参数,用于指定操作选项
- `-Type`: 命令参数,用于指定操作选项

### 命令参数说明

- `-F`: 命令参数,用于指定操作选项
- `-Type`: 命令参数,用于指定操作选项
- `-H`: 命令参数,用于指定操作选项
- `-Range`: 命令参数,用于指定操作选项
- `-X`: 命令参数,用于指定操作选项

### 命令参数说明

- `-H`: 命令参数,用于指定操作选项
- `-F`: 命令参数,用于指定操作选项
- `-Range`: 命令参数,用于指定操作选项
- `-Type`: 命令参数,用于指定操作选项
- `-X`: 命令参数,用于指定操作选项

### 命令参数说明

- `-X`: 命令参数,用于指定操作选项
- `-F`: 命令参数,用于指定操作选项
- `-Range`: 命令参数,用于指定操作选项
- `-Type`: 命令参数,用于指定操作选项
- `-H`: 命令参数,用于指定操作选项

### 命令参数说明

- `-Type`: 命令参数,用于指定操作选项
- `-X`: 命令参数,用于指定操作选项
- `-F`: 命令参数,用于指定操作选项
- `-H`: 命令参数,用于指定操作选项
- `-Range`: 命令参数,用于指定操作选项

### 命令参数说明

- `-H`: 命令参数,用于指定操作选项
- `-Type`: 命令参数,用于指定操作选项
- `-Range`: 命令参数,用于指定操作选项
- `-X`: 命令参数,用于指定操作选项
- `-F`: 命令参数,用于指定操作选项

### 命令参数说明

- `-X`: 命令参数,用于指定操作选项
- `-H`: 命令参数,用于指定操作选项
- `-F`: 命令参数,用于指定操作选项
- `-Type`: 命令参数,用于指定操作选项
- `-Range`: 命令参数,用于指定操作选项

## 适用场景

### 场景一：播客节目快速发布

播客创作者需要将录制好的音频节目快速上传到流媒体平台分发。使用默认上传方式，仅提供节目标题即可完成上传并获取 HLS 播放链接，嵌入播客网站或分发给订阅者。

### 场景二：语音内容托管

教育或媒体机构需要将语音讲座、会议录音等内容上传到流媒体平台托管。使用默认上传方式快速完成上传，获取 HLS 播放链接分发给听众，适合对编码参数无特殊要求的日常内容托管。

### 场景三：音频资料归档

个人或团队需要将音频资料上传至流媒体平台备份托管。通过默认上传方式快速完成上传，获取播放链接便于后续访问与分享。

## 使用案例

### 案例一：播客节目默认上传

用户提供音频文件路径与节目标题"科技脱口秀第50期"。流程执行：调用 create 接口创建 type 为 audio 的音频对象，获取 AUDIO_ID；计算文件 MD5 哈希与大小，通过 part 接口上传文件分片；调用 complete 接口触发转码；查询音频详情获取 HLS 播放链接返回用户。用户将链接嵌入播客网站供订阅者收听。

### 案例二：语音讲座上传

用户提供语音讲座音频文件路径与标题"产品方法论第三讲"。流程执行：调用 create 接口创建音频对象；计算文件哈希并上传分片；调用 complete 接口完成上传并触发转码；查询详情获取 HLS 播放链接。用户将链接分享给学员在线收听。

## 响应处理规范

1. 解析 create 接口的 JSON 响应，提取 `data.id` 作为 AUDIO_ID
2. 计算音频文件的 MD5 哈希值
3. 通过 part 接口上传文件分片，附带 hash 与 Content-Range 头
4. 调用 complete 接口完成上传并触发转码
5. 查询音频详情获取流媒体播放链接
6. 将播放链接返回用户
7. 若音频仍在转码中（状态为 transcoding），告知用户稍后查询

## 异常处理


### 401 认证失败

API 返回 401 状态码，说明 stream-public-key 或 stream-secret-key 无效。处理方式：提示用户核对 AIOZ Stream 控制台中的公钥与私钥是否正确复制，确认密钥未过期或被撤销。重新提供正确的密钥后执行ping命令测试网络连通性,检查防火墙和代理设置连接后重新执行命令上传流程。

### 400 请求格式错误

API 返回 400 状态码，说明请求体格式不符合接口要求。处理方式：检查 create 接口的 JSON 请求体结构，确认 type 字段为 "audio"，title 字段已正确填写。重新构造请求后执行ping命令测试网络连通性,检查防火墙和代理设置连接后重新执行命令。

### Content-Range 头缺失或格式错误

上传分片时缺少 Content-Range 头或格式不符合 `bytes {start}-{end}/{total_size}` 规范。处理方式：确认上传前正确计算 FILE_SIZE 与 END_POS，单分片上传时 start 为 0、end 为 file_size-1。重新构造请求头后执行ping命令测试网络连通性,检查防火墙和代理设置连接后重新执行命令上传。

### 转码未完成

查询音频详情时状态为 transcoding，尚未生成流媒体播放链接。处理方式：告知用户音频正在转码中，播放链接需等待转码完成后才能获取。建议用户间隔一段时间后重新查询音频详情。

### 网络超时或连接中断

上传过程中网络超时或连接中断，导致分片上传未完成。处理方式：执行ping命令测试网络连通性,检查防火墙和代理设置连接稳定性，确认 AIOZ Stream API 域名 `api-w3stream.attoaioz.cyou` 可达。网络恢复后重新执行上传流程。

## 常见问题

### Q1：如何获取 AIOZ Stream 的 API 密钥？

注册并登录 AIOZ Stream 平台后，在控制台的 API 设置或开发者页面创建 API 密钥。系统会生成一对 stream-public-key（公钥）与 stream-secret-key（私钥）。密钥作为 HTTP 请求头附加到所有 API 调用中，需妥善保管避免泄露。

### Q2：音频上传后为什么没有 mp4_url 字段？

AIOZ Stream 的音频类型输出仅提供 HLS 流媒体链接，不生成 mp4_url 字段。音频内容以自适应流媒体格式分发，由播放器根据网络状况动态选择码率。如需直接下载音频文件，需在本地保留原始文件。

### Q3：免费版与付费版有什么区别？

免费版仅支持默认上传方式，使用平台默认编码配置，适合快速发布场景。付费版支持自定义编码配置（质量预设、码率、采样率、标签、元数据）、多档位质量输出、DASH 格式、多分片上传等高级能力。

### Q4：转码需要多长时间？

转码耗时取决于音频时长与服务端负载。短音频通常在数分钟内完成转码。上传完成后通过查询音频详情接口检查转码状态，状态从 transcoding 变为 ready 即表示完成，此时可获取播放链接。

## 错误处理


| 错误场景 | 原因 | 处理方式 |
|---------|------|---------|
| LLM响应超时或无响应 | 网络延迟或模型负载过高 | 执行ping命令测试网络连通性,检查防火墙和代理设置连接，执行ping命令测试网络连通性,检查防火墙和代理设置连接后重新执行命令请求；确认Agent平台LLM服务正常 |
| 输入内容格式不正确 | 用户输入不符合skill预期格式 | 检查输入是否符合skill使用说明中的格式要求，参考示例章节 |
| 执行结果与预期不符 | 指令描述不够明确或上下文不足 | 提供更详细的指令描述，补充必要的上下文信息 |
| 命令执行失败 | 运行环境不满足要求或权限不足 | 确认运行环境符合依赖说明中的要求；检查命令权限设置 |

## 已知限制

- 仅支持默认上传方式，不支持自定义编码配置
- 音频输出仅提供 HLS 流媒体链接，不提供 mp4_url 直接下载链接
- 上传流程需要三次 API 调用，无法通过单次请求完成上传
- 转码在服务端异步进行，上传完成后需等待转码完成才能获取播放链接
- API 密钥以明文 HTTP 请求头传输，需确保调用环境的安全性
- API 域名需网络可达，受限网络环境可能无法访问

## 升级提示

本免费版支持默认上传方式与基础编码配置。升级付费版可解锁以下能力：

- 自定义编码配置（质量预设、码率、采样率、声道、语言标签）
- 多档位质量输出（standard、good、highest、lossless）
- DASH 流媒体格式支持
- 多分片上传与断点续传
- 标签与元数据管理
- 完整异常处理与编码配置参考

如需以上能力，请升级至付费版 audio-upload-aioz-stream。