範例

Curl

目錄

  1. 認證
  2. Tasks API
  3. Imports API
  4. Broadcasts API
  5. TTS API
  6. Speakers API
  7. Summary Templates API
  8. SSE API
  9. 實用腳本

認證

取得 WebSocket Ticket

WebSocket 連線使用 Ticket 機制認證。先透過 REST API 取得一次性 Ticket,再用於 WebSocket 連線。

curl -X POST "https://vas-poc.vurbo.ai/api/v1/auth/ticket" \
  -H "X-API-Key: vas_YOUR_API_KEY_HERE_32_CHARACTERS"

回應範例:

{
  "ticket": "aBcDeFgHiJkLmNoPqRsTuVwXyZ012345",
  "expires_in": 60
}

注意:Ticket 有效期為 60 秒,僅能使用一次。


Tasks API

取得任務列表

curl -X GET "https://vas-poc.vurbo.ai/api/v1/tasks" \
  -H "X-API-Key: vas_YOUR_API_KEY_HERE_32_CHARACTERS"

回應範例:

{
  "tasks": [
    {
      "task_id": "550e8400-e29b-41d4-a716-446655440000",
      "title": "會議記錄",
      "type": "transcribe",
      "duration_ms": 60000,
      "duration_formatted": "1:00",
      "source_lang": "zh-TW",
      "target_lang": "en-US",
      "created_at": "2025-12-13T10:00:00Z",
      "audio_status": "success",
      "is_pinned": false,
      "is_unread": true
    }
  ]
}

查詢進行中的任務

curl -X GET "https://vas-poc.vurbo.ai/api/v1/tasks?status=active" \
  -H "X-API-Key: vas_YOUR_API_KEY_HERE_32_CHARACTERS"

回應範例:

{
  "tasks": [
    {
      "task_id": "550e8400-e29b-41d4-a716-446655440000",
      "title": "未命名錄音",
      "type": "transcribe",
      "duration_ms": 0,
      "duration_formatted": "0:00",
      "source_lang": "zh-TW",
      "target_lang": "en-US",
      "created_at": "2026-02-24T10:00:00Z",
      "processing_status": "recording",
      "is_pinned": false,
      "is_unread": true
    }
  ]
}

刪除任務

curl -X DELETE "https://vas-poc.vurbo.ai/api/v1/tasks/550e8400-e29b-41d4-a716-446655440000" \
  -H "X-API-Key: vas_YOUR_API_KEY_HERE_32_CHARACTERS"

回應範例:

{
}

更新釘選狀態

釘選任務:

curl -X PUT "https://vas-poc.vurbo.ai/api/v1/tasks/550e8400-e29b-41d4-a716-446655440000/pin" \
  -H "X-API-Key: vas_YOUR_API_KEY_HERE_32_CHARACTERS" \
  -H "Content-Type: application/json" \
  -d '{"is_pinned": true}'

取消釘選:

curl -X PUT "https://vas-poc.vurbo.ai/api/v1/tasks/550e8400-e29b-41d4-a716-446655440000/pin" \
  -H "X-API-Key: vas_YOUR_API_KEY_HERE_32_CHARACTERS" \
  -H "Content-Type: application/json" \
  -d '{"is_pinned": false}'

回應範例:

{
  "is_pinned": true
}

標記已讀

curl -X PUT "https://vas-poc.vurbo.ai/api/v1/tasks/550e8400-e29b-41d4-a716-446655440000/read" \
  -H "X-API-Key: vas_YOUR_API_KEY_HERE_32_CHARACTERS"

回應範例:

{
  "is_unread": false
}

更新任務名稱

curl -X PATCH "https://vas-poc.vurbo.ai/api/v1/tasks/550e8400-e29b-41d4-a716-446655440000/name" \
  -H "X-API-Key: vas_YOUR_API_KEY_HERE_32_CHARACTERS" \
  -H "Content-Type: application/json" \
  -d '{"name": "產品會議討論"}'

回應範例:

{
  "message": "錄音名稱已更新",
  "data": {
    "task_id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "產品會議討論",
    "name_source": "user"
  }
}

下載任務音檔

下載任務的原始音檔(一律為 M4A 容器,副檔名 .m4a)。-OJ 會依伺服器回傳的 Content-Disposition 自動命名。

