> 功能说明: 本技能涵盖 自动化配置和灵活的参数设置、多种应用场景、时使用、化配置和灵活的参数设置 等核心能力。

AIOZ 音频上传

通过 AIOZ Stream API 将本地音频文件上传至 AIOZ 流媒体平台。完整上传流程包含三次 API 调用：创建音频对象 → 上传文件分片 → 完成上传。上传完成后服务端自动触发转码，最终返回 HLS/DASH 流媒体播放链接.

输入定义

专业版增强能力

认证配置

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

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

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

上传方式选择

用户发起上传请求时，询问选择以下方式：

默认上传（快速）：仅提供标题即可创建音频对象并上传，使用默认编码配置，适合快速发布场景.
自定义上传（高级）：完整配置编码参数，包括质量预设、码率、采样率、标签、元数据等，适合对音质有明确要求的发布场景.

完整上传流程

领先步：创建音频对象

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

curl -s -X POST "${AIOZ_API_URL:?请设置环境变量}/api/videos/create" \
  -H "stream-public-key: ${STREAM_PUBLIC_KEY:?请设置环境变量}" \
  -H "stream-secret-key: ${STREAM_SECRET_KEY:?请设置环境变量}" \
  -H 'Content-Type: application/json' \
  -d '{
    "title": "AUDIO_TITLE",
    "type": "audio"
  }'

自定义上传：包含完整编码配置.

请设置环境变量}/api/videos/create" \
  -H 'Content-Type: application/json' \
  -d '{
    "title": "AUDIO_TITLE",
    "type": "audio",
    "description": "DESCRIPTION",
    "is_public": true,
    "tags": ["tag1", "tag2"],
    "metadata": [
      {"key": "KEY", "value": "VALUE"}
    ],
    "qualities": [
      {
        "resolution": "highest",
        "type": "hls",
        "container_type": "mpegts",
        "audio_config": {
          "codec": "aac",
          "bitrate": 320000,
          "channels": "2",
          "sample_rate": 48000,
          "language": "en",
          "index": 0
        }
      },
      {
        "resolution": "standard",
        "type": "hls",
        "container_type": "mpegts",
        "audio_config": {
          "codec": "aac",
          "bitrate": 128000,
          "channels": "2",
          "sample_rate": 44100,
          "language": "en",
          "index": 0
        }
      }
    ]
  }'

从响应中提取 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 请求头：

请设置环境变量}/api/videos/AUDIO_ID/part" \
  -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；多分片上传时按分片调整 start/end 位置。表单字段：file 为音频文件二进制，index 为分片序号（单分片为 0），hash 为分片的 MD5 哈希.

第三步：完成上传

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

curl -s -X GET "${AIOZ_API_URL:?请设置环境变量}/api/videos/AUDIO_ID/complete" \
  -H 'accept: application/json' \

调用后上传流程结束，服务端开始转码.

获取播放链接

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

curl -s "${AIOZ_API_URL:?请设置环境变量}/api/videos/AUDIO_ID" \

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

依赖与配置

运行环境

• 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="${API_KEY:?请设置环境变量}"

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

能力总览

• 三步上传流程：Create → Upload Part → Complete 的标准化上传流程，支持单分片与多分片上传
• 默认与自定义编码配置：默认上传快速发布，自定义上传精细控制质量预设、码率、采样率、声道、语言标签
• HLS/DASH 流媒体输出：上传完成后服务端转码为 HLS 或 DASH 格式，返回自适应流媒体播放链接
• 多质量预设支持：standard、good、highest、lossless 四档质量预设，适配不同播放场景
• 元数据与标签管理：支持自定义标签与键值对元数据，便于音频内容分类与检索
• 分片上传与断点续传：通过 Content-Range 头实现多分片上传，支持大文件分块传输

快速熟悉

1. 确认运行环境满足依赖说明中的要求
2. 在AI Agent对话中调用本技能,提供必要的输入参数
3. 检查输出结果,根据需要进行后续处理

