AI MediaKit
AI MediaKit
API 参考
请输入
- 文档首页
AI MediaKit准备工作基础概念及准备工作
复制全文
下载 pdf基础概念及准备工作
文档反馈
问问助手本文档旨在介绍 AI MediaKit API 的通用概念和调用前必须完成的准备工作。理解这些基础知识，将帮助您更顺畅地集成我们的各项能力。
准备工作：获取并配置 API Key
API Key 是您调用 AI MediaKit 服务时用于身份认证的唯一凭证。API Key 信息高度敏感，泄露 API Key 可能导致您的服务配额被他人盗用，造成不必要的经济损失。因此我们建议您将 API Key 配置为环境变量，方便您合理安全地使用 API Key。AI MediaKit 支持两种类型的 API Key：
- 通用 API Key：你可以在访问控制（IAM）控制台创建通用 API Key，并在火山引擎所有支持 API Key 的服务中通用使用。该方式支持更灵活、更安全的权限管理；同时，你还可以在火山引擎费用中心按 API Key 查看工具用量和费用。创建方法参见 API Key 管理；分账配置方法请参见项目与队列管理。
- 专用 API Key：在 AI MediaKit 控制台创建的 API Key，仅对 AI MediaKit 服务生效。
通过 AI MediaKit 控制台获取 API Key
- 访问 AI MediaKit 控制台 API Key 管理页面。
- 单击创建 API Key 按钮。
- 在弹出的名称文本框中确认/更改 API Key 名称，然后单击创建。
- 创建成功后，您可以在 API Key 列表中查看和复制新创建的 Key。
安全使用建议
强烈建议您将 API Key 配置为环境变量，而不是将其硬编码在代码中。这是一种业界公认的安全实践，可以有效避免因代码仓库权限管理不当等原因导致 Key 泄露。详细配置方法请参考：配置 API Key 到环境变量。
核心概念
异步任务与同步任务
AI MediaKit 的媒体处理任务分为同步任务和异步任务，主要取决于工具的复杂度和预期耗时。
同步任务
同步任务适用于处理耗时较短、可以快速返回结果的场景。目前，AI MediaKit 的图像工具以及获取媒体上传地址 API 采用同步任务模型。其交互流程非常直接：
- 提交任务并等待：您通过调用具体工具的 POST 接口提交任务。
- 直接获取结果：服务处理完成后，处理结果（例如，处理后的图片 URL 或识别出的文本信息）将直接包含在本次请求的 HTTP 响应体中返回。您无需再次发起请求查询结果。
异步任务
对于处理时间较长的任务，例如大多数音视频处理任务（如视频拼接、视频裁剪等），AI MediaKit 采用异步任务模型。这意味着您提交任务和获取结果是两个独立的步骤，整个过程不会实时阻塞您的程序。标准的交互流程如下：
- 提交任务：您通过调用具体工具的 POST 接口来创建一个处理任务（例如，POST /api/v1/tools/concat-video）。如果请求参数校验通过，系统会立即返回一个全局唯一的 task_id。
- 查询状态：您需要使用上一步获取的 task_id，通过轮询通用的 GET /api/v1/tasks/{task_id} 接口来查询任务的实时状态。任务状态可能为 processing（处理中）、completed（已完成）、failed（已失败）等。
- 获取结果：当任务状态变为 completed 后，任务查询接口的响应中会包含一个 result 字段。该字段是一个 JSON 对象，包含了处理结果（例如，生成文件的下载地址 video_url）。
说明
幂等性控制
为确保在网络波动或客户端重试等不确定场景下，同一个处理请求不被重复执行，所有异步任务的提交接口均采用幂等性设计。
说明
同步任务当前不支持幂等性校验。
- 为什么需要幂等性：防止因客户端重试、网络抖动等原因导致同一个任务被多次执行，从而避免不必要的资源消耗和重复计费。
- 默认幂等行为：当您调用一个任务提交接口时，AI MediaKit 会根据您的账号信息和核心请求参数（例如，对于视频裁剪，这包括 video_url、start_time 和 end_time）的组合生成一个唯一标识。如果在该任务成功提交的 24 小时内，系统收到一个具有相同标识的请求，将不会创建新任务，而是会返回与首次请求相同的结果（例如，返回同一个 task_id）。
- 如何使用 client_token 主动控制幂等：除了依赖服务端的默认行为，您还可以通过在请求中加入可选参数 client_token 来实现更精确的幂等控制。client_token 是一个由客户端生成的、长度不超过 64 个字符的唯一字符串。
- 场景一：防止重复执行（触发幂等）
- 目的：因网络超时、客户端无响应等原因需要重试同一个请求时，确保任务不被重复创建。
- 操作：在重试时，使用与第一次请求完全相同的 client_token。
- 示例：您发起一个画质增强任务，并设置 client_token 为 "task-enhance-user123-20251125"。如果请求超时，您只需使用同一个 client_token 再次发起请求即可。服务端将识别到这是一个重试请求，并返回原任务的信息，而不会创建新任务。
- 场景二：强制重新执行（跳过幂等）
- 目的：希望对完全相同的视频源和操作参数，再次执行一次全新的任务。
- 操作：必须提供一个新的、唯一的 client_token。
- 示例：您已对某个视频源成功执行过一次处理。现在需要对其发起完全相同的处理请求，此时，您必须为第二次请求提供一个新的 client_token，否则将触发幂等，无法创建新任务。
API QPS 限制说明
为保障服务的稳定性，AI MediaKit 对 API 的调用频率设置了上限，即 QPS（Queries Per Second，每秒请求数）限制。QPS 限制以火山引擎主账号为单位。一个主账号及其下所有子账号的 API 调用量会被合并计算，总和不能超过设定的 QPS 上限。
AI MediaKit 对异步任务和同步任务采用不同的限流策略。
说明
- 超限影响：当调用频率超过 QPS 限制时，API 将返回限流相关的错误码，您需要降低调用频率或稍后重试。
- 配额调整：下文所列均为默认 QPS 限制。如果您当前的业务需求超出了默认配额，请联系您的客户经理或提交工单申请提升额度。
- 异步任务并发数限制：除了 API QPS 限制外，AI MediaKit 还对同一账号下可以同时处理的异步任务数量设有上限。该限制为账号维度，所有项目和队列共享同一个并发上限，默认为 20。创建更多项目或队列不会增加账号的并发上限。如需提升并发上限，请提交工单联系技术支持。同步任务（如图像工具）不受此并发数限制。
异步任务的 QPS 限制
所有异步任务共享同一个账号级别的调用频率限制。
- 限流规则：账号维度全局限流。
- 默认上限：每个主账号（及其所有子账号）调用所有异步接口的总 QPS 上限为 40。
同步任务的 QPS 限制
同步任务采用“按工具独立限流”的策略。每个同步工具 API 都有独立的 QPS 配额，不同工具之间的调用互不影响。各同步工具的默认 QPS 上限如下表所示：
最近更新时间：2026.10.09 15:39:54
这个页面对您有帮助吗？
有用
有用
无用
无用