# Whisper Audio Transcription

> Audio Generation

Transcribe an uploaded audio file with `whisper-1`.
The endpoint accepts `multipart/form-data` and is compatible with the
OpenAI `/v1/audio/transcriptions` path. The model supports `json`,
`text`, and `verbose_json` response formats. It does **not** support
`srt`, `vtt`, or streaming (`stream`).

## Endpoint

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

## Request Body

## Responses

- **200** — Transcription response. JSON by default; plain text for
`response_format=text`; verbose JSON with `duration`, `language`,
and `segments` for `response_format=verbose_json`.

- **400** — Invalid request parameters (e.g. unsupported response_format srt/vtt).
- **default** — Error response.

## OpenAPI Definition

```json
{
  "openapi": "3.1.0",
  "x-language": "en-US",
  "info": {
    "title": "ModelVerse Whisper Audio API",
    "version": "1.0.0",
    "description": "Self-contained OpenAPI 3.1 schema for the ModelVerse OpenAI-compatible\n`whisper-1` audio transcription API. Billed per audio duration (seconds).\n"
  },
  "servers": [
    {
      "url": "https://api.modelverse.cn",
      "description": "ModelVerse API endpoint shown in the source document."
    }
  ],
  "tags": [
    {
      "name": "Whisper",
      "description": "Audio transcription with `whisper-1`, billed per audio duration (seconds)."
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "paths": {
    "/v1/audio/transcriptions": {
      "post": {
        "tags": [
          "Whisper"
        ],
        "operationId": "createWhisperTranscription",
        "summary": "Whisper Audio Transcription",
        "description": "Transcribe an uploaded audio file with `whisper-1`.\nThe endpoint accepts `multipart/form-data` and is compatible with the\nOpenAI `/v1/audio/transcriptions` path. The model supports `json`,\n`text`, and `verbose_json` response formats. It does **not** support\n`srt`, `vtt`, or streaming (`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": "Minimal transcription",
                  "value": {
                    "model": "whisper-1",
                    "file": "/path/to/audio.mp3"
                  }
                },
                "specifiedLanguage": {
                  "summary": "Transcribe with an explicit ISO-639-1 language",
                  "value": {
                    "model": "whisper-1",
                    "file": "/path/to/audio.mp3",
                    "language": "zh"
                  }
                },
                "verbose": {
                  "summary": "Verbose format (with timestamps and duration)",
                  "value": {
                    "model": "whisper-1",
                    "file": "/path/to/audio.mp3",
                    "response_format": "verbose_json"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Transcription response. JSON by default; plain text for\n`response_format=text`; verbose JSON with `duration`, `language`,\nand `segments` for `response_format=verbose_json`.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WhisperJsonResponse"
                },
                "examples": {
                  "defaultJson": {
                    "summary": "Default JSON transcription",
                    "value": {
                      "text": "The weather is nice today, let's go for a walk in the park."
                    }
                  },
                  "verboseJson": {
                    "summary": "Verbose JSON transcription",
                    "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": "Raw transcription text when `response_format=text` (UTF-8 encoded)."
                },
                "examples": {
                  "plainText": {
                    "summary": "Plain text transcription",
                    "value": "The weather is nice today, let's go for a walk in the park."
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid request parameters (e.g. unsupported response_format srt/vtt).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WhisperErrorResponse"
                },
                "examples": {
                  "error": {
                    "$ref": "#/components/examples/WhisperError"
                  }
                }
              }
            }
          },
          "default": {
            "description": "Error response.",
            "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": "Provide the ModelVerse API Key in the Authorization header\n(`Bearer <api_key>`).\n"
      }
    },
    "schemas": {
      "WhisperRequest": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "model",
          "file"
        ],
        "properties": {
          "model": {
            "type": "string",
            "const": "whisper-1",
            "description": "Model name, fixed to `whisper-1`."
          },
          "file": {
            "type": "string",
            "format": "binary",
            "description": "The audio file to transcribe. Supported formats: `flac`, `m4a`,\n`mp3`, `mp4`, `mpga`, `ogg`, `wav`, `webm`; the `.oga` extension is\nnot supported (use `.ogg` instead); `mpeg` may produce inaccurate\ntranscription due to lower encoding quality. File size limit 25 MB.\n"
          },
          "language": {
            "type": "string",
            "pattern": "^[a-z]{2}$",
            "description": "Audio language in ISO-639-1 format (e.g. `zh`, `en`, `ja`).\nSpecifying the language explicitly improves accuracy and latency;\nif omitted, the model auto-detects.\n",
            "examples": [
              "zh",
              "en",
              "ja"
            ]
          },
          "prompt": {
            "type": "string",
            "description": "Optional text to guide the model's transcription style. Must match\nthe audio language. Can be used to continue a previous audio segment\nor unify terminology.\n"
          },
          "response_format": {
            "type": "string",
            "enum": [
              "json",
              "text",
              "verbose_json"
            ],
            "default": "json",
            "description": "Output format. `whisper-1` supports `json`, `text`, and\n`verbose_json`; **`srt` and `vtt` are not supported** and will\nreturn an error. For subtitle timestamps, use `verbose_json` and\nparse the `start`/`end` fields from the `segments` array.\n"
          },
          "temperature": {
            "type": "number",
            "minimum": 0,
            "maximum": 1,
            "default": 0,
            "description": "Sampling temperature from 0 to 1. At 0 the model adjusts\nautomatically; higher values produce more varied output. Azure does\nnot error above 1, but output may contain garbled text — keep within\n0–1.\n"
          }
        }
      },
      "WhisperJsonResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "text"
        ],
        "properties": {
          "text": {
            "type": "string",
            "description": "The transcribed text."
          }
        }
      },
      "WhisperVerboseJsonResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "task",
          "language",
          "duration",
          "text",
          "segments"
        ],
        "properties": {
          "task": {
            "type": "string",
            "const": "transcribe",
            "description": "Task type, fixed to `transcribe`."
          },
          "language": {
            "type": "string",
            "description": "Detected audio language (e.g. `chinese`, `english`)."
          },
          "duration": {
            "type": "number",
            "description": "Audio duration in seconds; the source of billing usage."
          },
          "text": {
            "type": "string",
            "description": "Full transcribed text."
          },
          "segments": {
            "type": "array",
            "description": "Array of segments, each containing `start`/`end`/`text` and other fields; usable for subtitle generation.",
            "items": {
              "$ref": "#/components/schemas/WhisperSegment"
            }
          }
        }
      },
      "WhisperSegment": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "id": {
            "type": "integer"
          },
          "seek": {
            "type": "integer"
          },
          "start": {
            "type": "number",
            "description": "Segment start time in seconds."
          },
          "end": {
            "type": "number",
            "description": "Segment end time in seconds."
          },
          "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": "Error description."
          },
          "type": {
            "type": "string",
            "description": "Error type.",
            "examples": [
              "invalid_request_error"
            ]
          },
          "code": {
            "type": "string",
            "description": "Machine-readable error code.",
            "examples": [
              "error_code"
            ]
          },
          "param": {
            "type": "string",
            "description": "Request ID used for feedback or troubleshooting."
          }
        }
      }
    },
    "examples": {
      "WhisperError": {
        "summary": "Standard JSON error response",
        "value": {
          "error": {
            "message": "Error description",
            "type": "invalid_request_error",
            "code": "error_code",
            "param": "<request ID, used for feedback or troubleshooting>"
          }
        }
      }
    }
  }
}
```