> ## 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.

# 身份驗證

> 了解如何安全地使用 軟雲API 金鑰進行身份驗證

## API 金鑰驗證

Skiesoft「聽有 AI」使用 API 金鑰進行身份驗證。每個請求都必須在標頭中包含有效的 API 金鑰。

### 取得 API 金鑰

1. 前往 [軟雲開發者控制台](https://developer.skiesoft.com)
2. 登入您的帳號或建立新帳號
3. 建立新的 API 金鑰
4. 記錄您的 `API_KEY`

<Warning>
  請妥善保管您的 API 金鑰，不要在公開的程式碼庫中暴露金鑰資訊。
</Warning>

### 驗證方式

所有 API 請求都必須在 HTTP 標頭中包含以下資訊：

```http theme={null}
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
```

### 環境變數設定

建議使用環境變數來儲存敏感資訊：

<CodeGroup>
  ```bash .env theme={null}
  SKIESOFT_API_KEY=sk_ski_1234567890abcdef
  ```

  ```bash Linux/macOS theme={null}
  export SKIESOFT_API_KEY="sk_ski_1234567890abcdef"
  ```

  ```powershell Windows PowerShell theme={null}
  $env:SKIESOFT_API_KEY="sk_ski_1234567890abcdef"
  ```
</CodeGroup>

### 測試驗證

使用以下程式碼測試您的 API 金鑰是否正確設定：

<CodeGroup>
  ```javascript Node.js theme={null}
  async function testAuthentication() {
    try {
      const result = await client.getAccountInfo();
      console.log('驗證成功！');
      console.log('帳號資訊:', result);
    } catch (error) {
      console.error('驗證失敗:', error.message);
    }
  }

  testAuthentication();
  ```

  ```python Python theme={null}
  async def test_authentication():
      try:
          result = await client.get_account_info()
          print('驗證成功！')
          print('帳號資訊:', result)
      except Exception as error:
          print('驗證失敗:', str(error))

  # 執行測試
  import asyncio
  asyncio.run(test_authentication())
  ```

  ```bash cURL theme={null}
  curl -X GET "https://api.skiesoft.com/v1/account" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "X-Project-ID: YOUR_PROJECT_ID" \
    -H "Content-Type: application/json"
  ```
</CodeGroup>

## 安全最佳實踐

### 1. 金鑰管理

* **不要硬編碼**：永遠不要在程式碼中硬編碼 API 金鑰
* **使用環境變數**：將金鑰儲存在環境變數或安全的配置檔案中
* **定期輪換**：定期更新您的 API 金鑰
* **最小權限原則**：只授予必要的權限給 API 金鑰

### 2. 網路安全

* **使用 HTTPS**：所有 API 請求都必須使用 HTTPS
* **IP 白名單**：在控制台中設定 IP 白名單限制存取
* **請求簽名**：對於高安全性需求，可啟用請求簽名驗證

### 3. 錯誤處理

正確處理驗證錯誤：

```javascript theme={null}
try {
  const result = await client.transcribe(audioData);
} catch (error) {
  switch (error.code) {
    case 'INVALID_API_KEY':
      console.error('API 金鑰無效，請檢查您的金鑰');
      break;
    case 'PROJECT_NOT_FOUND':
      console.error('專案 ID 不存在');
      break;
    case 'QUOTA_EXCEEDED':
      console.error('配額已用完，請升級方案');
      break;
    case 'RATE_LIMIT_EXCEEDED':
      console.error('請求頻率過高，請稍後再試');
      break;
    default:
      console.error('未知錯誤:', error.message);
  }
}
```

## 開發與正式環境

### 測試環境

用於開發和測試的環境：

```javascript theme={null}
const testClient = new SkiesoftVoice({
  apiKey: 'sk_test_1234567890abcdef',
  projectId: 'proj_test_abcdef123456',
  endpoint: 'https://api-test.skiesoft.com/v1'
});
```

### 正式環境

用於生產環境的設定：

```javascript theme={null}
const prodClient = new SkiesoftVoice({
  apiKey: process.env.SKIESOFT_API_KEY, // sk_live_...
  projectId: process.env.SKIESOFT_PROJECT_ID,
  endpoint: 'https://api.skiesoft.com/v1'
});
```

## 配額與限制

每個 API 金鑰都有使用配額和頻率限制：

| 方案   | 每月配額       | 每秒請求數 | 並發連線數 |
| ---- | ---------- | ----- | ----- |
| 免費試用 | 1,000 分鐘   | 5     | 2     |
| 基礎方案 | 10,000 分鐘  | 20    | 5     |
| 專業方案 | 100,000 分鐘 | 50    | 20    |
| 企業方案 | 無限制        | 100   | 50    |

### 監控使用量

```javascript theme={null}
// 取得當前使用量
const usage = await client.getUsage();
console.log('本月已使用:', usage.currentMonth);
console.log('剩餘配額:', usage.remaining);
console.log('重置日期:', usage.resetDate);
```

## 常見問題

### Q: API 金鑰格式是什麼？

A: 測試環境金鑰以 `sk_test_` 開頭，正式環境金鑰以 `sk_live_` 開頭，後面跟著 32 位英數字元。

### Q: 如何重新產生 API 金鑰？

A: 在開發者控制台的專案設定中，點擊「重新產生金鑰」按鈕。舊金鑰將立即失效。

### Q: 可以同時使用多個 API 金鑰嗎？

A: 可以，每個專案可以產生多個 API 金鑰，方便不同環境或應用程式使用。

***

需要協助設定身份驗證？請聯絡我們的技術支援：[support@skiesoft.com](mailto:support@skiesoft.com)