# Scribe V2 Audio Transcription

> Audio Generation

Transcribe an uploaded audio file or a remote audio URL. Returns the
transcript, detected language, probabilities, and word-level timestamps.

**Content-Type**: `multipart/form-data`

**Audio source**: provide either `file` or `source_url` (at least one).

**Response shapes**:
- Single channel: `language_code`, `language_probability`, `text`, `words`, `audio_duration_secs`
- Multi-channel (`use_multi_channel=true` with `multichannel_output_style=separate`): one entry per channel under `transcripts`
- Diarization (`diarize=true`): `words[].speaker_id` identifies the speaker

## Endpoint

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

## Request Body

## Responses

- **200** — Transcription succeeded. The response is the official ElevenLabs JSON
structure. Single-channel requests return one transcript object;
multi-channel requests with `multichannel_output_style=separate`
return a `transcripts` array.

- **400** — Invalid parameters, e.g. neither `file` nor `source_url` was provided, or `stream`/`webhook` was requested.
- **401** — Authentication failed.
- **default** — Other errors. Upstream ElevenLabs error details are passed through.

## OpenAPI Definition

```json
{
  "openapi": "3.1.0",
  "x-language": "en-US",
  "info": {
    "title": "ModelVerse Scribe V2 Audio API",
    "version": "1.0.0",
    "description": "Self-contained OpenAPI 3.1 schema for the ModelVerse `scribe-v2` audio\ntranscription API. `scribe-v2` is powered by ElevenLabs Scribe v2 and is\nexposed through the OpenAI-compatible `POST /v1/audio/transcriptions` path.\nThe response is the official ElevenLabs JSON structure passed through as-is.\nBilled per audio duration (seconds), rounded up to the next second.\n\n**Capabilities**: 90+ languages, word/character timestamps, speaker\ndiarization (up to 32 speakers), keyterm prompting, multi-channel\ntranscription, verbatim removal, and context biasing.\n\n**Limitations**: streaming (`stream`), webhook delivery (`webhook`), and\n`srt`/`vtt` outputs are not supported.\n"
  },
  "servers": [
    {
      "url": "https://api.modelverse.cn",
      "description": "ModelVerse API endpoint"
    }
  ],
  "tags": [
    {
      "name": "Scribe-V2",
      "description": "ElevenLabs Scribe v2 transcription, billed per audio duration."
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "paths": {
    "/v1/audio/transcriptions": {
      "post": {
        "tags": [
          "Scribe-V2"
        ],
        "operationId": "createScribeV2Transcription",
        "summary": "Scribe V2 Audio Transcription",
        "description": "Transcribe an uploaded audio file or a remote audio URL. Returns the\ntranscript, detected language, probabilities, and word-level timestamps.\n\n**Content-Type**: `multipart/form-data`\n\n**Audio source**: provide either `file` or `source_url` (at least one).\n\n**Response shapes**:\n- Single channel: `language_code`, `language_probability`, `text`, `words`, `audio_duration_secs`\n- Multi-channel (`use_multi_channel=true` with `multichannel_output_style=separate`): one entry per channel under `transcripts`\n- Diarization (`diarize=true`): `words[].speaker_id` identifies the speaker\n",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "$ref": "#/components/schemas/ScribeV2Request"
              },
              "encoding": {
                "file": {
                  "contentType": "application/octet-stream"
                }
              },
              "examples": {
                "minimal": {
                  "summary": "Minimal transcription",
                  "value": {
                    "model": "scribe-v2",
                    "file": "@audio.mp3"
                  }
                },
                "diarize": {
                  "summary": "Speaker diarization",
                  "value": {
                    "model": "scribe-v2",
                    "file": "@meeting.mp3",
                    "diarize": true,
                    "num_speakers": 2
                  }
                },
                "keyterms": {
                  "summary": "Keyterms with an explicit language",
                  "value": {
                    "model": "scribe-v2",
                    "file": "@audio.mp3",
                    "language": "en",
                    "keyterms[]": [
                      "ElevenLabs",
                      "Scribe"
                    ]
                  }
                },
                "multichannel": {
                  "summary": "Multi-channel transcription",
                  "value": {
                    "model": "scribe-v2",
                    "file": "@multi_channel.wav",
                    "use_multi_channel": true,
                    "multichannel_output_style": "separate"
                  }
                },
                "sourceUrl": {
                  "summary": "Transcribe a remote URL",
                  "value": {
                    "model": "scribe-v2",
                    "source_url": "https://example.com/audio.mp3"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Transcription succeeded. The response is the official ElevenLabs JSON\nstructure. Single-channel requests return one transcript object;\nmulti-channel requests with `multichannel_output_style=separate`\nreturn a `transcripts` array.\n",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/ScribeV2Transcription"
                    },
                    {
                      "$ref": "#/components/schemas/ScribeV2MultichannelTranscription"
                    }
                  ]
                },
                "examples": {
                  "single": {
                    "summary": "Single-channel transcript",
                    "value": {
                      "language_code": "eng",
                      "language_probability": 0.98,
                      "text": "Hello, this is a test recording.",
                      "words": [
                        {
                          "text": "Hello",
                          "start": 0,
                          "end": 0.42,
                          "type": "word",
                          "speaker_id": null,
                          "logprob": -0.124,
                          "channel_index": null
                        }
                      ],
                      "transcription_id": "7f3c1d2e-4b5a-4c6d-8e9f-0123456789ab",
                      "audio_duration_secs": 5.06
                    }
                  },
                  "diarized": {
                    "summary": "Diarized transcript",
                    "value": {
                      "language_code": "eng",
                      "language_probability": 0.99,
                      "text": "Hello, I am Ming. Hi, I am Hong.",
                      "words": [
                        {
                          "text": "Hello",
                          "start": 0,
                          "end": 0.35,
                          "type": "word",
                          "speaker_id": "speaker_0",
                          "logprob": -0.08
                        },
                        {
                          "text": "Hong",
                          "start": 2.8,
                          "end": 3.2,
                          "type": "word",
                          "speaker_id": "speaker_1",
                          "logprob": -0.09
                        }
                      ],
                      "transcription_id": "8a4d2e3f-5c6b-4d7e-9f80-123456789abc",
                      "audio_duration_secs": 5.2
                    }
                  },
                  "multichannel": {
                    "summary": "Multi-channel transcripts",
                    "value": {
                      "transcripts": [
                        {
                          "language_code": "eng",
                          "language_probability": 0.98,
                          "text": "Hello from channel one.",
                          "channel_index": 0,
                          "words": [
                            {
                              "text": "Hello",
                              "start": 0,
                              "end": 0.5,
                              "type": "word",
                              "speaker_id": "speaker_0",
                              "logprob": -0.124,
                              "channel_index": 0
                            }
                          ]
                        },
                        {
                          "language_code": "eng",
                          "language_probability": 0.97,
                          "text": "Greetings from channel two.",
                          "channel_index": 1,
                          "words": [
                            {
                              "text": "Greetings",
                              "start": 0.1,
                              "end": 0.7,
                              "type": "word",
                              "speaker_id": "speaker_1",
                              "logprob": -0.156,
                              "channel_index": 1
                            }
                          ]
                        }
                      ],
                      "transcription_id": "9b5e3f4a-6d7c-4e8f-8a91-23456789abcd",
                      "audio_duration_secs": 5.06
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid parameters, e.g. neither `file` nor `source_url` was provided, or `stream`/`webhook` was requested.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ScribeV2ErrorResponse"
                },
                "examples": {
                  "error": {
                    "$ref": "#/components/examples/ScribeV2Error"
                  }
                }
              }
            }
          },
          "401": {
            "description": "Authentication failed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ScribeV2ErrorResponse"
                }
              }
            }
          },
          "default": {
            "description": "Other errors. Upstream ElevenLabs error details are passed through.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ScribeV2ErrorResponse"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "API key",
        "description": "Pass the ModelVerse API key in the `Authorization` header (`Bearer <api_key>`)."
      }
    },
    "schemas": {
      "ScribeV2Request": {
        "type": "object",
        "required": [
          "model"
        ],
        "description": "At least one of `file` or `source_url` must be provided. All other fields\nmirror the ElevenLabs `POST /v1/speech-to-text` parameters.\n",
        "properties": {
          "model": {
            "type": "string",
            "const": "scribe-v2",
            "description": "Model name. Must be `scribe-v2`."
          },
          "file": {
            "type": "string",
            "format": "binary",
            "description": "Audio or video file to transcribe. Supports common audio and video\nformats. Minimum audio length is 100 ms; maximum file size is 5 GB.\nProvide either `file` or `source_url`.\n"
          },
          "source_url": {
            "type": "string",
            "format": "uri",
            "description": "Public URL of an audio or video file. Hosted media, YouTube, TikTok,\nand other video links are supported. Provide either `file` or `source_url`.\n"
          },
          "language": {
            "type": "string",
            "description": "Language of the audio as ISO-639-1 or ISO-639-3 (e.g. `en`, `zh`,\n`eng`). Specifying it can improve accuracy; when omitted the language\nis detected automatically.\n"
          },
          "language_code": {
            "type": "string",
            "description": "ElevenLabs native field with the same meaning as `language`. If both\nare provided, `language_code` wins.\n"
          },
          "timestamps_granularity": {
            "type": "string",
            "enum": [
              "none",
              "word",
              "character"
            ],
            "default": "word",
            "description": "Timestamp granularity. `word` returns word-level timestamps,\n`character` returns character-level timestamps, and `none` omits\ntimestamps. OpenAI-style `timestamp_granularities[]` is also accepted;\n`segment` is downgraded to `word`.\n"
          },
          "tag_audio_events": {
            "type": "boolean",
            "default": true,
            "description": "Whether to tag audio events such as `(laughter)` and `(footsteps)` in the transcript."
          },
          "diarize": {
            "type": "boolean",
            "default": false,
            "description": "Whether to annotate the active speaker. When enabled, `words[].speaker_id` identifies the speaker."
          },
          "num_speakers": {
            "type": "integer",
            "minimum": 1,
            "maximum": 32,
            "description": "Maximum number of speakers in the audio (up to 32). When omitted, the model uses the maximum it supports."
          },
          "diarization_threshold": {
            "type": "number",
            "description": "Diarization threshold. A higher value makes it less likely for one\nspeaker to be split into several; a lower value makes it more likely.\nOnly valid when `diarize=true` and `num_speakers` is not set.\n"
          },
          "temperature": {
            "type": "number",
            "minimum": 0,
            "maximum": 2,
            "description": "Sampling temperature between 0.0 and 2.0. Higher values produce more diverse output."
          },
          "seed": {
            "type": "integer",
            "minimum": 0,
            "maximum": 2147483647,
            "description": "Best-effort deterministic sampling seed. Determinism is not guaranteed."
          },
          "no_verbatim": {
            "type": "boolean",
            "default": false,
            "description": "Whether to remove filler words, false starts, and non-speech sounds."
          },
          "use_multi_channel": {
            "type": "boolean",
            "default": false,
            "description": "Whether to transcribe each channel of a multi-channel file\nindependently. Up to 5 channels are supported, and each channel\nshould contain a single speaker. Each channel is billed at the full\naudio duration.\n"
          },
          "multichannel_output_style": {
            "type": "string",
            "enum": [
              "separate",
              "combined"
            ],
            "default": "separate",
            "description": "`separate` returns one transcript per channel under `transcripts`;\n`combined` merges all channels into one transcript whose words are\nsorted by start time and carry `channel_index`. `combined` requires\ntimestamps (granularity other than `none`) and does not support\nentity detection or redaction.\n"
          },
          "detect_speaker_roles": {
            "type": "boolean",
            "default": false,
            "description": "Whether to detect speaker roles (agent or customer). Requires\n`diarize=true` and cannot be combined with `use_multi_channel=true`.\nWhen enabled, `speaker_id` values become role names.\n"
          },
          "use_speaker_library": {
            "type": "boolean",
            "default": false,
            "description": "Whether to match detected speakers against the workspace speaker library. Only effective with `diarize=true`."
          },
          "file_format": {
            "type": "string",
            "enum": [
              "pcm_s16le_16",
              "other"
            ],
            "default": "other",
            "description": "Input audio format. `pcm_s16le_16` means 16-bit PCM, 16 kHz, mono,\nlittle-endian, which gives lower latency; use `other` otherwise.\n"
          },
          "keyterms[]": {
            "type": "array",
            "maxItems": 1000,
            "items": {
              "type": "string",
              "maxLength": 50
            },
            "description": "Keyterms to bias the transcription. Up to 1000 terms; each term may\ncontain at most 50 characters and 5 words. The characters `<`, `>`,\n`{`, `}`, `[`, `]`, and `\\` are not supported. Repeat the field to\npass multiple values; `keyterms` is also accepted. Adds a 20%\nsurcharge to the base transcription cost.\n"
          },
          "entity_detection": {
            "type": "string",
            "description": "Entity detection. Pass `all`, a category (`pii`, `phi`, `pci`,\n`other`, `offensive_language`), or a specific entity type. Repeat the\nfield to pass multiple values. Results are returned in `entities`.\n"
          },
          "entity_redaction": {
            "type": "string",
            "description": "Redact entities from the transcript. Same format as `entity_detection`\nand must be a subset of it. When enabled, `entities` is not returned.\n"
          },
          "entity_redaction_mode": {
            "type": "string",
            "enum": [
              "redacted",
              "entity_type",
              "enumerated_entity_type"
            ],
            "default": "enumerated_entity_type",
            "description": "Redaction placeholder format: `{REDACTED}`, `{ENTITY_TYPE}`, or\n`{ENTITY_TYPE_N}`. Only used when `entity_redaction` is set.\n"
          },
          "transcript_edit": {
            "type": "string",
            "maxLength": 2000,
            "description": "Natural-language instruction applied to the final transcript (up to\n2000 characters). The result is returned in `edited_transcript`.\nCannot be combined with `entity_detection`, `entity_redaction`, or\n`use_multi_channel`. Adds a 30% surcharge and is billed for at least\n10 seconds of audio.\n"
          },
          "enable_logging": {
            "type": "string",
            "enum": [
              "true",
              "false"
            ],
            "description": "Whether upstream may log the request. Set to `false` for zero-retention mode."
          }
        }
      },
      "ScribeV2Transcription": {
        "type": "object",
        "description": "Single-channel transcript (official ElevenLabs structure).",
        "required": [
          "language_code",
          "text",
          "words"
        ],
        "properties": {
          "language_code": {
            "type": "string",
            "description": "Detected language code, e.g. `eng` or `cmn`."
          },
          "language_probability": {
            "type": "number",
            "minimum": 0,
            "maximum": 1,
            "description": "Confidence of the language detection, between 0 and 1."
          },
          "text": {
            "type": "string",
            "description": "Full transcript text."
          },
          "words": {
            "type": "array",
            "description": "Words and audio events with timestamps and speaker information.",
            "items": {
              "$ref": "#/components/schemas/ScribeV2Word"
            }
          },
          "channel_index": {
            "type": [
              "integer",
              "null"
            ],
            "description": "Channel index for combined multi-channel output; `null` for single-channel audio."
          },
          "entities": {
            "type": "array",
            "description": "Detected entities, returned only when `entity_detection` is used.",
            "items": {
              "$ref": "#/components/schemas/ScribeV2Entity"
            }
          },
          "edited_transcript": {
            "$ref": "#/components/schemas/ScribeV2EditedTranscript"
          },
          "transcription_id": {
            "type": "string",
            "description": "Transcription task ID."
          },
          "audio_duration_secs": {
            "type": "number",
            "description": "Audio duration in seconds, also the billing basis."
          }
        }
      },
      "ScribeV2MultichannelTranscription": {
        "type": "object",
        "description": "Multi-channel transcript with one entry per channel.",
        "required": [
          "transcripts"
        ],
        "properties": {
          "transcripts": {
            "type": "array",
            "description": "One transcript per audio channel.",
            "items": {
              "$ref": "#/components/schemas/ScribeV2Transcription"
            }
          },
          "transcription_id": {
            "type": "string",
            "description": "Transcription task ID."
          },
          "audio_duration_secs": {
            "type": "number",
            "description": "Audio duration in seconds shared by all channels."
          }
        }
      },
      "ScribeV2Word": {
        "type": "object",
        "required": [
          "text",
          "start",
          "end",
          "type"
        ],
        "properties": {
          "text": {
            "type": "string",
            "description": "The word or sound that was transcribed."
          },
          "start": {
            "type": "number",
            "description": "Start time in seconds."
          },
          "end": {
            "type": "number",
            "description": "End time in seconds."
          },
          "type": {
            "type": "string",
            "description": "Type. `word` for normal words, `audio_event` for non-word sounds such as laughter, `spacing` for gaps."
          },
          "speaker_id": {
            "type": [
              "string",
              "null"
            ],
            "description": "Speaker identifier such as `speaker_0`; `null` when `diarize` is disabled."
          },
          "logprob": {
            "type": "number",
            "description": "Log probability of the prediction in [-infinity, 0]; higher means more confident."
          },
          "channel_index": {
            "type": [
              "integer",
              "null"
            ],
            "description": "Channel this word belongs to in multi-channel output; `null` for single-channel audio."
          },
          "characters": {
            "type": "array",
            "description": "Character-level timestamps, returned only when `timestamps_granularity=character`.",
            "items": {
              "$ref": "#/components/schemas/ScribeV2Character"
            }
          }
        }
      },
      "ScribeV2Character": {
        "type": "object",
        "required": [
          "text",
          "start",
          "end"
        ],
        "properties": {
          "text": {
            "type": "string",
            "description": "Character content."
          },
          "start": {
            "type": "number",
            "description": "Character start time in seconds."
          },
          "end": {
            "type": "number",
            "description": "Character end time in seconds."
          }
        }
      },
      "ScribeV2Entity": {
        "type": "object",
        "required": [
          "text",
          "entity_type",
          "start_char",
          "end_char"
        ],
        "properties": {
          "text": {
            "type": "string",
            "description": "The text identified as an entity."
          },
          "entity_type": {
            "type": "string",
            "description": "Entity type, e.g. `credit_card`, `email_address`, `person_name`."
          },
          "start_char": {
            "type": "integer",
            "description": "Start character position in the transcript."
          },
          "end_char": {
            "type": "integer",
            "description": "End character position in the transcript."
          }
        }
      },
      "ScribeV2EditedTranscript": {
        "type": "object",
        "description": "Transcript edit result, returned only when `transcript_edit` is used.",
        "required": [
          "kind",
          "text",
          "edited_text"
        ],
        "properties": {
          "kind": {
            "type": "string",
            "const": "transcript",
            "description": "Result kind, always `transcript`."
          },
          "text": {
            "type": "string",
            "description": "Edited transcript text."
          },
          "edited_text": {
            "type": "string",
            "description": "Edited transcript text, identical to `text`."
          }
        }
      },
      "ScribeV2ErrorResponse": {
        "type": "object",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "$ref": "#/components/schemas/ScribeV2Error"
          }
        }
      },
      "ScribeV2Error": {
        "type": "object",
        "required": [
          "message",
          "type",
          "code"
        ],
        "properties": {
          "message": {
            "type": "string",
            "description": "Error message."
          },
          "type": {
            "type": "string",
            "description": "Error type.",
            "examples": [
              "invalid_request_error"
            ]
          },
          "code": {
            "type": "string",
            "description": "Machine-readable error code.",
            "examples": [
              "invalid_value"
            ]
          },
          "param": {
            "type": [
              "string",
              "null"
            ],
            "description": "Name of the offending parameter."
          },
          "trace_id": {
            "type": "string",
            "description": "Request trace ID for feedback and troubleshooting."
          }
        }
      }
    },
    "examples": {
      "ScribeV2Error": {
        "summary": "Standard JSON error response",
        "value": {
          "error": {
            "message": "file or source_url is required",
            "type": "invalid_request_error",
            "code": "param_error",
            "param": null,
            "trace_id": "dac91750-390c-4e5b-9c29-dc2f71183929"
          }
        }
      }
    }
  }
}
```