核心功能: 本技能提供中文交互、时使用、化工作流场景等能力。

AIOZ 音频上传（免费版）

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

认证配置

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

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

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

完整上传流程

领先步：创建音频对象

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

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 哈希：

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 请求头：

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 哈希。

第三步：完成上传

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

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'

获取播放链接

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

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配置方式:

export API_KEY="${API_KEY:?请设置环境变量}"

配置后需重启会话或开启新终端生效。API Key应妥善保管,避免泄露到版本控制系统。

核心能力

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

三步上传流程

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

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

默认编码配置

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

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

HLS 流媒体输出

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

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

使用流程

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

适用场景

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

播客创作者需要将录制好的音频节目快速上传到流媒体平台分发。使用默认上传方式，仅提供节目标题即可完成上传并获取 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。

安全注意事项

风险类型	防范措施
API密钥泄露	通过环境变量配置，禁止硬编码到代码或配置文件中
命令执行风险	仅执行白名单命令，避免拼接用户输入到命令行参数中
网络通信安全	使用HTTPS协议，验证SSL证书有效性
敏感数据暴露	输出结果中不包含密钥、令牌等敏感信息

使用前请确认已阅读依赖说明章节，确保运行环境满足安全要求。

效率量化分析

操作场景	手动耗时	自动化耗时	效率提升
文件解析与提取	5-10分钟/个	<5秒/个	60-120x
批量文件处理(100个)	8-16小时	<5分钟	96-192x
API调用与响应解析	2-3分钟/次	<1秒/次	120-180x
多接口数据聚合	15-30分钟	<10秒	90-180x
命令执行与结果收集	3-5分钟/次	<2秒/次	90-150x
重复任务批量执行	因任务而异	线性缩减	5-50x
错误排查与修复	10-30分钟	<30秒	20-60x

差异化对比

对比维度	本技能	传统手动方式	通用脚本工具
自动化程度	全流程自动	完全手动	部分自动
错误处理	内置错误恢复	依赖人工经验	基本try-catch
可复用性	参数化配置	一次性脚本	模板化
安全合规	内置安全检查	无安全保障	无安全保障
适用场景	核心功能	通用场景	通用场景

核心功能

• 自动化执行: 基于指令驱动的自动化流程
• 文件处理: 支持多种文件格式的读取、解析和写入操作
• API集成: 通过标准化接口调用外部服务并处理响应
• 命令执行: 在安全沙箱中执行系统命令并收集结果
• 信息检索: 快速搜索和过滤目标数据