チュートリアル

概要

このチュートリアルでは、Tiro API を使って音声ファイルをアップロードし、文字起こしを行い、複数の言語に翻訳するまでの一連の手順を説明します。

前提条件

有効な Tiro API key
音声ファイル（MP3、WAV、M4A）
最大ファイルサイズ: 500MB
最大の長さ: 4 時間

Step 1: Voice File Job を作成する

まず、希望する文字起こしと翻訳の設定でジョブを作成します。

curl -X POST https://api.tiro.ooo/v1/external/voice-file/jobs \
  -H "Authorization: Bearer $TIRO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "transcriptLocaleHints": ["ko_KR"],
    "translationLocales": ["en_US"]
  }'

レスポンスの例:

{
  "id": "b2d1ab32-3fe2-4201-b0b4-391abdbaa023",
  "uploadUri": "https://storage.example.com/upload/signed-url"
}

Step 2: 音声ファイルをアップロードする

提供された署名付き URL に音声ファイルをアップロードします。

# Upload audio file to the signed URL (replace UPLOAD_URI with the uploadUri from Step 1)
curl -X PUT "$UPLOAD_URI" \
  -H "Content-Type: audio/mpeg" \
  --data-binary @/path/to/your/audio.mp3

Step 3: アップロード完了を通知する

アップロードが完了したことを API に伝えます。

curl -X PUT "https://api.tiro.ooo/v1/external/voice-file/jobs/$JOB_ID/upload-complete" \
  -H "Authorization: Bearer $TIRO_API_KEY" \
  -H "Content-Type: application/json"

Step 4: ジョブの完了をポーリングする

処理が完了するまで、ジョブのステータスを監視します。

# Check job status (poll until status is COMPLETED or FAILED)
curl -X GET "https://api.tiro.ooo/v1/external/voice-file/jobs/$JOB_ID" \
  -H "Authorization: Bearer $TIRO_API_KEY"

# Example response:
# {
#   "id": "job_abc123",
#   "status": "COMPLETED",
#   "fileUploadedAt": "2024-01-01T12:00:20Z",
#   "processStartedAt": "2024-01-01T12:01:00Z",
#   "processCompletedAt": "2024-01-01T12:02:30Z"
# }

Step 5: 結果を取得する

ジョブが完了したら、transcript と translations を取得します。

# Get transcript
curl -X GET "https://api.tiro.ooo/v1/external/voice-file/jobs/$JOB_ID/transcript" \
  -H "Authorization: Bearer $TIRO_API_KEY"

# Get all translations
curl -X GET "https://api.tiro.ooo/v1/external/voice-file/jobs/$JOB_ID/translations" \
  -H "Authorization: Bearer $TIRO_API_KEY"

# Get specific translation (e.g., English)
curl -X GET "https://api.tiro.ooo/v1/external/voice-file/jobs/$JOB_ID/translations/en_US" \
  -H "Authorization: Bearer $TIRO_API_KEY"

# Get transcript paragraph summary
curl -X GET "https://api.tiro.ooo/v1/external/voice-file/jobs/$JOB_ID/transcript/paragraph-summary" \
  -H "Authorization: Bearer $TIRO_API_KEY"

# Get translation paragraph summary
curl -X GET "https://api.tiro.ooo/v1/external/voice-file/jobs/$JOB_ID/translations/en_US/paragraph-summary" \
  -H "Authorization: Bearer $TIRO_API_KEY"

完全な例

音声ファイルを最初から最後まで処理する完全な例を以下に示します。

#!/bin/bash
# Complete Voice File Processing Script

# Set your API key
export TIRO_API_KEY="your_api_key_here"
AUDIO_FILE="/path/to/your/audio.mp3"

# Step 1: Create job
echo "Creating voice file job..."
RESPONSE=$(curl -s -X POST https://api.tiro.ooo/v1/external/voice-file/jobs \
  -H "Authorization: Bearer $TIRO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "transcriptLocaleHints": ["ko_KR"],
    "translationLocales": ["en_US"]
  }')

JOB_ID=$(echo $RESPONSE | jq -r '.id')
UPLOAD_URI=$(echo $RESPONSE | jq -r '.uploadUri')
echo "Job created: $JOB_ID"

# Step 2: Upload file
echo "Uploading audio file..."
curl -s -X PUT "$UPLOAD_URI" \
  -H "Content-Type: audio/mpeg" \
  --data-binary @"$AUDIO_FILE"
echo "File uploaded successfully"

# Step 3: Notify upload complete
echo "Notifying upload completion..."
curl -s -X PUT "https://api.tiro.ooo/v1/external/voice-file/jobs/$JOB_ID/upload-complete" \
  -H "Authorization: Bearer $TIRO_API_KEY" \
  -H "Content-Type: application/json"