curl -X GET "https://vas-poc.vurbo.ai/api/v1/tasks/550e8400-e29b-41d4-a716-446655440000/audio/export" \
  -H "X-API-Key: vas_YOUR_API_KEY_HERE_32_CHARACTERS" \
  -OJ

下載逐字稿

支援五種格式:txt(預設)、srtsbvvttcsv。輸出包含原文與所有翻譯語言。

# 預設 TXT 格式
curl -X GET "https://vas-poc.vurbo.ai/api/v1/tasks/550e8400-e29b-41d4-a716-446655440000/transcript/export" \
  -H "X-API-Key: vas_YOUR_API_KEY_HERE_32_CHARACTERS" \
  -OJ

# SRT 字幕(SubRip,適用於影片字幕軟體)
curl -X GET "https://vas-poc.vurbo.ai/api/v1/tasks/550e8400-e29b-41d4-a716-446655440000/transcript/export?format=srt" \
  -H "X-API-Key: vas_YOUR_API_KEY_HERE_32_CHARACTERS" \
  -OJ

# SBV 字幕(YouTube 上傳)
curl -X GET "https://vas-poc.vurbo.ai/api/v1/tasks/550e8400-e29b-41d4-a716-446655440000/transcript/export?format=sbv" \
  -H "X-API-Key: vas_YOUR_API_KEY_HERE_32_CHARACTERS" \
  -OJ

# VTT 字幕(HTML5 <track>)
curl -X GET "https://vas-poc.vurbo.ai/api/v1/tasks/550e8400-e29b-41d4-a716-446655440000/transcript/export?format=vtt" \
  -H "X-API-Key: vas_YOUR_API_KEY_HERE_32_CHARACTERS" \
  -OJ

# CSV 試算表(含 UTF-8 BOM,Excel 可直接開啟)
curl -X GET "https://vas-poc.vurbo.ai/api/v1/tasks/550e8400-e29b-41d4-a716-446655440000/transcript/export?format=csv" \
  -H "X-API-Key: vas_YOUR_API_KEY_HERE_32_CHARACTERS" \
  -OJ

注意:必須在 processing_status = completed 後才能匯出;尚未就緒會回 422 recording_transcript_not_ready


Imports API

檢查預算

上傳音檔前先檢查月度預算是否足夠。

curl -X POST "https://vas-poc.vurbo.ai/api/v1/imports/check-quota" \
  -H "X-API-Key: vas_YOUR_API_KEY_HERE_32_CHARACTERS" \
  -H "Content-Type: application/json" \
  -d '{"duration_ms": 3600000}'

回應範例:

{
  "data": {
    "allowed": true,
    "remaining_budget": 49.72,
    "is_exceeded": false
  }
}

上傳音檔

基本上傳:

curl -X POST "https://vas-poc.vurbo.ai/api/v1/imports" \
  -H "X-API-Key: vas_YOUR_API_KEY_HERE_32_CHARACTERS" \
  -F "file=@meeting.mp3" \
  -F 'transcription_languages=["zh-TW"]' \
  -F 'translation_languages=["en-US"]' \
  -F "recognition_mode=multi_speaker"

含文字處理設定的上傳:

curl -X POST "https://vas-poc.vurbo.ai/api/v1/imports" \
  -H "X-API-Key: vas_YOUR_API_KEY_HERE_32_CHARACTERS" \
  -F "file=@meeting.mp3" \
  -F 'transcription_languages=["zh-TW"]' \
  -F 'translation_languages=["en-US"]' \
  -F "recognition_mode=multi_speaker" \
  -F "summary_template=meeting" \
  -F 'terminology={"zh-TW": [{"term": "語者分離", "boost": 1.5}]}' \
  -F 'fuzzy_correction={"zh-TW": [{"correct": "語者分離", "incorrect": ["語這分離"]}]}' \
  -F 'translation_dict=[{"source": "語者分離", "translations": {"en-US": "Speaker Diarization"}}]'

上傳音檔(含 Webhook 回呼)

