AIOZ Stream 音频上传

使用 API 密钥认证，快速将音频上传至 AIOZ Stream API。完整上传流程需调用 3 个 API：创建 → 上传分片 → 完成。

适用场景

• 用户希望在 AIOZ Stream 上上传或创建音频
• 用户提及“上传音频”、“创建音频”、“aioz stream 音频”等关键词
• 用户希望获取其音频的 HLS 流媒体链接

认证方式

本技能采用 API 密钥认证。用户必须提供以下两项：

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

若用户未提供上述密钥，请主动向其索取。这些密钥将在所有 API 请求中作为 HTTP Header 发送。

使用选项

当用户希望上传音频时，请引导其选择以下任一方式：

选项 1：默认上传（快捷）

以最小化配置创建音频对象——仅需指定标题，随后上传文件。

示例用户输入：

“上传音频文件 /path/to/audio.mp3，标题为 My Podcast”

选项 2：自定义上传（高级）

以完整编码配置创建音频对象，支持质量预设、码率、采样率、标签、元数据等参数，随后上传文件。

示例用户输入：

“上传音频并应用自定义配置：标题 My Podcast，最高质量 HLS，320kbps，48000Hz，标签 podcast,tech”

完整上传流程（三步）

步骤 1：创建音频对象

默认配置：

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"
  }'

自定义配置（含编码参数）：

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",
    "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。

步骤 2：上传文件分片

将实际音频文件的二进制内容上传至已创建的音频对象。

首先，获取文件大小并计算 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))

# 计算 MD5 哈希值
HASH=$(md5sum /path/to/audio.mp3 | awk '{print $1}')

然后通过 multipart form-data 方式上传，并携带 Content-Range Header：

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 Header 是上传成功的必要条件。格式为：bytes {start}-{end}/{total_size}，其中：

• 单分片上传时：start=0，end=file_size-1，total_size=file_size
• 多分片上传时：需为每个分片分别设置对应的 start 与 end 值

form-data 字段说明：

• file：音频文件二进制内容（使用 @/path/to/file 语法）
• index：0（单分片上传时固定为 0；多分片上传时按顺序递增）
• hash：该分片文件的 MD5 哈希值

步骤 3：完成上传

文件分片上传成功后，调用完成接口以最终确认上传：

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'

此操作将触发转码任务。此时上传流程即视为成功。

上传完成后 — 获取音频链接

完成上传后，调用详情接口获取流媒体 URL：

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 URL 并返回给用户。

重要说明：音频输出不包含 mp4_url 字段，仅提供 HLS/DASH 流媒体链接。

自定义上传配置参考

质量预设（resolution 字段）：

• standard — 标准质量
• good — 良好质量
• highest — 最高质量
• lossless — 无损质量

流媒体格式（type 字段）：

• hls — HTTP Live Streaming（容器格式：mpegts 或 mp4）
• dash — Dynamic Adaptive Streaming（容器格式：fmp4）

音频编码配置：

• codec：aac（唯一支持的编码器）
• bitrate：整型数值，单位为 bit/sec（例如：128000、256000、320000）
• channels："2"（立体声）
• sample_rate：8000、11025、16000、22050、32000、44100、48000、88200、96000
• language：BCP 47 语言代码（例如：en、vi）
• index：0

推荐码率：

• 播客/人声：64000 – 128000 bps
• 音乐标准：128000 – 192000 bps
• 音乐高质：192000 – 256000 bps
• 音乐最高：256000 – 320000 bps

推荐采样率：

• 人声：22050 或 32000
• 音乐：44100 或 48000

响应处理流程

1. 解析创建接口的 JSON 响应 → 提取 data.id
2. 计算音频文件的 MD5 哈希值
3. 携带哈希值上传文件分片
4. 调用完成接口
5. 获取音频详情 → 提取流媒体 URL
6. 将音频链接返回给用户
7. 若音频仍处于转码中（status: transcoding），提示用户当前状态，并建议稍后重试查询

错误处理

• 401：API 密钥无效 — 提示用户检查公钥与密钥是否正确
• 400：请求格式错误 — 检查请求体结构是否符合要求
• 500：服务端错误 — 建议用户稍后重试

示例交互流程

1. 用户：“将我的音频上传到 AIOZ Stream”
2. 若尚未获知 API 密钥，则向用户索取（公钥 + 密钥）
3. 向用户索取音频文件路径
4. 询问：“请选择上传方式：默认上传（快捷）还是自定义配置？”
   • 若选默认：仅需用户提供标题
   • 若选自定义：进一步收集标题、质量预设、码率、采样率、标签等参数
5. 步骤 1： 创建音频对象 → 获取 AUDIO_ID
6. 步骤 2： 计算文件哈希值，上传文件分片
7. 步骤 3： 调用完成接口
8. 获取音频详情 → 向用户返回流媒体 URL