# 影片轉錄 API

> 從影片或音頻內容中提取字詞級別的逐字稿，並支援說話者分離（speaker diarization，自動標註說話者）。

## 影片轉錄 API

提交影片或音頻檔案，取得字詞級別的逐字稿，並支援說話者分離（speaker diarization，每個段落會標註偵測到的說話者）。API 支援主流平台影片，以及本機上傳的影片或音頻檔案，並支援語言設定。

## 支援的影片來源

API 接受以下平台的網址：YouTube、Vimeo、Dailymotion、Kick、Twitch、TikTok、Facebook、Zoom、Rumble 等。

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

### 工作流程

1. **提交**：從影片網址提交轉錄任務
2. **輪詢**：持續取得結果，直到狀態變為 `SUCCEEDED`

---

## 提交轉錄任務

從影片或音頻網址提交一個新的轉錄任務。

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

### 請求本體

| 參數 | 類型 | 必填 | 預設值 | 說明 |
|------|------|------|--------|------|
| `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` 時不進行翻譯。若 `target_lang` 與影片原始語言不同，逐字稿將自動翻譯成目標語言。 |

### 請求範例

```bash
curl -X POST https://wayinvideo-api.wayin.ai/api/v2/transcripts \
  -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",
    "target_lang": "en"
  }'
```

```python
import requests

requests.post(
    "https://wayinvideo-api.wayin.ai/api/v2/transcripts",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "x-wayinvideo-api-version": "v2",
    },
    json={
        "video_url": "https://www.youtube.com/watch?v=example",
        "target_lang": "en",
    },
)
```

```javascript
await fetch("https://wayinvideo-api.wayin.ai/api/v2/transcripts", {
  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",
  }),
});
```

### 回應

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

| 欄位 | 類型 | 說明 |
|------|------|------|
| `id` | string | 任務識別碼（用於取得結果） |
| `name` | string | 任務名稱 |
| `status` | string | `CREATED`、`QUEUED`、`ONGOING`、`SUCCEEDED`、`FAILED` |

---

## 使用範例

常見的轉錄情境。請將 `YOUR_API_KEY` 替換為從 [API Dashboard](https://wayin.ai/wayinvideo/api-dashboard) 取得的金鑰。

### 轉錄 YouTube 影片

```bash
curl -X POST https://wayinvideo-api.wayin.ai/api/v2/transcripts \
  -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"}'
```

### 轉錄多位說話者的 Podcast

傳入任何 Podcast 音頻網址（或[上傳檔案識別碼](https://wayin.ai/zh-tw/api-docs/upload/)）即可——說話者分離為自動執行；回應中每個段落都會附上 `speaker` 標籤。

```bash
curl -X POST https://wayinvideo-api.wayin.ai/api/v2/transcripts \
  -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` 即可即時翻譯。若已知來源語言，可搭配 `source_lang` 一起設定。

```bash
curl -X POST https://wayinvideo-api.wayin.ai/api/v2/transcripts \
  -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",
    "source_lang": "ja",
    "target_lang": "en"
  }'
```

---

## 取得轉錄結果

取得含時間戳記與說話者標籤的逐字稿。持續輪詢，直到 `status` 為 `SUCCEEDED`。

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

### 路徑參數

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

### 請求範例

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

### 回應

```json
{
  "data": {
    "status": "SUCCEEDED",
    "cost_usage": 27.0,
    "transcript": [
      {
        "text": "Welcome to today's presentation",
        "language": null,
        "start": 200,
        "end": 4500,
        "speaker": "Speaker 1"
      },
      {
        "text": "Thanks for coming",
        "language": null,
        "start": 5000,
        "end": 8200,
        "speaker": "Speaker 2"
      }
    ]
  }
}
```

### 回應欄位

| 欄位 | 類型 | 說明 |
|------|------|------|
| `status` | string | `CREATED`、`QUEUED`、`ONGOING`、`SUCCEEDED`、`FAILED` |
| `error_message` | string | 錯誤原因（僅在 `status` 為 `FAILED` 時出現） |
| `cost_usage` | number | 此次請求消耗的 API 點數 |
| `transcript` | array | 逐字稿片段列表（詳見下方） |

### 逐字稿片段

| 欄位 | 類型 | 說明 |
|------|------|------|
| `text` | string | 轉錄的文字內容 |
| `language` | string \| null | 偵測到的語言代碼，若無法偵測則為 `null` |
| `start` | integer | 起始時間（毫秒） |
| `end` | integer | 結束時間（毫秒） |
| `speaker` | string | 說話者標籤（例如 `"Speaker 1"`） |


---

## 常見問題

### 影片最長可以多長？

沒有硬性的長度限制。API 支援短片以及長影片或長音訊內容，可處理支援來源平台上的素材。

### API 會回傳字詞級別的時間戳記嗎？

會。每個逐字稿段落都包含毫秒級的 `start` 與 `end` 時間戳記、轉錄出的 `text`、偵測到的 `language`，以及由說話者分離指派的 `speaker` 標籤。

### 說話者分離如何運作？

說話者會自動偵測並依段落標註（`Speaker 1`、`Speaker 2`…）。不需任何設定——每次轉錄任務都會執行說話者分離。

### 支援哪些音頻與影片格式？

來源網址支援 YouTube、Vimeo、Dailymotion、Kick、Twitch、TikTok、Facebook、Zoom、Rumble 等。本機上傳請使用 `mp4`、`mov`、`webm` 或 `avi`（純音頻檔案可封裝至上述任一容器格式）。

### 可以將逐字稿翻譯成其他語言嗎？

可以——傳入 `target_lang` 參數即可。當 `target_lang` 與來源語言不同時，逐字稿將自動翻譯。完整的語言代碼清單請參見[支援語言](https://wayin.ai/zh-tw/api-docs/supported-languages/)。