curl -X POST "https://vas-poc.vurbo.ai/api/v1/imports" \
  -H "X-API-Key: vas_YOUR_API_KEY_HERE_32_CHARACTERS" \
  -F "file=@meeting.mp3" \
  -F 'transcription_languages=["zh-TW"]' \
  -F 'translation_languages=["en-US"]' \
  -F "recognition_mode=multi_speaker" \
  -F "callback_url=https://your-server.com/webhooks/vas"

設定 callback_url 後,處理完成時會收到 import.completed Webhook 通知,無需輪詢。詳見 Webhook 回呼指南


回應範例(HTTP 202):

{
  "data": {
    "import_id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "pending",
    "stage": null,
    "progress": 0,
    "message": null,
    "original_filename": "meeting.mp3",
    "file_size": "15.2 MB",
    "task_id": null,
    "error_code": null,
    "error_message": null,
    "created_at": "2025-12-31T10:00:00.000Z",
    "updated_at": "2025-12-31T10:00:00.000Z"
  }
}

查詢匯入狀態

curl -X GET "https://vas-poc.vurbo.ai/api/v1/imports/550e8400-e29b-41d4-a716-446655440000" \
  -H "X-API-Key: vas_YOUR_API_KEY_HERE_32_CHARACTERS"

回應範例:

{
  "data": {
    "import_id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "processing",
    "stage": "transcribing",
    "progress": 45,
    "message": "正在辨識語音...",
    "original_filename": "meeting.mp3",
    "file_size": "15.2 MB",
    "task_id": null,
    "error_code": null,
    "error_message": null,
    "created_at": "2025-12-31T10:00:00.000Z",
    "updated_at": "2025-12-31T10:05:00.000Z"
  }
}

狀態說明pendingprocessingcompleted / failed處理階段convertingtranscribingtranslatingsummarizing


取得匯入列表

curl -X GET "https://vas-poc.vurbo.ai/api/v1/imports?per_page=20" \
  -H "X-API-Key: vas_YOUR_API_KEY_HERE_32_CHARACTERS"

回應範例:

{
  "data": [
    {
      "import_id": "550e8400-e29b-41d4-a716-446655440000",
      "status": "completed",
      "original_filename": "meeting.mp3",
      "file_size": "15.2 MB",
      "task_id": "660e8400-e29b-41d4-a716-446655440001",
      "created_at": "2025-12-31T10:00:00.000Z"
    }
  ],
  "meta": {
    "current_page": 1,
    "last_page": 5,
    "per_page": 20,
    "total": 100
  }
}

Broadcasts API

建立廣播

curl -X POST "https://vas-poc.vurbo.ai/api/v1/broadcasts" \
  -H "X-API-Key: vas_YOUR_API_KEY_HERE_32_CHARACTERS" \
  -H "Content-Type: application/json" \
  -d '{
    "transcription_language": "zh-TW",
    "translation_languages": ["en-US", "ja-JP"],
    "name": "我的廣播頻道",
    "access_type": "public",
    "max_viewers": 50,
    "tts_config": {
      "en-US": {"voice": "en-US-JennyNeural", "speaking_rate": 1.0},
      "ja-JP": {"voice": "ja-JP-NanamiNeural", "speaking_rate": 1.0}
    },
    "summary_template": "meeting",
    "summary_language": "zh-TW",
    "callback_url": "https://your-server.com/webhooks/vas"
  }'

回應範例(HTTP 201):

{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "token": "a3f9",
    "name": "我的廣播頻道",
    "share_url": "https://vas-poc.vurbo.ai/broadcast/a3f9",
    "transcription_language": "zh-TW",
    "translation_languages": ["en-US", "ja-JP"],
    "tts_config": {
      "en-US": {"voice": "en-US-JennyNeural", "speaking_rate": 1.0},
      "ja-JP": {"voice": "ja-JP-NanamiNeural", "speaking_rate": 1.0}
    },
    "speaker_diarization": false,
    "summary_template": "meeting",
    "summary_language": "zh-TW",
    "max_viewers": 50,
    "access_type": "public",
    "pass_code": null,
    "status": "pending",
    "is_live": false,
    "created_at": "2026-01-03T10:00:00.000Z"
  }
}

查詢廣播狀態

curl -X GET "https://vas-poc.vurbo.ai/api/v1/broadcasts/550e8400-e29b-41d4-a716-446655440000" \
  -H "X-API-Key: vas_YOUR_API_KEY_HERE_32_CHARACTERS"

