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

# OpenAI 格式 - 语音识别

> - 适用于所有兼容 OpenAI 格式语音识别模型的通用 Transcriptions API 参考
- 将音频文件转换为文本
- 支持的模型：`whisper-1`（主推）、`gpt-4o-transcribe`、`gpt-4o-mini-transcribe`、`cohere-transcribe`
- 支持指定语言、提示词引导风格与多种响应格式
- 各模型独有的字段（如时间戳粒度、流式、说话人分离、标点控制等）请参见页面下方的「模型参数说明」


## 模型参数说明

OpenAI 语音识别接口在不同模型上支持的字段存在差异。请求体只列出了**所有模型通用的核心字段**，下文说明各模型独有或受限的字段。

### 支持的模型

| 模型 ID                               | 用途                                          |
| ----------------------------------- | ------------------------------------------- |
| `whisper-1`                         | 经典 Whisper V2 模型，支持最完整的输出格式与时间戳粒度           |
| `gpt-4o-transcribe`                 | 高精度识别，仅支持 `json` 输出，可流式                     |
| `gpt-4o-mini-transcribe`            | 轻量版高精度识别，仅支持 `json` 输出，可流式                  |
| `gpt-4o-mini-transcribe-2025-12-15` | `gpt-4o-mini-transcribe` 的版本快照              |
| `gpt-4o-transcribe-diarize`         | 带说话人分离的识别，使用 `diarized_json` 获取每段说话人标注      |
| `cohere-transcribe`                 | Fal 平台托管的 Cohere 转写模型，支持 14 种语言，可控标点与最大输出长度 |

### `response_format` 各模型支持矩阵

| 模型                                                        | 支持的格式                                                           |
| --------------------------------------------------------- | --------------------------------------------------------------- |
| `whisper-1`                                               | `json` / `text` / `srt` / `verbose_json` / `vtt`                |
| `gpt-4o-transcribe`、`gpt-4o-mini-transcribe`(-2025-12-15) | 仅 `json`                                                        |
| `gpt-4o-transcribe-diarize`                               | `json` / `text` / `diarized_json`（要拿到说话人标注必须使用 `diarized_json`） |
| `cohere-transcribe`                                       | 仅 `json` / `text`                                               |

### `whisper-1` 独有特性

* **`timestamp_granularities[]`** — array，可选值 `word` / `segment`，默认 `[segment]`
  * 词级 / 段级时间戳粒度
  * **仅在 `response_format=verbose_json` 时生效**
  * 表单字段名以 `timestamp_granularities[]` 形式重复传递（数组）
  * gpt-4o-\* 系列因仅支持 `json`，实际无法使用此参数；`gpt-4o-transcribe-diarize` 明确禁用
* **不支持流式**：在 `whisper-1` 上传 `stream=true` 会被静默忽略。

### gpt-4o-\* 系列独有参数

适用于 `gpt-4o-transcribe`、`gpt-4o-mini-transcribe`、`gpt-4o-mini-transcribe-2025-12-15`。

* **`include[]`** — array，可选值仅 `logprobs`
  * 返回每个 token 的对数概率，用于评估模型识别置信度
  * **仅在 `response_format=json` 时**生效
  * 不适用于 `whisper-1` 与 `gpt-4o-transcribe-diarize`

* **`stream`** — boolean，默认 `false`
  * 通过 SSE（Server-Sent Events）流式返回识别结果
  * `whisper-1` 不支持，参数会被忽略

* **`chunking_strategy`** — `"auto"` 字符串 或 `server_vad` 对象
  * 控制音频如何切分为块。不传则整段音频作为一个块识别
  * 设为 `"auto"`：服务端先做响度归一化，再用 VAD 自动选择切分边界
  * 设为 `server_vad` 对象（手动调参 VAD）：

    | 字段                    | 类型      | 默认    | 说明                                   |
    | --------------------- | ------- | ----- | ------------------------------------ |
    | `type`                | string  | —     | **必填**，固定为 `"server_vad"`            |
    | `prefix_padding_ms`   | integer | `300` | VAD 检测到语音前包含的音频时长（毫秒）                |
    | `silence_duration_ms` | integer | `200` | 用于判定语音结束的静音时长（毫秒）。值越短响应越快，但可能在短停顿处误切 |

### `gpt-4o-transcribe-diarize` 独有参数

仅适用于 `gpt-4o-transcribe-diarize`（说话人分离专用模型）。

* **`chunking_strategy`** — 处理超过 30 秒的音频时**必传**（推荐 `"auto"`）

* **`known_speaker_names[]`** — array，最多 4 个
  * 已知说话人的标识列表（如 `customer`、`agent`）
  * 与 `known_speaker_references[]` 一一对应

* **`known_speaker_references[]`** — array，最多 4 个
  * 对应说话人的参考音频，使用 [data URL](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/Data_URLs) 格式
  * 每段需 2-10 秒
  * 支持的音频格式与 `file` 字段相同

