Skip to main content

​
使用指南

語音轉文字 API 是我們最核心的功能，提供高準確度的音訊轉錄服務。本指南將幫助您快速整合並優化使用體驗。
API 的詳細參數、請求格式和回應結構請參考自動生成的 API 文件。本頁面專注於實際使用指南和最佳實踐。

​
快速整合

​
基本使用

最簡單的語音轉文字請求： 
const fs = require('fs');
const fetch = require('node-fetch');
const FormData = require('form-data');

async function transcribeAudio(audioPath) {
  const form = new FormData();
  form.append('file', fs.createReadStream(audioPath));
  form.append('model', 'thiannu-v1');
  
  const response = await fetch('https://api.skiesoft.com/v1/audio/transcriptions', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
    },
    body: form
  });
  
  const result = await response.json();
  return result.text;
}

​
進階功能使用

啟用說話者分離和詳細輸出： 
const form = new FormData();
form.append('file', fs.createReadStream(audioPath));
form.append('model', 'thiannu-v1');
form.append('speaker_diarization', 'true')

const response = await fetch('https://api.skiesoft.com/v1/audio/transcriptions', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
  },
  body: form
});

​
批次處理大量檔案

class BatchTranscriber {
  constructor(apiKey, options = {}) {
    this.apiKey = apiKey;
    this.concurrency = options.concurrency || 3;
    this.transcriber = new RobustTranscriber(apiKey);
  }
  
  async processBatch(audioFiles, options = {}) {
    const results = [];
    const errors = [];
    
    // 使用 Promise.allSettled 處理並發請求
    const chunks = this.chunkArray(audioFiles, this.concurrency);
    
    for (const chunk of chunks) {
      const promises = chunk.map(async (file) => {
        try {
          const audioBuffer = fs.readFileSync(file.path);
          const base64Audio = audioBuffer.toString('base64');
          
          const result = await this.transcriber.transcribeWithRetry(base64Audio, options);
          
          return {
            file: file.path,
            success: true,
            result,
            metadata: file.metadata
          };
        } catch (error) {
          return {
            file: file.path,
            success: false,
            error: error.message,
            metadata: file.metadata
          };
        }
      });
      
      const chunkResults = await Promise.allSettled(promises);
      
      chunkResults.forEach(result => {
        if (result.status === 'fulfilled') {
          if (result.value.success) {
            results.push(result.value);
          } else {
            errors.push(result.value);
          }
        } else {
          errors.push({
            file: 'unknown',
            success: false,
            error: result.reason.message
          });
        }
      });
      
      // 在批次之間稍作停頓，避免超過速率限制
      if (chunks.indexOf(chunk) < chunks.length - 1) {
        await this.delay(1000);
      }
    }
    
    return {
      successful: results,
      failed: errors,
      summary: {
        total: audioFiles.length,
        successful: results.length,
        failed: errors.length
      }
    };
  }
  
  chunkArray(array, size) {
    const chunks = [];
    for (let i = 0; i < array.length; i += size) {
      chunks.push(array.slice(i, i + size));
    }
    return chunks;
  }
  
  delay(ms) {
    return new Promise(resolve => setTimeout(resolve, ms));
  }
}

// 使用範例
const batchTranscriber = new BatchTranscriber('YOUR_API_KEY', {
  concurrency: 2  // 同時處理 2 個檔案
});

const audioFiles = [
  { path: 'audio1.wav', metadata: { source: 'meeting1' } },
  { path: 'audio2.wav', metadata: { source: 'meeting2' } },
  { path: 'audio3.wav', metadata: { source: 'interview1' } }
];

const batchResults = await batchTranscriber.processBatch(audioFiles, {
  speaker_diarization: true
});

console.log(`成功處理: ${batchResults.summary.successful} 個檔案`);
console.log(`失敗: ${batchResults.summary.failed} 個檔案`);

​
效能優化建議

​
1. 檔案大小優化

  • 對於超過 25MB 的檔案，建議先分割處理
  • 使用適當的音訊壓縮格式（推薦 FLAC 或高品質 MP3）
  • 移除不必要的靜音片段

​
2. 並發處理

  • 根據您的速率限制設定適當的並發數
  • 實作請求佇列管理
  • 監控 API 使用量避免超額

​
3. 快取策略

  • 對相同音訊檔案的結果進行快取
  • 實作檔案指紋識別避免重複處理
  • 定期清理過期的快取資料