> ## Documentation Index
> Fetch the complete documentation index at: https://docs.skiesoft.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 快速開始

> 30 分鐘內完成「聽有 AI」語音辨識 API 整合

## 開始使用「聽有 AI」

本指南將協助您在 30 分鐘內完成「聽有 AI」語音辨識 API 的整合，讓您的應用程式具備強大的語音轉文字功能。

### 前置準備

<AccordionGroup>
  <Accordion icon="key" title="取得 API 金鑰">
    1. 前往 [軟雲官網](https://skiesoft.com) 註冊開發者帳號
    2. 登入[開發者控制台](https://developer.skiesoft.com)
    3. 建立新的 API 金鑰
    4. 記錄您的 `API_KEY`

    <Note>
      新用戶可獲得免費試用額度，包含 1000 分鐘的語音辨識服務
    </Note>
  </Accordion>
</AccordionGroup>

### 基本整合

<AccordionGroup>
  <Accordion icon="microphone" title="即時語音辨識">
    以下是使用 Node.js 進行即時語音辨識的範例：

    ```javascript theme={null}
    const WebSocket = require('ws');
    const fs = require('fs');

    const SERVER_URL = 'wss://api.skiesoft.com/asr';
    const WEBM_FILE_PATH = 'input.webm';
    const API_TOKEN = 'your-api-token-here';

    const ws = new WebSocket(SERVER_URL, {
        headers: { 'Authorization': `Bearer ${API_TOKEN}` }
    });

    ws.on('open', async () => {
        console.log('連接成功');

        const fileStream = fs.createReadStream(WEBM_FILE_PATH);

        fileStream.on('data', (data) => {
            ws.send(data);
        });

        fileStream.on('end', () => {
            ws.send(Buffer.alloc(0)); // 發送空 buffer 表示結束
            console.log('文件發送完成');
        });
    });

    ws.on('message', (message) => {
        const data = JSON.parse(message.toString());
        console.log('收到訊息:', data);
        if (data.type === 'ready_to_stop') {
            ws.close();
        }
    });
    ```
  </Accordion>

  <Accordion icon="file-audio" title="音檔上傳辨識">
    上傳音檔進行批次辨識：

    ```javascript theme={null}
    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;
    }
    ```
  </Accordion>
</AccordionGroup>

### 測試您的整合

<AccordionGroup>
  <Accordion icon="flask" title="測試音檔">
    使用我們提供的測試音檔驗證整合是否正確：

    ```bash theme={null}
    # 下載測試音檔
    curl -O https://cdn.skiesoft.com/samples/test-mixed-language.wav
    ```

    預期的辨識結果應該包含：

    * 國語：「你好，歡迎使用聽有 AI」
    * 臺語：「這个系統真好用」
    * 英語：「This is a test recording」
  </Accordion>

  <Accordion icon="bug" title="常見問題排除">
    **API 金鑰錯誤**

    ```
    Error: Invalid API key
    ```

    請確認您的 API 金鑰正確。

    **音訊格式不支援**

    ```
    Error: Unsupported audio format
    ```

    請確認音檔格式為 WAV, MP3, FLAC 或 AAC，採樣率在 8kHz-48kHz 範圍內。

    **配額超限**

    ```
    Error: Quota exceeded
    ```

    請檢查您的使用配額，或聯絡我們升級方案。
  </Accordion>
</AccordionGroup>

## 下一步

恭喜！您已經成功整合「聽有 AI」語音辨識服務。接下來您可以：

<CardGroup>
  <Card title="探索進階功能" icon="rocket" href="/essentials/voice-recognition">
    了解更多語音辨識的進階功能和最佳實踐
  </Card>

  <Card title="查看 API 參考" icon="book" href="/api-reference/introduction">
    完整的 API 文件和所有可用端點
  </Card>

  <Card title="技術支援" icon="headset" href="mailto:support@skiesoft.com">
    遇到問題？聯絡我們的技術支援團隊
  </Card>
</CardGroup>

## 範例專案

我們提供完整的範例專案供您參考：

* [Node.js 即時語音辨識範例](https://github.com/Skiesoft/voice-examples/tree/main/nodejs-realtime)
* [Python 批次處理範例](https://github.com/Skiesoft/voice-examples/tree/main/python-batch)
* [React 網頁語音輸入範例](https://github.com/Skiesoft/voice-examples/tree/main/react-voice-input)
* [Android 行動應用範例](https://github.com/Skiesoft/voice-examples/tree/main/android-app)

***

需要協助？請聯絡我們的技術支援團隊：[support@skiesoft.com](mailto:support@skiesoft.com) 或撥打 04-3702-8737