### `gpt-4o-transcribe-diarize` 不支持的字段

以下字段在 `gpt-4o-transcribe-diarize` 上**不可用**：

| 字段                          | 说明                   |
| --------------------------- | -------------------- |
| `prompt`                    | 不支持提示词引导             |
| `timestamp_granularities[]` | 不支持词级 / 段级时间戳粒度配置    |
| `include[]`                 | 不支持 `logprobs` 等附加返回 |
| `stream`                    | 不支持流式输出              |

### `cohere-transcribe` 独有特性

由 Fal 平台托管的 Cohere 转写模型，支持 14 种语言（`en` / `fr` / `de` / `it` / `es` / `pt` / `el` / `nl` / `pl` / `zh` / `ja` / `ko` / `vi` / `ar`）。`language` 传其他取值时由上游返回错误。

#### 独有参数

* **`punctuation`** — boolean，默认 `true`
  * 控制识别结果是否保留标点符号

* **`max_new_tokens`** — integer，默认 `256`
  * 限制单次识别输出的最大 token 数

#### 不支持的字段

以下 OpenAI 标准字段在 `cohere-transcribe` 上**不可用**，传入后会被静默忽略（不会报错）：

| 字段                          | 说明                 |
| --------------------------- | ------------------ |
| `prompt`                    | 不支持提示词引导           |
| `temperature`               | 不支持温度参数            |
| `timestamp_granularities[]` | 不支持词级 / 段级时间戳      |
| `include[]`                 | 不支持 logprobs 等附加返回 |
| `stream`                    | 不支持流式输出            |
| `chunking_strategy`         | 不支持分块策略            |

`response_format` 仅支持 `json` / `text`，传入 `srt` / `vtt` / `verbose_json` / `diarized_json` 等其他值会返回 400。


## OpenAPI

````yaml openapi/zh/openai-format-transcriptions.json POST /v1/audio/transcriptions
openapi: 3.1.0
info:
  title: OpenAI Format - Transcriptions
  version: '1.0'
servers:
  - url: https://api.aihubmax.com
security:
  - BearerAuth: []
paths:
  /v1/audio/transcriptions:
    post:
      tags:
        - Text Series > OpenAI Format
      summary: OpenAI Format - Transcriptions
      description: >
        - 适用于所有兼容 OpenAI 格式语音识别模型的通用 Transcriptions API 参考

        - 将音频文件转换为文本

        -
        支持的模型：`whisper-1`（主推）、`gpt-4o-transcribe`、`gpt-4o-mini-transcribe`、`cohere-transcribe`

        - 支持指定语言、提示词引导风格与多种响应格式

        - 各模型独有的字段（如时间戳粒度、流式、说话人分离、标点控制等）请参见页面下方的「模型参数说明」
      operationId: openai-format-transcriptions
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/TranscriptionRequest'
      responses:
        '200':
          $ref: '#/components/responses/TranscriptionSuccess'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
