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

依赖项

API Key 配置

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

可用性分类

• 分类: MD+EXEC（）

API Key配置方式:

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 流媒体输出相关配置参数进行设置

技术细节

能力覆盖范围

本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 即表示完成，此时可获取播放链接。

错误处理

已知限制

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

升级提示

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

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

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