说明：宿主若在环境中注入 ARK_SKILL_API_BASE / ARK_SKILL_API_KEY（例如供其他 Skill 走 SkillHub 网关），与本 Skill 的 AMK_API_KEY、 ARK_API_KEY（视频理解） 相互独立，请勿混淆。

⚠️ 严格执行：必须先完成 环境检查；环境缺失须提示用户，不可跳过。

<SKILL_DIR> 为 byted-mediakit-tools 所在目录。 当前方法返回的 链接仅供下载，不支持播放能力 禁止修改任何返回数据信息，如 play_url 、 request_id 、 task_id 等 用户明确声明需要重新执行时：除 understand_video_content 外的方法需 生成新的 client_token（不要复用上一次的 client_token），避免命中上次的幂等结果

火山引擎 AI MediaKit 音视频处理工具集#

概览#

本工具集基于火山引擎 AI MediaKit 提供一站式音视频处理能力，包括：

• 🎬 视频理解：AI 分析视频内容，生成自然语言描述
• ✂️ 音视频剪辑：精确裁剪音视频时长
• 🔗 音视频拼接：拼接多个片段，支持转场效果
• 🎵 音频提取：从视频中提取音频轨道
• 🖼️ 画质增强：提升视频画质、分辨率、帧率
• 🎬 文生视频：图片生成视频，支持动画效果
• 🎧 音视频合成：合成新的音轨与视频

---

获取密钥#

在开始使用前，请先获取必要的 API 密钥：

• AI MediaKit 控制台： https://console.volcengine.com/imp/ai-mediakit/
• 方舟模型与密钥： https://console.volcengine.com/ark/region:ark+cn-beijing/model/detail?Id=doubao-seed-1-8

---

快速开始#

1. 环境配置#

在 <SKILL_DIR>/.env 中配置环境变量（首次使用会自动创建模板）：

bash

# AMK API Key (必填) - https://console.volcengine.com/imp/ai-mediakit/
AMK_API_KEY=your_amk_api_key_here
# AMK 环境取值 prod 或 boe
AMK_ENV=prod
# 是否启用 client_token 自动注入（用于幂等）
AMK_ENABLE_CLIENT_TOKEN=false
# 方舟 密钥（可选，仅使用视频理解功能时必须配置）
ARK_API_KEY=your_ark_api_key_here
# 方舟 模型ID（可选，仅使用视频理解功能时必须配置）
ARK_MODEL_ID=doubao-seed-1-8

2. 依赖安装#

bash

cd <SKILL_DIR>/scripts
python3 -m venv .venv
. .venv/bin/activate
python -m pip install -U pip
python -m pip install -r requirements.txt

---

核心功能#

同步能力（立即返回结果）#

能力说明understand_video_content视频内容理解，使用 AI 分析视频并生成自然语言描述

异步能力（默认自动等待结果）#

能力说明trim_media_duration裁剪音视频时长，精确到毫秒concat_media_segments拼接多个音视频片段，支持转场效果extract_audio从视频中提取音频轨道，支持 mp3/m4a 格式enhance_video视频画质增强，支持超分、插帧等image_to_video图片生成视频，支持动画和转场mux_audio_video音视频合成，支持时长对齐

辅助能力#

能力说明query_task查询异步任务执行状态和结果

---

使用示例#

视频理解#

bash

./byted-mediakit-tools.sh understand_video_content \
  --video_url "https://example.com/video.mp4" \
  --prompt "总结视频内容" \
  --fps 1

视频裁剪#

bash

# 裁剪前 10 秒
./byted-mediakit-tools.sh trim_media_duration \
  --type video \
  --source "https://example.com/video.mp4" \
  --start_time 0 \
  --end_time 10

音视频拼接#

bash

./byted-mediakit-tools.sh concat_media_segments \
  --type video \
  --sources "https://example.com/1.mp4" "https://example.com/2.mp4"

音频提取#

bash

./byted-mediakit-tools.sh extract_audio \
  --video_url "https://example.com/video.mp4" \
  --format mp3

画质增强#

bash

./byted-mediakit-tools.sh enhance_video \
  --video_url "https://example.com/video.mp4" \
  --tool_version professional \
  --resolution 1080p

图片生成视频#

bash

./byted-mediakit-tools.sh image_to_video \
  --images "image_url=https://example.com/1.jpg,duration=3,animation_type=zoom_in" \
           "image_url=https://example.com/2.jpg,duration=3,animation_type=pan_left"

音视频合成#

bash

./byted-mediakit-tools.sh mux_audio_video \
  --video_url "https://example.com/video.mp4" \
  --audio_url "https://example.com/audio.mp3" \
  --is_audio_reserve false

异步任务（不等待结果）#

bash

# 使用 --no-wait 立即返回 task_id
./byted-mediakit-tools.sh --no-wait trim_media_duration \
  --type video \
  --source "https://example.com/video.mp4" \
  --start_time 0 \
  --end_time 10

# 查询任务结果
./byted-mediakit-tools.sh query_task --task_id "amk-xxx-xxx"

---

响应格式#

同步响应（视频理解）#

json

{
  "status": "success",
  "result": {
    "choices": [
      {
        "role": "assistant",
        "content": "视频内容分析结果..."
      }
    ]
  }
}

异步响应（默认自动等待）#

json

{
  "task_id": "amk-tool-extract-audio-xxxxxxxxxxxxxx",
  "duration": 82.454056,
  "play_url": "https://example.vod.cn-north-1.volcvideo.com/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.mp3?preview=1&auth_key=***",
  "request_id": "20260401xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "status": "completed",
  "task_type": "extract-audio"
}

异步响应（--no-wait）#

json

{
  "status": "pending",
  "task_id": "amk-xxx-xxx",
  "message": "任务已提交，已跳过等待，可调用 query_task 接口传入 task_id 查询结果",
  "query_example": "./byted-mediakit-tools.sh query_task --task_id amk-xxx-xxx"
}

错误响应#

json

{
  "status": "failed/canceled/timeout",
  "task_id": "amk-xxx-xxx",
  "message": "错误详情"
}

---

详细文档#

各功能的详细参数说明请参考 reference/ 目录下的对应文档：

能力文档链接understand_video_contentreference/understand_video_content.mdquery_taskreference/query_task.mdconcat_media_segmentsreference/concat_media_segments.mdenhance_videoreference/enhance_video.mdextract_audioreference/extract_audio.mdimage_to_videoreference/image_to_video.mdmux_audio_videoreference/mux_audio_video.mdtrim_media_durationreference/trim_media_duration.md统一响应格式reference/common_response.md

---

注意事项#

1. 返回链接：所有返回的 play_url 等链接仅供下载，不支持直接播放
2. 幂等性：重新执行任务时，请确保生成新的 client_token（ AMK_ENABLE_CLIENT_TOKEN=true 时自动处理）
3. 视频理解：使用视频理解功能必须配置 ARK_API_KEY 和 ARK_MODEL_ID
4. 超时处理：大文件处理可能耗时较长，建议使用 --no-wait 配合 query_task 轮询

---

© 北京火山引擎科技有限公司 2026 版权所有