# AI MediaKit 接入说明

> 火山云 AI MediaKit 系列能力的 Base URL、API Key 鉴权、统一响应结构与错误码。

AI MediaKit 系列提供**智能插帧、字幕擦除、画质增强**三类视频再处理能力，接口格式与火山云官方 AI MediaKit 完全一致——若你已有基于官方 API 的接入代码或 SDK，只需**替换 Base URL 与 API Key** 即可直接使用。

## 基础信息

- **Base URL**：

  ```
  https://api.looprouter.com/api/aimediakit
  ```

  完整接口路径为 Base URL + `/api/v1/...`（与官方一致，官方 SDK 会自动拼接）。

- **鉴权**：所有接口都需在请求头携带 API Key：

  ```
  Authorization: Bearer sk-你的APIKey
  Content-Type: application/json
  ```

  在 [控制台 → 令牌](https://console.looprouter.com/keys) 创建 `sk-` 开头的 API Key。

- **调用模式**：异步。提交任务立即返回 `task_id`，需轮询 [任务查询接口](/video-processing/aimediakit/get-task) 获取结果。

## 能力一览

| 能力 | 接口 |
| --- | --- |
| [智能插帧](/video-processing/aimediakit/frame-interpolation) | `POST /api/v1/tools/video-frame-interpolation` |
| [字幕擦除](/video-processing/aimediakit/subtitle-erasure-pro) | `POST /api/v1/tools/erase-video-subtitle-pro` |
| [画质增强（标准版 / 专业版）](/video-processing/aimediakit/enhance-video) | `POST /api/v1/tools/enhance-video` |
| [画质增强（大模型版）](/video-processing/aimediakit/enhance-video-generative) | `POST /api/v1/tools/enhance-video-generative` |
| [任务查询（通用）](/video-processing/aimediakit/get-task) | `GET /api/v1/tasks/{task_id}` |

## 统一响应结构

### 提交成功（受理）

所有提交接口（`POST /api/v1/tools/*`）成功受理后同步返回：

```json
{
  "success": true,
  "task_id": "vg_9f8c1e2b7a6d4f30",
  "request_id": "b1e6c2f0-3a4d-4e5f-8a90-1234567890ab"
}
```

拿到 `task_id` 后轮询 [任务查询接口](/video-processing/aimediakit/get-task)。

### 请求失败

```json
{
  "success": false,
  "task_id": "",
  "error": {
    "code": "InvalidParameter",
    "type": "BadRequest",
    "message": "frame_interpolation.fps must be between 15 and 120"
  },
  "request_id": "b1e6c2f0-3a4d-4e5f-8a90-1234567890ab"
}
```

### 错误码

| HTTP | `error.code` | `error.type` | 说明 |
| --- | --- | --- | --- |
| 400 | `InvalidParameter` | `BadRequest` | 请求参数非法，`message` 会说明具体原因 |
| 401 | `Unauthorized` | `Unauthorized` | API Key 缺失或无效 |
| 403 | `QuotaExceeded` | `Forbidden` | 账户余额不足或超出可用额度 |
| 404 | `NotFound` | `NotFound` | 任务不存在 |
| 429 | `TooManyRequests` | `Throttling` | 请求过于频繁或未完成任务数超上限 |
| 503 | `ServiceUnavailable` | `ServiceUnavailable` | 服务暂不可用 |
| 其它 5xx | `InternalError` | `InternalError` | 内部错误，请稍后重试 |

## 视频源要求

所有能力的 `video_url` 均要求：

- 公网可直接访问的 `http(s)` 链接；
- 最长 **1024** 字符；
- 不支持 base64 内联数据。

## 成片链接有效期

<Warning>
任务成功后返回的成片 `video_url` 为**临时链接**，约 **2 小时**后失效。请尽快下载并转存到你自己的存储。下载时无需携带 `Authorization` 请求头。
</Warning>

## 计费

按**实际用量后付费**：任务成功后按**实际输出时长与输出分辨率档位**计费；任务失败**不收费**。详见 [视频处理总览](/video-processing/overview#计费与结算)。