# VOD 接入说明

> 火山云 VOD 系列能力的 AK/SK 鉴权、Base URL、统一响应结构与错误码。官方 SDK 换域名与密钥即可接入。

VOD 系列接口格式与火山云视频点播（VOD）OpenAPI 完全一致——若你已有基于火山官方 VOD SDK 的接入代码，只需**替换接入域名与 AK/SK** 即可直接使用，无需改动任何签名逻辑。

## 基础信息

- **Base URL**：

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

- **鉴权**：使用 **AK/SK**（Access Key / Secret Key），签名方式与火山官方一致。AK/SK 在 [控制台](https://console.looprouter.com) 获取——系统已为你生成好，直接填入官方 SDK 即可。SDK 的 `region` 保持官方默认 `cn-north-1`。

- **请求分派**：与官方一致，所有请求打到同一入口，按 query 参数 `Action` 与 `Version` 区分接口。

<Warning>
请务必使用 `api.looprouter.com` 域名接入（而非 `looprouter.com` 主站域名），否则请求无法到达 API 服务。
</Warning>

## 支持的 Action

| Action | HTTP 方法 | Version | 用途 |
| --- | --- | --- | --- |
| `UploadMediaByUrl` | POST | `2020-08-01` | 提交源视频链接，获取上传作业 ID |
| `QueryUploadTaskInfo` | GET | `2020-08-01` | 查询上传结果，换取媒资 `Vid` |
| `AsyncVCreativeTask` | POST | `2018-01-01` | 提交漫剧转绘任务 |
| `GetVCreativeTaskResult` | GET | `2018-01-01` | 轮询转绘任务结果 |
| `GetPlayInfo` | GET | `2020-08-01` | 获取成片播放地址 |

完整链路与各 Action 的参数详解见 [AI 漫剧转绘](/video-processing/vod/comic-style-transfer)。

## 统一响应结构

### 成功

```json
{
  "ResponseMetadata": {
    "RequestId": "b1e6c2f0-…",
    "Action": "AsyncVCreativeTask",
    "Version": "2018-01-01",
    "Service": "vod",
    "Region": "cn-north-1"
  },
  "Result": { "…": "各 Action 的结果对象" }
}
```

### 失败

失败时无 `Result`，错误信息挂在 `ResponseMetadata.Error`：

```json
{
  "ResponseMetadata": {
    "RequestId": "b1e6c2f0-…",
    "Action": "AsyncVCreativeTask",
    "Version": "2018-01-01",
    "Service": "vod",
    "Region": "cn-north-1",
    "Error": {
      "Code": "InvalidParameter",
      "Message": "ParamObj.input must be in the form vid://<Vid>"
    }
  }
}
```

### 错误码

| HTTP | `Error.Code` | 说明 |
| --- | --- | --- |
| 400 | `InvalidParameter` | 请求参数非法，`Message` 会说明具体原因 |
| 400 | `InvalidAction` | 不支持的 `Action` |
| 401 | `InvalidCredential` | AK/SK 无效或签名错误 |
| 403 | `QuotaExceeded` | 账户余额不足或超出可用额度 |
| 404 | `ResourceNotFound` | 任务 / 媒资不存在，或成片尚未就绪 |
| 429 | `Throttling` | 请求过于频繁或未完成任务数超上限 |
| 503 | `ServiceUnavailable` | 服务暂不可用 |
| 其它 5xx | `InternalError` | 内部错误，请稍后重试 |

## 成片链接有效期

<Warning>
`GetPlayInfo` 返回的播放地址为**临时链接**，约 **2 小时**后失效。请在任务成功后**尽快下载**并转存到你自己的存储。下载时无需携带鉴权信息。
</Warning>

## 计费

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

## 下一步

<CardGroup cols={2}>
  <Card title="AI 漫剧转绘" icon="palette" href="/video-processing/vod/comic-style-transfer">
    完整 5 步链路：上传 → 提交 → 轮询 → 取片
  </Card>
  <Card title="常见问题" icon="circle-question" href="/video-processing/faq">
    签名排错、计费时机、失败退费
  </Card>
</CardGroup>