取得廣播列表

curl -X GET "https://vas-poc.vurbo.ai/api/v1/broadcasts?per_page=10&page=1" \
  -H "X-API-Key: vas_YOUR_API_KEY_HERE_32_CHARACTERS"

更新廣播設定

改為密碼保護:

curl -X PATCH "https://vas-poc.vurbo.ai/api/v1/broadcasts/550e8400-e29b-41d4-a716-446655440000" \
  -H "X-API-Key: vas_YOUR_API_KEY_HERE_32_CHARACTERS" \
  -H "Content-Type: application/json" \
  -d '{
    "access_type": "password",
    "pass_code": "mySecret123"
  }'

調整觀眾人數上限:

curl -X PATCH "https://vas-poc.vurbo.ai/api/v1/broadcasts/550e8400-e29b-41d4-a716-446655440000" \
  -H "X-API-Key: vas_YOUR_API_KEY_HERE_32_CHARACTERS" \
  -H "Content-Type: application/json" \
  -d '{"max_viewers": 200}'

變更語言設定:

curl -X PATCH "https://vas-poc.vurbo.ai/api/v1/broadcasts/550e8400-e29b-41d4-a716-446655440000" \
  -H "X-API-Key: vas_YOUR_API_KEY_HERE_32_CHARACTERS" \
  -H "Content-Type: application/json" \
  -d '{
    "transcription_language": "en-US",
    "translation_languages": ["zh-TW", "ja-JP", "ko-KR"]
  }'

撤銷廣播

pending 狀態的廣播可撤銷。

curl -X DELETE "https://vas-poc.vurbo.ai/api/v1/broadcasts/550e8400-e29b-41d4-a716-446655440000" \
  -H "X-API-Key: vas_YOUR_API_KEY_HERE_32_CHARACTERS"

回應範例:

{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "revoked",
    "revoked_at": "2026-01-03T10:05:00.000Z"
  }
}

TTS API

取得語音列表

curl -X GET "https://vas-poc.vurbo.ai/api/v1/tts/voices?language=en-US" \
  -H "X-API-Key: vas_YOUR_API_KEY_HERE_32_CHARACTERS"

回應範例:

{
  "data": {
    "language": "en-US",
    "voices": [
      {
        "voice_name": "en-US-JennyNeural",
        "display_name": "Jenny",
        "gender": "Female",
        "is_default": true,
        "sample_url": "https://vas-poc.vurbo.ai/api/v1/tts/voices/en-US-JennyNeural/sample"
      },
      {
        "voice_name": "en-US-GuyNeural",
        "display_name": "Guy",
        "gender": "Male",
        "is_default": false,
        "sample_url": "https://vas-poc.vurbo.ai/api/v1/tts/voices/en-US-GuyNeural/sample"
      }
    ]
  }
}

試聽語音

curl -X GET "https://vas-poc.vurbo.ai/api/v1/tts/voices/zh-TW-HsiaoChenNeural/sample" \
  -H "X-API-Key: vas_YOUR_API_KEY_HERE_32_CHARACTERS" \
  --output sample.mp3

回應為 MP3 音訊二進位資料,不計入 TTS 費用。 支援 TTS 的語言清單請參考附錄 - 支援語言


Speakers API

全域重命名說話者

curl -X PATCH "https://vas-poc.vurbo.ai/api/v1/tasks/550e8400-e29b-41d4-a716-446655440000/speakers/rename" \
  -H "X-API-Key: vas_YOUR_API_KEY_HERE_32_CHARACTERS" \
  -H "Content-Type: application/json" \
  -d '{
    "speaker_id": "Guest-1",
    "new_label": "王經理"
  }'

回應範例:

{
  "data": {
    "speaker_id": "Guest-1",
    "new_label": "王經理",
    "affected_sids": [1, 3, 5, 8, 12]
  }
}

重新指派單句語者

curl -X PATCH "https://vas-poc.vurbo.ai/api/v1/tasks/550e8400-e29b-41d4-a716-446655440000/speakers/reassign" \
  -H "X-API-Key: vas_YOUR_API_KEY_HERE_32_CHARACTERS" \
  -H "Content-Type: application/json" \
  -d '{
    "sid": 5,
    "target_speaker_id": "Guest-2"
  }'

