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

# 語音轉文字

> 將音訊轉錄為輸入語言。相容於 OpenAI API 格式，並支援額外的說話者分類。



## OpenAPI

````yaml api-reference/openapi.json post /audio/transcriptions
openapi: 3.1.0
info:
  title: 軟雲聽有 AI API
  description: Skiesoft「聽有 AI」語音辨識服務 API，支援國台英混合語言辨識、即時串流處理和語音轉文字功能。提供高準確度的語音辨識、說話者分離等進階功能。
  version: 1.0.0
  contact:
    name: 軟雲技術支援
    email: support@skiesoft.com
    url: https://skiesoft.com
  license:
    name: Proprietary
    url: https://skiesoft.com/terms-of-service
  termsOfService: https://skiesoft.com/terms-of-service
servers:
  - url: https://api.skiesoft.com/v1
security:
  - bearerAuth: []
tags:
  - name: 語音辨識
    description: 音訊轉錄和語音辨識功能，支援說話者分離
  - name: 即時語音辨識
    description: WebSocket 即時語音串流辨識，支援低延遲的即時文字轉錄
  - name: 帳號管理
    description: 帳號資訊和使用量查詢
paths:
  /audio/transcriptions:
    post:
      tags:
        - 語音辨識
      summary: 語音轉文字
      description: 將音訊轉錄為輸入語言。相容於 OpenAI API 格式，並支援額外的說話者分類。
      operationId: transcribeAudio
      requestBody:
        description: 音訊檔案和辨識參數
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/TranscribeRequest'
            examples:
              basic_transcription:
                summary: 基本轉錄
                value:
                  file: audio.wav
                  model: thiannu-v1
              with_speaker_diarization:
                summary: 啟用說話者分離
                value:
                  file: audio.wav
                  model: thiannu-v1
                  speaker_diarization: true
      responses:
        '200':
          description: 轉錄成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TranscribeResponseJson'
              examples:
                json_format:
                  summary: 詳細 JSON 格式回應
                  value:
                    task: transcribe
                    duration: 6.5
                    text: 你好，歡迎使用聽有 AI。這是一個測試錄音。
                    segments:
                      - id: 0
                        start: 0
                        end: 6.5
                        text: 你好，歡迎使用聽有 AI。這是一個測試錄音。
                with_speaker_diarization:
                  summary: 啟用說話者分離的詳細回應
                  value:
                    task: transcribe
                    duration: 6.5
                    text: 你好，歡迎使用聽有 AI。這是一個測試錄音。
                    segments:
                      - id: 0
                        start: 0
                        end: 3.2
                        text: 你好，歡迎使用聽有 AI
                        speaker: 1
                      - id: 1
                        start: 3.2
                        end: 6.5
                        text: 這是一個測試錄音。
                        speaker: 1
                    num_speakers: 2
            text/plain:
              schema:
                type: string
                description: 純文字格式的轉錄結果
                example: 你好，歡迎使用聽有 AI。這是一個測試錄音。
        '400':
          description: 請求格式錯誤
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                invalid_audio:
                  summary: 無效的音訊格式
                  value:
                    error:
                      message: 不支援的音訊格式。請使用支援的格式：mp3、wav 或是 webm。
                      type: invalid_request_error
                      param: file
                      code: invalid_file_format
                audio_too_long:
                  summary: 音訊檔案太長
                  value:
                    error:
                      message: 音訊檔案太長，最多支援 100MB 或 4 小時。
                      type: invalid_request_error
                      param: file
                      code: file_too_large
        '401':
          description: 身份驗證失敗
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                invalid_api_key:
                  summary: 無效的 API 金鑰
                  value:
                    error:
                      message: 無效的 API 金鑰。請檢查您的 API 金鑰是否正確。
                      type: invalid_request_error
                      code: invalid_api_key
        '403':
          description: 權限不足
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '413':
          description: 檔案太大
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                file_too_large:
                  summary: 檔案大小超過限制
                  value:
                    error:
                      message: 檔案大小超過 100MB 限制
                      type: invalid_request_error
                      param: file
                      code: file_too_large
        '429':
          description: 請求頻率過高
          headers:
            X-RateLimit-Retry-After:
              description: 建議重試等待時間（秒）
              schema:
                type: integer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                rate_limit:
                  summary: 超過速率限制
                  value:
                    error:
                      message: 請求頻率過高，請稍後再試
                      type: rate_limit_error
                      code: rate_limit_exceeded
        '500':
          description: 伺服器內部錯誤
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: 服務暫時無法使用
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    TranscribeRequest:
      type: object
      required:
        - file
        - model
      properties:
        file:
          type: string
          format: binary
          description: 要轉錄的音訊檔案物件（不是檔案名稱），支援以下格式：mp3、wav、webm。
        model:
          type: string
          description: 要使用的模型 ID
          enum:
            - thiannu-v1
          example: thiannu-v1
        speaker_diarization:
          type: boolean
          description: 啟用說話者分離功能，可識別和區分不同的說話者。這是 軟雲聽有 AI 的獨有功能。
          default: false
          example: true
    TranscribeResponseJson:
      type: object
      required:
        - task
        - duration
        - text
        - segments
      properties:
        task:
          type: string
          description: 執行的任務類型。
          enum:
            - transcribe
          example: transcribe
        duration:
          type: number
          description: 音訊的持續時間，以秒為單位。
          example: 6.5
        text:
          type: string
          description: 完整的轉錄文字內容。
          example: 你好，歡迎使用聽有 AI。這是一個測試錄音。
        segments:
          type: array
          description: >-
            從音訊中提取的片段，包含時間戳記、標記和其他元資料。僅在 timestamp_granularities 請求包含 segment
            時包含。
          items:
            $ref: '#/components/schemas/TranscriptionSegment'
        num_speakers:
          type: number
          description: 偵測到的說話者數量
    Error:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          required:
            - message
            - type
          properties:
            message:
              type: string
              description: 錯誤的人類可讀描述。
              example: 無效的 API 金鑰
            type:
              type: string
              description: 錯誤類型。
              example: invalid_request_error
            param:
              type: string
              description: 導致錯誤的參數（如果適用）。
              example: file
            code:
              type: string
              description: 錯誤代碼（如果適用）。
              example: invalid_api_key
    TranscriptionSegment:
      type: object
      required:
        - id
        - start
        - end
        - text
      properties:
        id:
          type: integer
          description: 片段的唯一識別碼。
          example: 0
        start:
          type: number
          description: 片段的開始時間，以秒為單位。
          example: 0
        end:
          type: number
          description: 片段的結束時間，以秒為單位。
          example: 6.5
        text:
          type: string
          description: 片段的文字內容。
          example: 你好，歡迎使用聽有 AI。這是一個測試錄音。
        speaker:
          type: integer
          description: 說話者 ID（僅在啟用說話者分離時提供）。
          example: 1
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 使用 API 金鑰進行身份驗證。格式：Bearer YOUR_API_KEY

````