# 上傳 API

> 上傳本機影片檔案，搭配 AI Clipping、Summarization、Video Notes、Transcription、Find Moments 與 Video Enhancer 使用。

## 上傳 API

上傳 API 讓你將本機影片檔案上傳至 WayinVideo。上傳完成後，可將回傳的檔案識別碼作為其他 API 端點（AI 剪輯、時刻搜尋、影片摘要、影片筆記、影片轉錄、影片增強）的 `video_url` 使用。

> **檔案大小限制：** 本機上傳的單一檔案上限為 5 GB。若需要更大的限制，請聯繫 [wayinvideo@wayin.ai](mailto:wayinvideo@wayin.ai)。

> **支援格式：** 請上傳有效的影片檔案，目前支援格式：**avi**、**mp4**、**mov**、**webm**。上傳其他格式可能導致後續任務處理失敗。

### 上傳流程

1. **請求**：提供檔案資訊，取得預簽名上傳網址
2. **上傳**：使用 `PUT` 請求將檔案直接上傳至預簽名網址
3. **使用**：將回傳的 `identity` 值作為後續 API 呼叫的 `video_url`

---

## 取得上傳網址

請求本機檔案的臨時上傳網址。

```
POST https://wayinvideo-api.wayin.ai/api/v2/upload/single-file
```

### 請求本體

| 參數   | 類型   | 必填 | 預設值 | 說明                                        |
| ------ | ------ | ---- | ------ | ------------------------------------------- |
| `name` | string | 是   | —      | 含副檔名的檔案名稱（例如 `"my-video.mp4"`） |

### 請求範例

```bash
curl -X POST https://wayinvideo-api.wayin.ai/api/v2/upload/single-file \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "x-wayinvideo-api-version: v2" \
  -d '{
    "name": "sample-video.mp4"
  }'
```

### 回應

```json
{
  "data": {
    "upload_url": "https://storage.example.com/upload/presigned-url...",
    "identity": "file_abc123"
  }
}
```

| 欄位         | 類型   | 說明                                                                                                |
| ------------ | ------ | --------------------------------------------------------------------------------------------------- |
| `upload_url` | string | 用於上傳檔案的預簽名網址，**有效期 1 小時**，請在時限內完成上傳。若已過期，請重新請求一組新的網址。 |
| `identity`   | string | 檔案識別碼，用於其他 API 的 `video_url`                                                             |

---

## 上傳檔案

使用 `upload_url` 以 `PUT` 請求上傳檔案。`--data-binary` 後的 `@` 接著本機檔案路徑：

```bash
curl -X PUT "https://storage.example.com/upload/presigned-url..." \
  -H "Content-Type: video/mp4" \
  --data-binary @/Users/me/Videos/sample-video.mp4
```

> **注意：** 使用相同的 `upload_url` 再次上傳，新檔案會覆蓋舊檔案。每個單一檔案不得超過 **5 GB**。

---

## 使用已上傳的檔案

上傳完成後，將 `identity` 值作為 `video_url` 提交任務。

> **注意：** 每個 `identity` 有效期為 **24 小時**。在配額充足的情況下，可在 24 小時內多次使用同一個 `identity` 提交任務。

```bash
curl -X POST https://wayinvideo-api.wayin.ai/api/v2/clips \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "x-wayinvideo-api-version: v2" \
  -d '{
    "video_url": "THE_IDENTITY_VALUE",
    "enable_export": false
  }'
```

---

## 常見問題

### 應該上傳本機檔案還是直接傳入來源網址？

如果影片已經存在於支援的平台（YouTube、Vimeo、TikTok、Zoom 等），直接將網址傳給處理端點即可——不需要上傳。只有當檔案尚未存放在支援的來源時，才需要使用上傳 API。

### 單一上傳檔案的大小上限是多少？

每個檔案 5 GB。若你的使用情境需要更高上限，請聯繫 [wayinvideo@wayin.ai](mailto:wayinvideo@wayin.ai)。

### 支援哪些檔案格式？

`mp4`、`mov`、`webm`、`avi`。其他格式可能在處理時失敗。

### 上傳會佔用我訂閱計劃的儲存配額嗎？

會——上傳的檔案會佔用訂閱計劃的儲存空間。各訂閱計劃的儲存空間與單一檔案大小限制請參見 [訂閱計劃](https://wayin.ai/wayinvideo/settings/plan)。

### 如何在其他 API 呼叫中使用已上傳的檔案？

上傳完成後，將回傳的檔案識別碼作為任何支援之處理端點的 `video_url` 欄位——[AI Clipping](https://wayin.ai/zh-tw/api-docs/ai-clipping/)、[Find Moments](https://wayin.ai/zh-tw/api-docs/find-moments/)、[Video Summarization](https://wayin.ai/zh-tw/api-docs/video-summarization/)、[Video Notes](https://wayin.ai/zh-tw/api-docs/video-notes/)、[Video Transcription](https://wayin.ai/zh-tw/api-docs/video-transcription/) 或 [Video Enhancer](https://wayin.ai/zh-tw/api-docs/video-enhancer/)。