# Whisper-1 音频转写

> 音频生成

提交音频转写请求。上传音频文件后，响应返回转写文本及相关元数据。
`whisper-1` 按音频时长（秒）计费，支持 `json`、`text`、`verbose_json` 三种响应格式；
**不支持 `srt`、`vtt`，也不支持流式（`stream`）**。

## 请求地址

`POST https://api.modelverse.cn/v1/audio/transcriptions`

## 请求体

## 响应

- **200** — 转写响应。默认返回 JSON；`response_format=text` 返回纯文本；
`response_format=verbose_json` 返回带 `duration`、`language`、`segments` 的详细结构。

- **400** — 请求参数无效（如使用了不支持的 `response_format`：`srt`/`vtt`）。
- **default** — 错误响应。

## OpenAPI 定义

```json
{
  "openapi": "3.1.0",
  "x-language": "zh-CN",
  "info": {
    "title": "whisper-1接口文档",
    "version": "1.0.0",
    "description": "这是 ModelVerse 上 `whisper-1` 的音频转写接口文档，说明如何上传音频、获取转写结果以及处理错误。\n接口路径为 `POST /v1/audio/transcriptions`。按音频时长（秒）计费。\n"
  },
  "servers": [
    {
      "url": "https://api.modelverse.cn",
      "description": "ModelVerse API endpoint shown in the source document."
    }
  ],
  "tags": [
    {
      "name": "Whisper-1",
      "description": "Audio transcription with `whisper-1`, billed per audio duration (seconds)."
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "paths": {
    "/v1/audio/transcriptions": {
      "post": {
        "tags": [
          "Whisper-1"
        ],
        "operationId": "createWhisperTranscription",
        "summary": "Whisper-1 音频转写",
        "description": "提交音频转写请求。上传音频文件后，响应返回转写文本及相关元数据。\n`whisper-1` 按音频时长（秒）计费，支持 `json`、`text`、`verbose_json` 三种响应格式；\n**不支持 `srt`、`vtt`，也不支持流式（`stream`）**。\n",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "$ref": "#/components/schemas/WhisperRequest"
              },
              "encoding": {
                "file": {
                  "contentType": "application/octet-stream"
                }
              },
              "examples": {
                "minimal": {
                  "summary": "最简音频转写",
                  "value": {
                    "model": "whisper-1",
                    "file": "/path/to/audio.mp3"
                  }
                },
                "specifiedLanguage": {
                  "summary": "指定 ISO-639-1 语言",
                  "value": {
                    "model": "whisper-1",
                    "file": "/path/to/audio.mp3",
                    "language": "zh"
                  }
                },
                "verbose": {
                  "summary": "详细格式（带时间轴与 duration）",
                  "value": {
                    "model": "whisper-1",
                    "file": "/path/to/audio.mp3",
                    "response_format": "verbose_json"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "转写响应。默认返回 JSON；`response_format=text` 返回纯文本；\n`response_format=verbose_json` 返回带 `duration`、`language`、`segments` 的详细结构。\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WhisperJsonResponse"
                },
                "examples": {
                  "defaultJson": {
                    "summary": "默认 JSON 转写",
                    "value": {
                      "text": "今天天气真好，我们去公园散步吧。"
                    }
                  },
                  "verboseJson": {
                    "summary": "详细 JSON 转写",
                    "value": {
                      "task": "transcribe",
                      "language": "english",
                      "duration": 5.06,
                      "text": "This is a test song.",
                      "segments": [
                        {
                          "id": 0,
                          "seek": 0,
                          "start": 0,
                          "end": 2,
                          "text": " This is a test song.",
                          "tokens": [
                            50364,
                            220,
                            5723
                          ],
                          "temperature": 0,
                          "avg_logprob": -0.67,
                          "compression_ratio": 0.77,
                          "no_speech_prob": 0.16
                        }
                      ]
                    }
                  }
                }
              },
              "text/plain": {
                "schema": {
                  "type": "string",
                  "description": "纯文本转写结果（UTF-8 编码），当 response_format=text 时返回。"
                },
                "examples": {
                  "plainText": {
                    "summary": "纯文本转写",
                    "value": "今天天气真好，我们去公园散步吧。"
                  }
                }
              }
            }
          },
          "400": {
            "description": "请求参数无效（如使用了不支持的 `response_format`：`srt`/`vtt`）。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WhisperErrorResponse"
                },
                "examples": {
                  "error": {
                    "$ref": "#/components/examples/WhisperError"
                  }
                }
              }
            }
          },
          "default": {
            "description": "错误响应。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WhisperErrorResponse"
                },
                "examples": {
                  "error": {
                    "$ref": "#/components/examples/WhisperError"
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "API key",
        "description": "在 Authorization 头中传入 ModelVerse API Key（`Bearer <api_key>`）。\n"
      }
    },
    "schemas": {
      "WhisperRequest": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "model",
          "file"
        ],
        "properties": {
          "model": {
            "type": "string",
            "const": "whisper-1",
            "description": "模型名称，固定为 `whisper-1`。"
          },
          "file": {
            "type": "string",
            "format": "binary",
            "description": "待转写的音频文件。支持格式 `flac`、`m4a`、`mp3`、`mp4`、`mpga`、\n`ogg`、`wav`、`webm`；不支持 `.oga` 扩展名（请用 `.ogg` 代替）；\n`mpeg` 格式因编码质量较低可能导致识别不准确。文件大小上限 25 MB。\n"
          },
          "language": {
            "type": "string",
            "pattern": "^[a-z]{2}$",
            "description": "音频语言，ISO-639-1 格式（如 `zh`、`en`、`ja`）。显式指定语言可提升\n准确率与响应速度；不传则由模型自动检测。\n",
            "examples": [
              "zh",
              "en",
              "ja"
            ]
          },
          "prompt": {
            "type": "string",
            "description": "引导模型转录风格的提示词，需与音频语言一致。可用于续接前段音频或统一术语表达。\n"
          },
          "response_format": {
            "type": "string",
            "enum": [
              "json",
              "text",
              "verbose_json"
            ],
            "default": "json",
            "description": "输出格式。`whisper-1` 支持 `json`、`text`、`verbose_json`；\n**不支持 `srt`、`vtt`**，使用时会返回错误。如需字幕时间轴，请使用\n`verbose_json` 并从 `segments` 数组中解析 `start`/`end` 字段。\n"
          },
          "temperature": {
            "type": "number",
            "minimum": 0,
            "maximum": 1,
            "default": 0,
            "description": "采样温度，范围 0–1。设为 0 时模型自动调节；较高值使输出更多样，\n较低值更确定。超过 1 时 Azure 不会报错，但输出可能出现乱码，请保持在 0–1 范围内。\n"
          }
        }
      },
      "WhisperJsonResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "text"
        ],
        "properties": {
          "text": {
            "type": "string",
            "description": "转写后的文字。"
          }
        }
      },
      "WhisperVerboseJsonResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "task",
          "language",
          "duration",
          "text",
          "segments"
        ],
        "properties": {
          "task": {
            "type": "string",
            "const": "transcribe",
            "description": "任务类型，固定为 `transcribe`。"
          },
          "language": {
            "type": "string",
            "description": "检测到的音频语言（如 `chinese`、`english`）。"
          },
          "duration": {
            "type": "number",
            "description": "音频时长（秒），也是计费用量的来源。"
          },
          "text": {
            "type": "string",
            "description": "完整转写文字。"
          },
          "segments": {
            "type": "array",
            "description": "分段信息数组，每个元素含 `start`/`end`/`text` 等字段，可用于生成字幕。",
            "items": {
              "$ref": "#/components/schemas/WhisperSegment"
            }
          }
        }
      },
      "WhisperSegment": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "id": {
            "type": "integer"
          },
          "seek": {
            "type": "integer"
          },
          "start": {
            "type": "number",
            "description": "段起始时间（秒）。"
          },
          "end": {
            "type": "number",
            "description": "段结束时间（秒）。"
          },
          "text": {
            "type": "string"
          },
          "tokens": {
            "type": "array",
            "items": {
              "type": "integer"
            }
          },
          "temperature": {
            "type": "number"
          },
          "avg_logprob": {
            "type": "number"
          },
          "compression_ratio": {
            "type": "number"
          },
          "no_speech_prob": {
            "type": "number"
          }
        }
      },
      "WhisperErrorResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "$ref": "#/components/schemas/WhisperError"
          }
        }
      },
      "WhisperError": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "message",
          "type",
          "code",
          "param"
        ],
        "properties": {
          "message": {
            "type": "string",
            "description": "错误说明。"
          },
          "type": {
            "type": "string",
            "description": "错误类型。",
            "examples": [
              "invalid_request_error"
            ]
          },
          "code": {
            "type": "string",
            "description": "机器可读的错误码。",
            "examples": [
              "error_code"
            ]
          },
          "param": {
            "type": "string",
            "description": "请求 ID，用于反馈或排查错误原因。"
          }
        }
      }
    },
    "examples": {
      "WhisperError": {
        "summary": "标准 JSON 错误响应",
        "value": {
          "error": {
            "message": "错误描述信息",
            "type": "invalid_request_error",
            "code": "error_code",
            "param": "<请求 ID，用于反馈或排查错误原因>"
          }
        }
      }
    }
  }
}
```