本文面向开发者,详细介绍如何通过 API 调用 Aideo Agent,将强大的视频 AI 能力无缝集成到您的业务系统或应用中。您将了解到 API 的核心调用流程、参数配置,并通过丰富的代码示例快速上手。
说明
在开始之前,建议您先阅读 Aideo Agent 的快速开始指南,了解 Aideo Agent 的核心功能、应用场景和计费规则,并通过控制台操作体验各项 AI 能力的实际效果。
前提条件
实现流程
API 接入的核心流程分为两步:
- 提交任务:调用
SubmitAideoTaskAsync 接口,提交一个异步的智能处理任务。 - 获取结果:轮询
GetAideoTaskResult 接口,获取任务的处理结果。
步骤 1:提交任务
调用 SubmitAideoTaskAsync 接口,提交一个异步的智能处理任务。该接口提供以下两种调用方式。
任务提交方式 | 核心参数 | 说明 |
|---|
自然语言驱动 | Prompt(必填) | 您只需通过 Prompt 参数提供简单的自然语言指令,Agent 将自动理解您的意图,分析并调用底层的 AI 能力(如视频翻译、字幕擦除等)来完成任务。 |
指定技能驱动 | - SkillType(必填)
- SkillParams(是否必填取决于 SkillType)
| 您可以通过 SkillType 明确指定调用哪个具体的 AI 能力,并通过 SkillParams 传入该能力所需的精确参数。 |
请求示例 1:使用自然语言驱动 AI 视频翻译任务
通过 Prompt 让 Agent 自动分析并执行一个包含字幕翻译、语音翻译和口型对齐的复杂视频翻译任务。
POST https://vod.volcengineapi.com?Action=SubmitAideoTaskAsync&Version=2025-03-03
{
"SpaceName": "your_space_name",
"MultiInputs": [
{ "Type": "Vid", "Vid": "your_video_id" }
],
"Prompt": "帮我翻译这个视频从中文翻译成英语。字幕和语音都要翻译,字幕压制到视频中。"
}
请求示例 2:使用指定技能驱动 AI 高光分析任务
直接调用“高光剪辑”技能,对输入的视频进行故事线维度的分析,并自动剪辑生成一个时长在 1-3 分钟、且开头包含最精彩片段的高光集锦视频。
POST https://vod.volcengineapi.com?Action=SubmitAideoTaskAsync&Version=2025-03-03
{
"SpaceName": "your_space_name",
"MultiInputs": [
{"Type": "Vid", "Vid": "your_drama_vid_1"}
],
"SkillType": "Highlight",
"SkillParams": "{\"HighlightCuts\":{\"MinDuration\":60,\"MaxDuration\":180},\"OpeningHook\":{\"WithOpeningHook\":true}}"
}
步骤 2:获取结果
- 轮询
GetAideoTaskResult 接口并传入步骤 1 中获取的 TaskId 获取任务结果。 - 检查返回结果中的顶层
Status 字段。当其值为 Completed 时,表示任务已完成。 - 在
ApiResponses 数组中查找与您指定的 SkillType 对应的结果。解析逻辑如下:
- 遍历
ApiResponses 数组。 - 找到
VodTaskType 字段与您提交时 SkillType 同名的那个对象。 - 解析该对象内部与
VodTaskType 同名的结果数据(如 AITranslation, Highlight)。
参考信息
技能参数 SkillParams 详解
当您调用 SubmitAideoTaskAsync 接口通过指定技能驱动(SkillType + SkillParams)时,SkillParams 字符串需要根据不同的 SkillType 构造成对应的 JSON 结构。
SkillType | SkillParams 是否必填 | SkillParams 内部结构 | SkillParams 示例 |
|---|
AITranslation | 必填 | 包含以下对象: | 将一个中文视频,通过 ASR 识别出语音,翻译成英文字幕和英文语音,并生成一个带英文硬字幕的新视频。 {
"SpaceName": "your_space_name",
"MultiInputs": [
{ "Type": "Vid", "Vid": "your_video_id" }
],
"SkillType": "AITranslation",
"SkillParams": "{\"TranslationConfig\":{\"SourceLanguage\":\"zh\",\"TargetLanguage\":\"en\",\"TranslationTypeList\":[\"SubtitleTranslation\",\"VoiceTranslation\"]},\"OperatorConfig\":{\"SubtitleRecognitionConfig\":{\"RecognitionType\":\"ASR\"}},\"SubtitleConfig\":{\"IsHardSubtitle\":true,\"IsEraseSource\":false,\"FontSize\":24,\"MarginV\":0.1}}"
}
|
Highlight | 必填 | 包含以下对象: | 对输入视频进行故事线维度的分析,并自动剪辑生成一个时长在 1-3 分钟、且开头包含最精彩片段的高光集锦。 {
"SpaceName": "your_space_name",
"MultiInputs": [
{"Type": "Vid", "Vid": "your_drama_vid_1"}
],
"SkillType": "Highlight",
"SkillParams": "{\"HighlightCuts\":{\"MinDuration\":60,\"MaxDuration\":180},\"OpeningHook\":{\"WithOpeningHook\":true}}"
}
|
Vision | 必填 | 结构同 OperationTaskVision 对象。 | 利用多模态大模型,结合视频画面和语音内容,对整个视频进行深度理解,并根据 Prompt 的要求生成一段详细的文字描述。 {
"SpaceName": "your_space_name",
"MultiInputs": [
{ "Type": "Vid", "Vid": "your_video_id" }
],
"SkillType": "Vision",
"SkillParams": "{\"Prompt\":\"[角色]\\n假设你是一个专业的视频内容分析专家,擅长通过视频抽帧图片和音频转译文本,精准把握视频核心内容。\\n[任务目标]\\n请根据输入的视频抽帧图片信息以及音频转译文本,撰写视频内容梗概。要求涵盖视频主要情节、关键人物以及核心事件,语言简洁流畅,逻辑清晰。\\n[限制]\\n视频内容梗概需要限制在1000字\\n输入内容\\n视频音频转译文本\\n{{PLACEHOLDER_ASR_RESULT}}\\n视频分段描述文本\\n{{PLACEHOLDER_VIDEO_CLIP_RESULT}}\\n输出格式\\n请严格按照以下 JSON 格式输出,不要输出其他额外内容:\\n{\"视频内容梗概\":\"[在此处填写概括后的视频内容,包含主要情节、关键人物、核心事件]\"}"}"
}
|
VCreative | 必填 | 包含 Text(剪辑提示词)字段。 | 将输入的多张图片,按顺序拼接成一个指定总时长的视频。 {
"SpaceName": "your_space_name",
"MultiInputs": [
{ "Type": "Vid", "Vid": "your_image_mid_1" }, // 此处传入图片的 Mid
{ "Type": "Vid", "Vid": "your_image_mid_2" }, // 此处传入图片的 Mid
{ "Type": "Vid", "Vid": "your_image_mid_3" } // 此处传入图片的 Mid
],
"SkillType": "VCreative",
"SkillParams": "{\"Text\":\"将图片1、2、3拼接为10s的视频\"}"
}
|
将输入的多个视频素材拼接生成一个新视频。 {
"SpaceName": "your_space_name",
"MultiInputs": [
{ "Type": "Vid", "Vid": "your_video_id_1" },
{ "Type": "Vid", "Vid": "your_video_id_2" }
],
"SkillType": "VCreative",
"SkillParams": "{\"Text\":\"将视频1、2拼接到一起\"}"
}
|
将一个视频素材的画面和一个独立的音频素材合并,生成一个音画合一的新视频。 {
"SpaceName": "your_space_name",
"MultiInputs": [
{ "Type": "Vid", "Vid": "your_video_id_for_visuals" }, // 用于画面的视频
{ "Type": "Vid", "Vid": "your_audio_id_for_sound" } // 用于声音的音频
],
"SkillType": "VCreative",
"SkillParams": "{\"Text\":\"将输入视频和音频合成到一起\"}"
}
|
Erase | 可选 | 结构同 OperationTaskErase 对象 | 自动检测并擦除视频画面中的硬字幕,并生成一个不带字幕的、干净的新视频。 {
"SpaceName": "your_space_name",
"MultiInputs": [
{ "Type": "Vid", "Vid": "your_video_id" }
],
"SkillType": "Erase",
"SkillParams": "{\"Mode\":\"Auto\",\"Auto\":{\"Type\":\"Subtitle\"},\"NewVid\":true}"
}
|