回應範例:

{
  "data": {
    "sid": 5,
    "old_speaker_id": "Guest-1",
    "new_speaker_id": "Guest-2",
    "new_speaker_label": "李小華"
  }
}

Summary Templates API

取得摘要模板列表

curl -X GET "https://vas-poc.vurbo.ai/api/v1/summary-templates" \
  -H "X-API-Key: vas_YOUR_API_KEY_HERE_32_CHARACTERS"

回應範例:

{
  "data": [
    {"slug": "general", "name": "通用摘要", "description": "適用於一般對話的摘要模板"},
    {"slug": "meeting", "name": "會議摘要", "description": "適用於會議記錄的摘要模板"},
    {"slug": "meeting_minutes", "name": "會議紀要", "description": "詳細的會議紀要模板"},
    {"slug": "speech", "name": "演講摘要", "description": "適用於演講內容的摘要模板"},
    {"slug": "interview", "name": "訪談摘要", "description": "適用於訪談內容的摘要模板"},
    {"slug": "course", "name": "課程摘要", "description": "適用於課程內容的摘要模板"}
  ]
}

SSE API

取得歷史紀錄

curl -N "https://vas-poc.vurbo.ai/api/v1/sse/history/transcribe/550e8400-e29b-41d4-a716-446655440000" \
  -H "X-API-Key: vas_YOUR_API_KEY_HERE_32_CHARACTERS"

注意-N 參數用於禁用緩衝,以即時接收 SSE 事件。

回應範例(SSE 格式):

event: connected
data: {"message": "歷史紀錄服務已連線 (recordingId: 550e8400-e29b-41d4-a716-446655440000)"}

event: init_metadata
data: {"task_id": "550e8400-e29b-41d4-a716-446655440000", "title": "會議記錄", "created_at": "2025-12-17T10:00:00Z", "type": "transcribe", "has_speaker_diarization": false, "transcription_languages": ["zh-TW"], "translation_languages": ["en-US"], "summary_template": null, "summary_language": null}

event: init_sentence
data: {"sid": 1, "origin": "你好,很高興認識你", "translations": {"en-US": "Hello, nice to meet you"}, "start_time": "00:05"}

event: init_sentence
data: {"sid": 2, "origin": "今天我們來討論產品規劃", "translations": {"en-US": "Today let's discuss product planning"}, "start_time": "00:10"}

event: init_summary
data: {"text": "這是會議摘要..."}

event: init_done
data: {"totalSentences": 2}

下載音訊

下載完整音訊:

curl -o audio.m4a "https://vas-poc.vurbo.ai/api/v1/sse/audio/550e8400-e29b-41d4-a716-446655440000" \
  -H "X-API-Key: vas_YOUR_API_KEY_HERE_32_CHARACTERS"

取得部分音訊(Range Request):

curl -H "Range: bytes=0-1023" \
  -H "X-API-Key: vas_YOUR_API_KEY_HERE_32_CHARACTERS" \
  -o audio_part.m4a \
  "https://vas-poc.vurbo.ai/api/v1/sse/audio/550e8400-e29b-41d4-a716-446655440000"

重新翻譯全文

curl -N "https://vas-poc.vurbo.ai/api/v1/sse/retranslate/550e8400-e29b-41d4-a716-446655440000?targetLang=ja-JP" \
  -H "X-API-Key: vas_YOUR_API_KEY_HERE_32_CHARACTERS"

回應範例(SSE 格式):

event: translation
data: {"sid": 1, "text": "こんにちは、お会いできて嬉しいです", "is_final": true}

event: translation
data: {"sid": 2, "text": "今日は製品計画について話し合いましょう", "is_final": true}

event: done
data: {"totalUpdated": 2}

重新翻譯摘要

curl -N "https://vas-poc.vurbo.ai/api/v1/sse/retranslate/summary/550e8400-e29b-41d4-a716-446655440000?targetLang=en-US" \
  -H "X-API-Key: vas_YOUR_API_KEY_HERE_32_CHARACTERS"

回應範例(SSE 格式):

event: summary_translation
data: {"text": "This is the", "is_final": false}

event: summary_translation
data: {"text": "This is the meeting summary...", "is_final": true}