components:
  schemas:
    TranscriptionRequest:
      type: object
      required:
        - file
        - model
      properties:
        file:
          type: string
          format: binary
          description: |
            待识别音频文件

            **说明：**
            - 通过 multipart/form-data 上传
            - 支持格式：flac / mp3 / mp4 / mpeg / mpga / m4a / ogg / wav / webm
        model:
          type: string
          description: >-
            语音识别模型
            ID，可选值：`whisper-1`、`gpt-4o-transcribe`、`gpt-4o-mini-transcribe`、`cohere-transcribe`
          example: whisper-1
        language:
          type: string
          description: >-
            音频语言（ISO-639-1 代码，如
            `en`、`zh`、`ja`）。提供该参数能提升识别准确度并加快处理速度。各模型支持的语言集存在差异，详见下方「模型参数说明」。
          example: zh
        prompt:
          type: string
          description: 用于引导模型识别风格或延续上一段音频的可选文本。提示词需与音频语言一致。
        response_format:
          type: string
          description: 响应格式
          enum:
            - json
            - text
            - srt
            - verbose_json
            - vtt
          default: json
        temperature:
          type: number
          description: 采样温度，取值 0-1。值越高输出越随机，0 表示模型自动调整。
          minimum: 0
          maximum: 1
          default: 0
        punctuation:
          type: boolean
          description: 是否保留标点符号。仅 `cohere-transcribe` 支持，默认为 `true`；传给其他模型会被忽略。
        max_new_tokens:
          type: integer
          description: 限制单次识别输出的最大 token 数。仅 `cohere-transcribe` 支持，默认为 `256`；传给其他模型会被忽略。
    TranscriptionResponse:
      type: object
      required:
        - text
      properties:
        text:
          type: string
          description: 识别得到的文本
          example: 今天天气不错，我们去公园散步吧。
    TranscriptionVerboseResponse:
      type: object
      required:
        - task
        - language
        - duration
        - text
      properties:
        task:
          type: string
          description: 任务类型
          enum:
            - transcribe
        language:
          type: string
          description: 检测到的音频语言
          example: chinese
        duration:
          type: number
          description: 音频时长（秒）
          example: 5.32
        text:
          type: string
          description: 完整的识别文本
          example: 今天天气不错，我们去公园散步吧。
        words:
          type: array
          description: 词级时间戳列表（仅 whisper-1 + verbose_json 时返回，详见下方「模型参数说明」）
          items:
            type: object
            properties:
              word:
                type: string
                description: 词内容
                example: 今天
              start:
                type: number
                description: 起始时间（秒）
                example: 0
              end:
                type: number
                description: 结束时间（秒）
                example: 0.42
        segments:
          type: array
          description: 段级详细信息（仅 whisper-1 + verbose_json 时返回，详见下方「模型参数说明」）
          items:
            type: object
            properties:
              id:
                type: integer
                description: 段索引
                example: 0
              seek:
                type: integer
                description: 段起始 seek 偏移
                example: 0
              start:
                type: number
                description: 段起始时间（秒）
                example: 0
              end:
                type: number
                description: 段结束时间（秒）
                example: 5.32
              text:
                type: string
                description: 段文本
                example: 今天天气不错，我们去公园散步吧。
              tokens:
                type: array
                description: 段对应的 token 列表
                items:
                  type: integer
              temperature:
                type: number
                description: 采样温度
                example: 0
              avg_logprob:
                type: number
                description: 平均对数概率
                example: -0.32
              compression_ratio:
                type: number
                description: 压缩比
                example: 1.21
              no_speech_prob:
                type: number
                description: 无语音概率
                example: 0.02
    ErrorResponse400:
      type: object
      properties:
        error:
          type: object
          properties:
            message:
              type: string
              example: 请求参数无效
            type:
              type: string
              example: invalid_request_error
    ErrorResponse401:
      type: object
      properties:
        error:
          type: object
          properties:
            message:
              type: string
              example: API密钥无效
            type:
              type: string
              example: authentication_error
    ErrorResponse403:
      type: object
      properties:
        error:
          type: object
          properties:
            message:
              type: string
              example: 访问被拒绝
            type:
              type: string
              example: permission_error
    ErrorResponse429:
      type: object
      properties:
        error:
          type: object
          properties:
            message:
              type: string
              example: 请求频率超限
            type:
              type: string
              example: rate_limit_error
    ErrorResponse500:
      type: object
      properties:
        error:
          type: object
          properties:
            message:
              type: string
              example: 服务器内部错误
            type:
              type: string
              example: server_error
  responses:
    TranscriptionSuccess:
      description: 语音识别响应
      content:
        application/json:
          schema:
            oneOf:
              - $ref: '#/components/schemas/TranscriptionResponse'
              - $ref: '#/components/schemas/TranscriptionVerboseResponse'
          examples:
            default-json:
              summary: 默认 JSON 响应
              description: '`response_format=json`（默认）时返回'
              value:
                text: 今天天气不错，我们去公园散步吧。
            verbose-json:
              summary: 详细 JSON 响应
              description: >-
                whisper-1 在 `response_format=verbose_json`
                且开启词级时间戳粒度时返回（详见下方「模型参数说明」）
              value:
                task: transcribe
                language: chinese
                duration: 5.32
                text: 今天天气不错，我们去公园散步吧。
                words:
                  - word: 今天
                    start: 0
                    end: 0.42
                  - word: 天气不错
                    start: 0.42
                    end: 1.36
                segments:
                  - id: 0
                    seek: 0
                    start: 0
                    end: 5.32
                    text: 今天天气不错，我们去公园散步吧。
                    tokens:
                      - 50364
                      - 1029
                      - 31935
                    temperature: 0
                    avg_logprob: -0.32
                    compression_ratio: 1.21
                    no_speech_prob: 0.02
        text/plain:
          schema:
            type: string
          examples:
            text:
              summary: 纯文本响应
              description: '`response_format=text` 时返回'
              value: 今天天气不错，我们去公园散步吧。
            srt:
              summary: SRT 字幕响应
              description: '`response_format=srt` 时返回'
              value: |
                1
                00:00:00,000 --> 00:00:05,320
                今天天气不错，我们去公园散步吧。
            vtt:
              summary: VTT 字幕响应
              description: '`response_format=vtt` 时返回'
              value: |
                WEBVTT

                00:00:00.000 --> 00:00:05.320
                今天天气不错，我们去公园散步吧。
    BadRequest:
      description: 请求错误
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse400'
    Unauthorized:
      description: 未授权
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse401'
    PaymentRequired:
      description: 余额不足
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse400'
    Forbidden:
      description: 禁止访问
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse403'
    TooManyRequests:
      description: 请求过多
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse429'
    InternalServerError:
      description: 服务器内部错误
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse500'
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: |
        ## 所有接口均需要使用Bearer Token进行认证 ##

        使用时在请求头中添加：

        `Authorization: Bearer YOUR_API_KEY`

````