# 影片筆記 API

> 使用自訂提示詞、時間戳記、長度控制與選用影片畫面，從影片生成結構化 AI 筆記。

## 影片筆記 API

提交影片網址或已上傳的檔案，以生成摘要資訊，並可選擇生成結構化 AI 筆記。你可以自訂筆記指示、輸出語言、偏好長度、時間戳記，以及是否包含來源影片中的相關畫面。

每個回應都包含結構化概覽、主題標籤與時間軸重點。啟用 AI 筆記生成時，回應也會同時包含 Markdown 與純文字格式的筆記。未啟用 AI 筆記生成時，回應只會包含摘要相關資訊。

## 支援的影片來源

API 接受來自 YouTube、Vimeo、Dailymotion、Kick、Twitch、TikTok、Facebook、Zoom、Rumble 等平台的影片網址。

你也可以處理[本機上傳的影片檔案](https://wayin.ai/zh-tw/api-docs/upload/)——本機上傳需要 **Starter** 訂閱計劃或以上。

### 工作流程

1. **提交**：使用影片網址或已上傳的檔案識別碼提交影片筆記任務
2. **輪詢**：持續查詢結果端點，直到 `status` 為 `SUCCEEDED`

---

## 提交影片筆記任務

建立包含或不包含 AI 筆記生成的任務。若要生成 AI 筆記，請加入 `note_params`；若只需要摘要、主題標籤與時間軸重點，則省略此參數。

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

### 請求本體

| 參數          | 類型   | 必填 | 預設值 | 說明                                                                                                                       |
| ------------- | ------ | ---- | ------ | -------------------------------------------------------------------------------------------------------------------------- |
| `video_url`   | string | 是   | —      | 來源影片網址或已上傳的檔案識別碼                                                                                           |
| `source_lang` | string | 否   | `null` | 影片的來源語言（參見[支援語言](https://wayin.ai/zh-tw/api-docs/supported-languages/)）。為 `null` 時，系統會自動偵測原始語言。                   |
| `target_lang` | string | 否   | `null` | 生成摘要與重點的目標語言（參見[支援語言](https://wayin.ai/zh-tw/api-docs/supported-languages/)）。為 `null` 時，輸出語言會跟隨偵測到的來源語言。 |
| `note_params` | object | 否   | `null` | AI 筆記生成設定。省略此物件即可略過 AI 筆記生成。                                                                          |

### 筆記參數

| 參數              | 類型    | 必填條件                    | 預設值 | 說明                       |
| ----------------- | ------- | --------------------------- | ------ | -------------------------- |
| `enable_note`     | boolean | 提供 `note_params` 時為必填 | —      | 設為 `true` 以生成 AI 筆記 |
| `generate_params` | object  | 提供 `note_params` 時為必填 | —      | AI 筆記生成設定            |

### 筆記生成參數

| 參數                | 類型    | 必填 | 預設值  | 說明                                                                                         |
| ------------------- | ------- | ---- | ------- | -------------------------------------------------------------------------------------------- |
| `prompt`            | string  | 是   | —       | 描述所需筆記結構、內容或重點的指示                                                           |
| `language`          | string  | 否   | `null`  | 僅設定 AI 筆記的輸出語言，不影響摘要或重點（參見[支援語言](https://wayin.ai/zh-tw/api-docs/supported-languages/)） |
| `length_option`     | string  | 是   | —       | 偏好的筆記長度：`short`、`medium` 或 `long`                                                  |
| `include_timestamp` | boolean | 是   | —       | 是否在相關段落與重點加入來源影片時間戳記，協助讀者找到影片中的對應時刻                       |
| `image_visual`      | boolean | 否   | `false` | 是否包含從來源影片擷取的相關畫面                                                             |

### 請求範例

```bash
curl -X POST https://wayinvideo-api.wayin.ai/api/v2/notes \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "x-wayinvideo-api-version: v2" \
  -d '{
    "video_url": "https://www.youtube.com/watch?v=EXAMPLE",
    "source_lang": "en",
    "target_lang": "en",
    "note_params": {
      "enable_note": true,
      "generate_params": {
        "prompt": "Organize the main ideas and action items",
        "language": "en",
        "length_option": "medium",
        "include_timestamp": true,
        "image_visual": false
      }
    }
  }'
```

```python
import requests

requests.post(
    "https://wayinvideo-api.wayin.ai/api/v2/notes",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "x-wayinvideo-api-version": "v2",
    },
    json={
        "video_url": "https://www.youtube.com/watch?v=EXAMPLE",
        "target_lang": "en",
        "note_params": {
            "enable_note": True,
            "generate_params": {
                "prompt": "Organize the main ideas and action items",
                "language": "en",
                "length_option": "medium",
                "include_timestamp": True,
            },
        },
    },
)
```

```javascript
await fetch('https://wayinvideo-api.wayin.ai/api/v2/notes', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer YOUR_API_KEY',
    'x-wayinvideo-api-version': 'v2',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    video_url: 'https://www.youtube.com/watch?v=EXAMPLE',
    target_lang: 'en',
    note_params: {
      enable_note: true,
      generate_params: {
        prompt: 'Organize the main ideas and action items',
        language: 'en',
        length_option: 'medium',
        include_timestamp: true,
      },
    },
  }),
});
```

### 提交回應

```json
{
  "data": {
    "id": "note_proj_001",
    "name": "sample project name",
    "status": "CREATED"
  }
}
```

| 欄位     | 類型   | 說明                                       |
| -------- | ------ | ------------------------------------------ |
| `id`     | string | 用於取得結果的任務識別碼                   |
| `name`   | string | 從來源影片產生的任務名稱                   |
| `status` | string | 初始任務狀態；已接受的任務會回傳 `CREATED` |

---

## 使用範例

以下範例展示常見的影片筆記使用情境。請將 `YOUR_API_KEY` 替換為從 [API Dashboard](https://wayin.ai/wayinvideo/api-dashboard) 取得的金鑰。

### 生成含時間戳記的精簡筆記

```bash
curl -X POST https://wayinvideo-api.wayin.ai/api/v2/notes \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "x-wayinvideo-api-version: v2" \
  -H "Content-Type: application/json" \
  -d '{
    "video_url": "https://www.youtube.com/watch?v=EXAMPLE",
    "note_params": {
      "enable_note": true,
      "generate_params": {
        "prompt": "Create concise notes covering the main ideas",
        "length_option": "short",
        "include_timestamp": true
      }
    }
  }'
```

### 生成著重行動項目的會議筆記

```bash
curl -X POST https://wayinvideo-api.wayin.ai/api/v2/notes \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "x-wayinvideo-api-version: v2" \
  -H "Content-Type: application/json" \
  -d '{
    "video_url": "UPLOADED_FILE_ID",
    "note_params": {
      "enable_note": true,
      "generate_params": {
        "prompt": "Create meeting notes with decisions, owners, and action items",
        "length_option": "medium",
        "include_timestamp": true
      }
    }
  }'
```

### 不生成 AI 筆記，僅處理影片

省略 `note_params`，即可回傳摘要、主題標籤與時間軸重點，而不包含筆記資料。

```bash
curl -X POST https://wayinvideo-api.wayin.ai/api/v2/notes \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "x-wayinvideo-api-version: v2" \
  -H "Content-Type: application/json" \
  -d '{
    "video_url": "https://www.youtube.com/watch?v=EXAMPLE",
    "target_lang": "en"
  }'
```

---

## 取得影片筆記結果

提交任務後，持續輪詢此端點，直到 `status` 為 `SUCCEEDED`。成功的回應會包含摘要資訊，以及要求生成時所產生的 AI 筆記。

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

### 路徑參數

| 參數 | 類型   | 必填 | 說明                  |
| ---- | ------ | ---- | --------------------- |
| `id` | string | 是   | 提交端點回傳的任務 ID |

### 結果請求

```bash
curl -X GET https://wayinvideo-api.wayin.ai/api/v2/notes/results/note_proj_001 \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "x-wayinvideo-api-version: v2"
```

```python
import requests

requests.get(
    "https://wayinvideo-api.wayin.ai/api/v2/notes/results/note_proj_001",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "x-wayinvideo-api-version": "v2",
    },
)
```

```javascript
await fetch(
  'https://wayinvideo-api.wayin.ai/api/v2/notes/results/note_proj_001',
  {
    method: 'GET',
    headers: {
      Authorization: 'Bearer YOUR_API_KEY',
      'x-wayinvideo-api-version': 'v2',
    },
  }
);
```

### 成功回應範例

```json
{
  "data": {
    "summary_id": "vdsmr_001",
    "status": "SUCCEEDED",
    "title": "sample title",
    "video_thumbnail": "https://cdn.example.com/thumb/video_001.jpg",
    "summary": "sample summary text",
    "note_data": "# Main Ideas\n\n- **00:45** First key point\n- **03:20** Second key point",
    "note_text": "Main Ideas\n\n00:45 First key point\n03:20 Second key point",
    "tags": ["#topic1", "#topic2"],
    "highlights": [
      {
        "start": 0,
        "end": 196000,
        "desc": "sample section title",
        "events": [
          {
            "timestamp": 45000,
            "desc": "sample event description"
          }
        ]
      }
    ],
    "cost_usage": 54.0
  }
}
```

### 回應欄位

| 欄位              | 類型     | 說明                                                                     |
| ----------------- | -------- | ------------------------------------------------------------------------ |
| `summary_id`      | string   | 已生成摘要的識別碼                                                       |
| `status`          | string   | 任務狀態：`CREATED`、`QUEUED`、`ONGOING`、`SUCCEEDED` 或 `FAILED`        |
| `error_message`   | string   | 錯誤原因；僅在 `status` 為 `FAILED` 時出現                               |
| `title`           | string   | AI 生成的標題                                                            |
| `video_thumbnail` | string   | 來源影片縮圖網址                                                         |
| `summary`         | string   | 影片的結構化概覽                                                         |
| `note_data`       | string   | 保留 Markdown 結構的 AI 筆記，適合以 Markdown 格式呈現；未要求生成時省略 |
| `note_text`       | string   | 移除 Markdown 語法的 AI 筆記純文字版本；未要求生成時省略                 |
| `tags`            | string[] | AI 生成的主題標籤                                                        |
| `highlights`      | array    | 含時間戳記與關鍵事件的時間軸段落                                         |
| `cost_usage`      | number   | 任務消耗的 API 點數                                                      |

### 重點段落物件

| 欄位     | 類型   | 說明                 |
| -------- | ------ | -------------------- |
| `start`  | number | 起始時間（毫秒）     |
| `end`    | number | 結束時間（毫秒）     |
| `desc`   | string | 段落標題或描述       |
| `events` | array  | 重點段落中的關鍵事件 |

### 事件物件

| 欄位        | 類型   | 說明             |
| ----------- | ------ | ---------------- |
| `timestamp` | number | 事件時間（毫秒） |
| `desc`      | string | 事件描述         |

---

## 常見問題

### 影片筆記與影片摘要有何不同？

[影片摘要 API](https://wayin.ai/zh-tw/api-docs/video-summarization/) 會生成概覽、主題標籤與時間軸重點。影片筆記 API 會回傳相同的摘要資訊，並可額外生成可自訂的 Markdown 與純文字格式筆記。

### 一定要生成 AI 筆記嗎？

不用。省略 `note_params` 即可回傳摘要資訊，而不生成 AI 筆記。若要生成筆記，請提供 `note_params`、將 `enable_note` 設為 `true`，並加入 `generate_params.prompt`。

### `note_data` 與 `note_text` 有何不同？

`note_data` 會保留生成的 Markdown 結構，以便呈現標題、清單、強調與其他格式。`note_text` 包含相同筆記，但會移除 Markdown 語法，適合用於搜尋索引、嵌入、預覽或純文字儲存。

### 可以控制筆記格式嗎？

可以。使用 `generate_params.prompt` 提供指示、以 `language` 設定筆記語言、以 `length_option` 設定偏好長度、以 `include_timestamp` 加入時間戳記，並以 `image_visual` 包含相關影片畫面。

### 支援哪些影片來源？

支援 YouTube、Vimeo、Dailymotion、Kick、Twitch、TikTok、Facebook、Zoom、Rumble 等平台的網址，也支援透過[上傳 API](https://wayin.ai/zh-tw/api-docs/upload/)上傳本機檔案。