event: done
data: {"totalUpdated": 1}

TTS 語音合成

curl -N "https://vas-poc.vurbo.ai/api/v1/sse/tts/550e8400-e29b-41d4-a716-446655440000" \
  -H "X-API-Key: vas_YOUR_API_KEY_HERE_32_CHARACTERS" \
  -H "Content-Type: application/json" \
  -d '{
    "sid": 1,
    "language": "en-US",
    "voice": "en-US-JennyNeural"
  }'

實用腳本

取得所有任務並格式化輸出

curl -s "https://vas-poc.vurbo.ai/api/v1/tasks" \
  -H "X-API-Key: vas_YOUR_API_KEY_HERE_32_CHARACTERS" \
  | jq '.tasks[] | {id: .task_id, title: .title, duration: .duration_formatted}'

批次刪除所有任務

#!/bin/bash
API_KEY="vas_YOUR_API_KEY_HERE_32_CHARACTERS"
BASE_URL="https://vas-poc.vurbo.ai/api/v1"

# 取得所有任務 ID
TASK_IDS=$(curl -s "${BASE_URL}/tasks" \
  -H "X-API-Key: ${API_KEY}" \
  | jq -r '.tasks[].task_id')

# 逐一刪除
for ID in $TASK_IDS; do
  echo "刪除任務: $ID"
  curl -s -X DELETE "${BASE_URL}/tasks/${ID}" \
    -H "X-API-Key: ${API_KEY}"
  echo ""
done

echo "完成"

上傳音檔並輪詢狀態

#!/bin/bash
API_KEY="vas_YOUR_API_KEY_HERE_32_CHARACTERS"
BASE_URL="https://vas-poc.vurbo.ai/api/v1"
FILE="meeting.mp3"

# 步驟 1:上傳音檔
echo "上傳音檔: ${FILE}"
RESPONSE=$(curl -s -X POST "${BASE_URL}/imports" \
  -H "X-API-Key: ${API_KEY}" \
  -F "file=@${FILE}" \
  -F 'transcription_languages=["zh-TW"]' \
  -F 'translation_languages=["en-US"]' \
  -F "recognition_mode=multi_speaker" \
  -F "summary_template=meeting")

IMPORT_ID=$(echo "$RESPONSE" | jq -r '.data.import_id')
echo "匯入 ID: ${IMPORT_ID}"

# 步驟 2:輪詢狀態
while true; do
  STATUS_RESPONSE=$(curl -s "${BASE_URL}/imports/${IMPORT_ID}" \
    -H "X-API-Key: ${API_KEY}")

  STATUS=$(echo "$STATUS_RESPONSE" | jq -r '.data.status')
  STAGE=$(echo "$STATUS_RESPONSE" | jq -r '.data.stage')
  PROGRESS=$(echo "$STATUS_RESPONSE" | jq -r '.data.progress')

  echo "狀態: ${STATUS} | 階段: ${STAGE} | 進度: ${PROGRESS}%"

  if [ "$STATUS" = "completed" ]; then
    TASK_ID=$(echo "$STATUS_RESPONSE" | jq -r '.data.task_id')
    echo "處理完成!任務 ID: ${TASK_ID}"
    break
  fi

  if [ "$STATUS" = "failed" ]; then
    ERROR=$(echo "$STATUS_RESPONSE" | jq -r '.data.error_message')
    echo "處理失敗: ${ERROR}"
    break
  fi

  sleep 5
done

匯出任務歷史紀錄為 JSON

#!/bin/bash
API_KEY="vas_YOUR_API_KEY_HERE_32_CHARACTERS"
BASE_URL="https://vas-poc.vurbo.ai/api/v1"
TASK_ID="550e8400-e29b-41d4-a716-446655440000"
OUTPUT_FILE="task_${TASK_ID}.json"

# 取得歷史紀錄並儲存
curl -s -N "${BASE_URL}/sse/history/transcribe/${TASK_ID}" \
  -H "X-API-Key: ${API_KEY}" \
  | grep "^data:" \
  | sed 's/^data: //' \
  > "${OUTPUT_FILE}"

echo "已匯出至 ${OUTPUT_FILE}"

版本:V1.5.7 最後更新:2026-05-20

Copyright © 2026