> 详细的输入输出格式请参考下方章节说明。

编码配置参考

质量预设（resolution 字段）

• standard：标准质量，适合语音类内容
• good：良好质量，适合日常音乐播放
• highest：最高质量，适合高品质音乐发行
• lossless：无损质量，适合母带级存档

流媒体格式（type 字段）

• hls：HTTP Live Streaming，容器格式为 mpegts 或 mp4
• dash：Dynamic Adaptive Streaming，容器格式为 fmp4

音频编码参数

• codec：仅支持 aac
• bitrate：整数，单位 bits/sec（如 128000、256000、320000）
• channels：声道数，"2" 表示立体声
• sample_rate：采样率，可选值 8000、11025、16000、22050、32000、44100、48000、88200、96000
• language：BCP 47 语言代码（如 en、zh）
• index：音频流索引，默认 0

推荐码率

• 播客/语音：64000 - 128000 bps
• 标准音乐：128000 - 192000 bps
• 高品质音乐：192000 - 256000 bps
• 最高品质音乐：256000 - 320000 bps

推荐采样率

• 语音内容：22050 或 32000
• 音乐内容：44100 或 48000

场景说明

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

播客创作者需要将录制好的音频节目快速上传到流媒体平台分发。使用默认上传方式，仅提供节目标题即可完成上传并获取 HLS 播放链接，嵌入播客网站或分发给订阅者。适合追求发布效率、对编码参数无特殊要求的日常更新场景.

场景二：音乐作品高品质发行

音乐人或厂牌需要将音乐作品以高品质编码上传发布。使用自定义上传方式，配置 highest 质量预设、320kbps 码率、48000Hz 采样率，确保流媒体播放音质满足发行标准。同时通过 tags 与 metadata 字段标注曲目信息、专辑归属、版权声明，便于内容管理与检索.

场景三：语音内容多档位托管

教育或媒体机构需要为同一份语音内容提供多档位质量，适配不同网络环境的听众。使用自定义上传的 qualities 数组配置 standard 与 highest 两档 HLS 输出，低带宽听众播放标准档，高带宽听众播放高品质档，由播放器自适应切换.

场景四：音频内容批量归档

企业或机构需要将大量历史音频资料批量上传至流媒体平台归档托管。通过脚本化调用三步上传流程，配合 metadata 字段记录原始日期、来源、分类等归档元数据，实现音频资产的结构化托管与检索.

使用案例

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

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

案例二：音乐单曲自定义上传

用户提供音乐文件路径，要求以最高品质 HLS 格式上传，码率 320kbps，采样率 48000Hz，标签为"pop,2024"。流程执行：调用 create 接口，请求体包含 qualities 数组配置 highest 预设与完整 audio_config，tags 字段设为指定标签；获取 AUDIO_ID 后上传文件分片并完成转码；返回 HLS 播放链接。用户在音乐平台嵌入该链接供听众高品质播放.

案例三：有声书多档位上传

用户提供有声书音频文件，要求同时生成标准与最高两档 HLS 输出以适配不同网络环境。流程执行：调用 create 接口，qualities 数组包含两个质量配置（standard 档 128kbps/44100Hz，highest 档 256kbps/48000Hz），metadata 字段记录书籍章节信息；上传完成后返回 HLS 播放链接，播放器根据听众网络状况自适应选择档位.

响应处理规范

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

问题合集

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

注册并登录 AIOZ Stream 平台后，在控制台的 API 设置或开发者页面创建 API 密钥。系统会生成一对 stream-public-key（公钥）与 stream-secret-key（密钥）。公钥用于标识账户身份，密钥用于签名验证，两者均需妥善保管。密钥作为 HTTP 请求头（stream-public-key、stream-secret-key）附加到所有 API 调用中.

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

