# 影片增強 API

> 將平台上的影片檔或已上傳的檔案增強至 1080p、2K 或 4K，可選擇強化畫面文字，並可處理最長 10 分鐘的片段。

## 影片增強 API

提交已存放在平台上的影片，或你上傳的檔案，取得 1080p、2K 或 4K 的增強結果。可以開關畫面文字強化，也可以增強整支影片，或最長 10 分鐘的片段。

## 支援的影片來源

傳入平台檔案網址，或 [上傳 API](https://wayin.ai/zh-tw/api-docs/upload/) 回傳的 `identity`。本機上傳需要 **Starter** 方案或以上。

### 流程

1. **提交**增強任務，帶上來源影片與目標解析度
2. **輪詢**結果，直到 `status` 為 `DONE` 或 `ERROR`
3. `status` 為 `DONE` 時讀取 `output_url`

---

## 端點

| 方法   | 路徑                                  | 說明         |
| ------ | ------------------------------------- | ------------ |
| `POST` | `/api/v2/video-enhancer`              | 提交增強任務 |
| `GET`  | `/api/v2/video-enhancer/results/{id}` | 查詢任務結果 |

所有請求都需要：

```http
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
x-wayinvideo-api-version: v2
```

---

## 提交增強任務

```http
POST https://wayinvideo-api.wayin.ai/api/v2/video-enhancer
```

### 請求本文

| 參數             | 類型    | 必填 | 預設    | 說明                                                                                                                          |
| ---------------- | ------- | ---- | ------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `video_url`      | string  | 是   | —       | 平台檔案網址，或 [上傳 API](https://wayin.ai/zh-tw/api-docs/upload/) 回傳的 `identity`。                                                            |
| `target_res`     | string  | 是   | —       | 輸出解析度。允許值：`1080p`、`2k`、`4k`。                                                                                     |
| `enable_text_hd` | boolean | 否   | `true`  | 是否強化畫面文字。省略此欄位時預設為 `true`。                                                                                 |
| `start_ms`       | integer | 否   | —       | 片段起點，單位毫秒。`start_ms` 與 `end_ms` 都省略時處理整支影片，仍受 10 分鐘上限限制。只傳其中一個會被拒絕。                 |
| `end_ms`         | integer | 否   | —       | 片段終點，單位毫秒。必須大於 `start_ms`，且不得超過來源影片長度。                                                            |

處理區間最長 10 分鐘。計費按該區間向上取整到秒。費率見 [計費說明](https://wayin.ai/zh-tw/api-docs/pricing/)。

### 請求範例

```bash
curl -X POST https://wayinvideo-api.wayin.ai/api/v2/video-enhancer \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "x-wayinvideo-api-version: v2" \
  -d '{
    "video_url": "EF_up_06wguq1afbwg1",
    "target_res": "1080p",
    "enable_text_hd": true,
    "start_ms": 0,
    "end_ms": 8000
  }'
```

```python
import requests

requests.post(
    "https://wayinvideo-api.wayin.ai/api/v2/video-enhancer",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "x-wayinvideo-api-version": "v2",
    },
    json={
        "video_url": "EF_up_06wguq1afbwg1",
        "target_res": "1080p",
        "enable_text_hd": True,
        "start_ms": 0,
        "end_ms": 8000,
    },
)
```

```javascript
await fetch('https://wayinvideo-api.wayin.ai/api/v2/video-enhancer', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer YOUR_API_KEY',
    'x-wayinvideo-api-version': 'v2',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    video_url: 'EF_up_06wguq1afbwg1',
    target_res: '1080p',
    enable_text_hd: true,
    start_ms: 0,
    end_ms: 8000,
  }),
});
```

### 回應

剛提交的任務通常是 `PENDING`（排隊中）或 `IN_PROGRESS`（已開始執行）。

```json
{
  "data": {
    "id": "proj_01HQ2X8J3K4L5M6N7O8P9Q0R",
    "status": "IN_PROGRESS"
  }
}
```

| 欄位         | 類型   | 說明                                                                          |
| ------------ | ------ | ----------------------------------------------------------------------------- |
| `id`         | string | Project id。查詢結果時放在路徑中。                                           |
| `status`     | string | `PENDING` 排隊、`IN_PROGRESS` 執行中、`DONE` 完成、`ERROR` 失敗。             |
| `output_url` | string | 增強後的影片網址。僅在 `status` 為 `DONE` 時出現。                            |

---

## 查詢增強結果

用提交回應中的 `id` 輪詢，直到 `status` 為 `DONE` 或 `ERROR`。`status` 為 `DONE` 時讀取 `output_url`。

```http
GET https://wayinvideo-api.wayin.ai/api/v2/video-enhancer/results/{id}
```

### 請求範例

```bash
curl -X GET https://wayinvideo-api.wayin.ai/api/v2/video-enhancer/results/proj_01HQ2X8J3K4L5M6N7O8P9Q0R \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "x-wayinvideo-api-version: v2"
```

### 回應

```json
{
  "data": {
    "id": "proj_01HQ2X8J3K4L5M6N7O8P9Q0R",
    "status": "DONE",
    "output_url": "https://cdn.viralhub.ai/user/video_0_8000_1080p.mp4"
  }
}
```

欄位與提交回應相同。任務完成後會帶上 `output_url`。

---

## 計費

影片增強按處理區間消耗 **API 點數**，向上取整到秒。不足 1 秒按 1 秒計。

| 目標解析度 | API 點數 |
| ---------- | -------- |
| 1080p      | 每秒 1   |
| 2K（`2k`） | 每秒 2   |
| 4K（`4k`） | 每秒 4   |

帳戶點數不足時不會建立任務，也不會扣點。詳見 [計費說明](https://wayin.ai/zh-tw/api-docs/pricing/) 與 [狀態碼](https://wayin.ai/zh-tw/api-docs/status-codes/)。

---

## 錯誤

失敗請求使用標準狀態碼與回應格式。詳見 [狀態碼](https://wayin.ai/zh-tw/api-docs/status-codes/)。