# Step 4: Poll for completion
echo "Waiting for processing to complete..."
while true; do
  STATUS=$(curl -s -X GET "https://api.tiro.ooo/v1/external/voice-file/jobs/$JOB_ID" \
    -H "Authorization: Bearer $TIRO_API_KEY" | jq -r '.status')
  echo "Status: $STATUS"
  
  if [ "$STATUS" = "COMPLETED" ]; then
    echo "Job completed successfully!"
    break
  elif [ "$STATUS" = "FAILED" ]; then
    echo "Job failed!"
    exit 1
  fi
  
  sleep 5
done

# Step 5: Get results
echo "Retrieving results..."

echo "=== Transcript ==="
curl -s -X GET "https://api.tiro.ooo/v1/external/voice-file/jobs/$JOB_ID/transcript" \
  -H "Authorization: Bearer $TIRO_API_KEY" | jq '.text'

echo "=== Translation (en_US) ==="
curl -s -X GET "https://api.tiro.ooo/v1/external/voice-file/jobs/$JOB_ID/translations/en_US" \
  -H "Authorization: Bearer $TIRO_API_KEY" | jq '.text'

echo "=== Paragraph Summary ==="
curl -s -X GET "https://api.tiro.ooo/v1/external/voice-file/jobs/$JOB_ID/transcript/paragraph-summary" \
  -H "Authorization: Bearer $TIRO_API_KEY" | jq '.summary'

echo "Processing completed!"

Step 6: Paragraph Summary を理解する

Paragraph Summary 機能は、インテリジェントなコンテンツ要約を提供し、音声ファイルの要点をすばやく把握するのに役立ちます。

Paragraph Summary とは

Paragraph summary は、transcript や translation のコンテンツを自動生成した概要で、論理的なセクションに分割されています。各要約は次のものを提供します。

簡潔な概要: 各段落の要点を markdown 形式で
言語別: transcript と translations の両方について生成される要約
構造化されたコンテンツ: 解析が容易で、アプリケーションへの統合も簡単

レスポンスの例

paragraph summary を取得すると、次のようなレスポンスを受け取ります。

{
  "jobId": "job-123",
  "locale": "ko_KR",
  "summary": [
    {
      "type": "markdown",
      "content": "### 회의는 프로젝트 진행 상황을 점검하고, 다음 단계에 대한 계획을 수립하는 데 중점을 두었습니다."
    },
    {
      "type": "markdown", 
      "content": "### 팀원들은 각자의 담당 업무에 대한 현재 상태를 보고하고, 발생한 이슈들에 대해 논의했습니다."
    }
  ]
}

要約はいつ利用できますか

Transcript と Translation の要約: ジョブ完了後（COMPLETED ステータス）に利用できます
- COMPLETED は、transcript、translation（リクエストした場合）、およびその両方の paragraph summary を含む、すべての処理が完了したことを意味します
処理時間: 要約は非同期で生成され、通常はメイン処理の完了後 30〜60 秒以内に生成されます

ポーリングのベストプラクティス

指数バックオフ戦略

開始時の遅延: 2 秒（処理の開始には時間がかかります）
増加係数: 1.2 倍（緩やかな増加）
最大の遅延: 30 秒（サーバーへの過負荷を避けます）
最大試行回数: 想定される処理時間に基づきます

ジョブの状態遷移

処理時間のガイドライン

ファイルの長さ	想定される処理時間	推奨ポーリング間隔
5 分未満	30〜60 秒	開始: 2s、最大: 10s
5〜30 分	1〜5 分	開始: 5s、最大: 20s
30〜120 分	5〜15 分	開始: 10s、最大: 30s
2 時間超	15〜30 分	開始: 30s、最大: 60s

よくある問題と解決策

アップロードの失敗

問題: 413 Payload Too Large
解決策: ファイルサイズ（最大 500MB）を確認し、必要に応じて圧縮してください

処理の失敗

問題: 音声品質が低い
解決策: サンプルレートが 8kHz 以上であること、背景ノイズが最小限であることを確認してください

タイムアウトの問題

問題: 想定時間内にジョブが完了しない
解決策: 長いファイルではタイムアウトを長くし、ジョブの状態にエラーがないか確認してください

全体像をもう一度確認したい場合は Voice File 概要をご覧ください。すべてのパラメータとレスポンスフィールドについては、API Reference をご覧ください。

​概要

​前提条件

​Step 1: Voice File Job を作成する

​Step 2: 音声ファイルをアップロードする

​Step 3: アップロード完了を通知する

​Step 4: ジョブの完了をポーリングする

​Step 5: 結果を取得する

​完全な例

​Step 6: Paragraph Summary を理解する

​Paragraph Summary とは

​レスポンスの例

​要約はいつ利用できますか

​ポーリングのベストプラクティス

​指数バックオフ戦略

​ジョブの状態遷移

​処理時間のガイドライン

​よくある問題と解決策

​アップロードの失敗

​処理の失敗

​タイムアウトの問題

概要