AIOZ Stream 的音频类型输出仅提供 HLS/DASH 流媒体链接，不生成 mp4_url 字段。这是因为音频内容以自适应流媒体格式分发，播放器根据网络状况动态选择码率档位。如需直接下载音频文件，需在本地保留原始文件，平台不提供音频文件的直接下载链接。视频类型上传后才会有 mp4_url 字段.

Q3：单分片上传与多分片上传如何选择？

单分片上传适合小文件（通常 100MB 以下），一次上传整个文件，start=0、end=file_size-1。多分片上传适合大文件，将文件分割为多个分片分别上传，每个分片有独立的 index、Content-Range 与 hash。多分片上传支持断点续传，单个分片失败只需重传该分片。根据文件大小与网络稳定性选择上传方式.

Q4：转码需要多长时间？

转码耗时取决于音频时长、编码配置复杂度与服务端负载。短音频（数分钟）通常在 1-2 分钟内完成转码；长音频（数小时如有声书）可能需要更长时间。多档位质量配置会增加转码工作量。上传完成后通过查询音频详情接口检查转码状态，状态从 transcoding 变为 ready 即表示完成，此时可获取播放链接.

Q5：支持哪些音频输入格式？

AIOZ Stream 服务端转码接受常见音频格式输入，包括 MP3、WAV、FLAC、AAC、OGG 等。上传后服务端统一转码为配置的 HLS 或 DASH 输出格式，音频编码为 AAC。输入格式不影响输出格式，但建议使用无损或高码率源文件以保证转码后的音质。避免使用已高度压缩的低码率文件作为源，以免二次压缩导致音质损失.

Q6：tags 与 metadata 字段有什么区别？

tags 是字符串数组，用于音频内容的分类标签，便于按主题检索与筛选，如 ["podcast", "tech"]。metadata 是键值对数组，每项包含 key 与 value 字段，用于记录结构化元数据，如章节信息、版权声明、原始日期等。tags 适合扁平分类，metadata 适合结构化属性记录。两者可在自定义上传时同时配置.

功能边界

• 音频输出仅提供 HLS/DASH 流媒体链接，不提供 mp4_url 直接下载链接
• 音频编码仅支持 AAC 编解码器，不支持其他编码格式
• 上传流程需要三次 API 调用，无法通过单次请求完成上传
• 转码在服务端异步进行，上传完成后需等待转码完成才能获取播放链接
• API 密钥通过请求头传输，需确保调用环境的安全性
• 多分片上传需自行管理分片边界与序号，接口不提供分片管理能力
• 自定义编码配置的 qualities 数组中每个质量档位独立转码，增加转码耗时
• API 端点需网络可达，受限网络环境可能无法访问

输出规范

{
  "success": true,
  "data": {
    "result": "AIOZ音频上传处理结果",
    "execution_time": "0.5s",
    "metadata": {
      "version": "1.0",
      "processor": "audio-upload-aioz-stream"
    }
  },
  "execution_log": [
    "解析输入参数",
    "执行核心处理",
    "格式化输出结果"
  ],
  "error": null
}

创新亮点

效率提升量化分析

差异化对比

核心痛点解决

诊断与修复

安全规范

1. 使用HTTPS协议进行数据传输，确保数据安全。
2. API密钥应保密，避免泄露给未授权人员。
3. 定期检查API密钥权限，避免权限滥用。
4. 对上传的音频文件进行安全检查，防止恶意文件上传。
5. 设置合理的权限和访问控制，防止未授权访问。

安全风险防范

错误应对策略

针对AIOZ音频上传使用中可能遇到的常见问题,提供以下排查方案:

AIOZ音频上传通用排查步骤

1. 检查输入参数: 确认所有必填参数已提供且格式正确
2. 查看日志输出: 定位具体错误行和异常类型
3. 验证环境配置: 确认依赖库版本和运行环境满足要求
4. 逐步调试: 缩小问题范围,隔离故障模块