使用指南
語音轉文字 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. 快取策略
- 對相同音訊檔案的結果進行快取
- 實作檔案指紋識別避免重複處理
- 定期清理過期的快取資料