API統合

VoxScriber REST APIの完全な開発者向けドキュメント。認証、主要エンドポイント、ウェブフック、そして自動文字起こしをシステムに統合する方法について学びます。

APIの機能

認証

APIキーの取得

APIキーの使用

すべてのリクエストのAuthorizationヘッダーにAPIキーを含めてください：

curl -X POST https://api.vozparatexto.com.br/v1/transcribe \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: multipart/form-data" \
  -F "file=@audio.mp3"

主要エンドポイント

ファイルアップロード

POST /v1/upload
Content-Type: multipart/form-data

パラメータ：

• file（必須） - 音声/ビデオファイル
• language（オプション） - 言語コード（例："en-US"）
• engine（オプション） - 文字起こしエンジン（"ASSEMBLYAI"、"WHISPER"、"ELEVENLABS"）
• speaker_detection（オプション） - 話者識別を有効にする（ブール値）

レスポンス：

{
  "id": "upload_abc123",
  "status": "UPLOADED",
  "duration": 120.5,
  "fileSize": 2048000
}

文字起こしの開始

POST /v1/transcribe
Content-Type: application/json

ボディ：

{
  "uploadId": "upload_abc123",
  "engine": "ASSEMBLYAI",
  "speakerDetection": true,
  "language": "en-US"
}

ステータスの確認

GET /v1/transcription/{id}/status

レスポンス：

{
  "id": "trans_xyz789",
  "status": "COMPLETED",
  "progress": 100,
  "text": "Transcribed text...",
  "duration": 120.5,
  "creditsUsed": 8
}

結果のダウンロード

GET /v1/transcription/{id}/export?format=json

利用可能なフォーマット： json、txt、srt、vtt、docx、pdf

レート制限

| エンドポイント | 制限 | ウィンドウ | |---|---|---| | アップロード | 10 リクエスト | 60 秒 | | 文字起こし | 10 リクエスト | 60 秒 | | クエリ | 60 リクエスト | 60 秒 | | エクスポート | 30 リクエスト | 60 秒 |

統合例

Node.js

const FormData = require('form-data');
const fs = require('fs');
const axios = require('axios');

const API_KEY = process.env.VOXSCRIBER_API_KEY;
const BASE_URL = 'https://api.vozparatexto.com.br/v1';

async function transcribeFile(filePath) {
  // 1. Upload
  const form = new FormData();
  form.append('file', fs.createReadStream(filePath));

  const upload = await axios.post(`${BASE_URL}/upload`, form, {
    headers: {
      'Authorization': `Bearer ${API_KEY}`,
      ...form.getHeaders()
    }
  });

  // 2. Transcribe
  const transcription = await axios.post(`${BASE_URL}/transcribe`, {
    uploadId: upload.data.id,
    engine: 'ASSEMBLYAI',
    speakerDetection: true
  }, {
    headers: { 'Authorization': `Bearer ${API_KEY}` }
  });

  return transcription.data;
}

Python

import requests
import os

API_KEY = os.environ['VOXSCRIBER_API_KEY']
BASE_URL = 'https://api.vozparatexto.com.br/v1'

def transcribe_file(file_path):
    headers = {'Authorization': f'Bearer {API_KEY}'}

    # 1. Upload
    with open(file_path, 'rb') as f:
        upload = requests.post(
            f'{BASE_URL}/upload',
            headers=headers,
            files={'file': f}
        )

    # 2. Transcribe
    transcription = requests.post(
        f'{BASE_URL}/transcribe',
        headers=headers,
        json={
            'uploadId': upload.json()['id'],
            'engine': 'ASSEMBLYAI',
            'speakerDetection': True
        }
    )

    return transcription.json()

エラーハンドリング

| コード | 意味 | 推奨される対応 | |---|---|---| | 400 | 不正なリクエスト | パラメータを確認してください | | 401 | 認証されていません | APIキーを確認してください | | 403 | アクセス禁止 | トークンの権限を確認してください | | 429 | レート制限を超過 | 待ってから再試行してください | | 500 | 内部エラー | 30秒後に再試行してください |

セキュリティ

• すべてのリクエストにHTTPSを使用してください
• APIキーを環境変数に保存してください
• 定期的にキーをローテーションしてください
• 必要最小限の権限を使用してください
• ウェブフックの署名検証を実装してください

さらに学ぶ

• ウェブフックと通知 - 自動コールバックを設定する
• バッチ処理 - API経由で複数のファイルを文字起こしする
• ワークフロー自動化 - APIでプロセスを自動化する