# Scribe V3 音频转写

> 音频生成

上传音频文件或传入音频 URL，返回转写文本、语言识别结果与词级时间戳。

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

**音频来源**：`file` 与 `source_url` 至少提供一个。

**响应结构**：
- 单声道：`language_code`、`language_probability`、`text`、`words`、`audio_duration_secs`
- 多声道（`use_multi_channel=true` 且 `multichannel_output_style=separate`）：`transcripts` 数组，每个声道一条
- 说话人分离（`diarize=true`）：`words[].speaker_id` 标识说话人

## 请求地址

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

## 请求体

## 响应

- **200** — 转写成功。响应直接透传 ElevenLabs 官方 JSON：单声道返回单条转写对象，
多声道（`multichannel_output_style=separate`）返回 `transcripts` 数组。

- **400** — 请求参数错误，例如 `file` 与 `source_url` 都未提供、使用了 `stream`/`webhook`。
- **401** — 认证失败。
- **default** — 其他错误，上游 ElevenLabs 的错误信息会被透传。

## OpenAPI 定义

```json
{
  "openapi": "3.1.0",
  "x-language": "zh-CN",
  "info": {
    "title": "Scribe V3 语音转写接口文档",
    "version": "1.0.0",
    "description": "这是 ModelVerse 上 `scribe-v3` 的音频转写接口文档。`scribe-v3` 基于 ElevenLabs\nScribe v3，是 Scribe v2 的升级版本，在 FLEURS 上的词错误率比 v2 低约 27%。\n接口路径为 `POST /v1/audio/transcriptions`，兼容 OpenAI 的音频转写调用方式，\n响应直接透传 ElevenLabs 官方结果结构。按输入音频时长（秒）计费，不足 1 秒向上取整。\n\n**相比 scribe-v2 新增**：`numbers_format`（数字格式）、`secondary_language_codes`\n（混语种音频的辅助语言），并对整体识别准确率、说话人分离、关键词提示、实体检测与\n转写编辑做了增强。\n\n**支持能力**：90+ 种语言、词级/字符级时间戳、说话人分离（最多 32 人）、\n关键词提示（最多 1000 个）、多声道独立转写、去除口头禅、实体检测与脱敏、\n自然语言指令编辑转写。\n\n**限制**：不支持流式（`stream`）、不支持 Webhook 异步回调（`webhook`）、不支持 `srt`/`vtt`。\n接口固定返回 ElevenLabs 官方 JSON 结构。\n"
  },
  "servers": [
    {
      "url": "https://api.modelverse.cn",
      "description": "ModelVerse API endpoint"
    }
  ],
  "tags": [
    {
      "name": "Scribe-V3",
      "description": "ElevenLabs Scribe v3 录音转写，按音频时长（秒）计费。"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "paths": {
    "/v1/audio/transcriptions": {
      "post": {
        "tags": [
          "Scribe-V3"
        ],
        "operationId": "createScribeV3Transcription",
        "summary": "Scribe V3 音频转写",
        "description": "上传音频文件或传入音频 URL，返回转写文本、语言识别结果与词级时间戳。\n\n**Content-Type**：`multipart/form-data`\n\n**音频来源**：`file` 与 `source_url` 至少提供一个。\n\n**响应结构**：\n- 单声道：`language_code`、`language_probability`、`text`、`words`、`audio_duration_secs`\n- 多声道（`use_multi_channel=true` 且 `multichannel_output_style=separate`）：`transcripts` 数组，每个声道一条\n- 说话人分离（`diarize=true`）：`words[].speaker_id` 标识说话人\n",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "$ref": "#/components/schemas/ScribeV3Request"
              },
              "encoding": {
                "file": {
                  "contentType": "application/octet-stream"
                }
              },
              "examples": {
                "minimal": {
                  "summary": "最简转写",
                  "value": {
                    "model": "scribe-v3",
                    "file": "@audio.mp3"
                  }
                },
                "diarize": {
                  "summary": "说话人分离",
                  "value": {
                    "model": "scribe-v3",
                    "file": "@meeting.mp3",
                    "diarize": true,
                    "num_speakers": 2
                  }
                },
                "multilingual": {
                  "summary": "混合语言音频 + 数字格式",
                  "value": {
                    "model": "scribe-v3",
                    "file": "@audio.mp3",
                    "language": "en",
                    "secondary_language_codes[]": [
                      "zh",
                      "es"
                    ],
                    "numbers_format": "digits"
                  }
                },
                "keyterms": {
                  "summary": "关键词提示",
                  "value": {
                    "model": "scribe-v3",
                    "file": "@audio.mp3",
                    "keyterms[]": [
                      "ElevenLabs",
                      "Scribe"
                    ]
                  }
                },
                "multichannel": {
                  "summary": "多声道独立转写",
                  "value": {
                    "model": "scribe-v3",
                    "file": "@multi_channel.wav",
                    "use_multi_channel": true,
                    "multichannel_output_style": "separate"
                  }
                },
                "sourceUrl": {
                  "summary": "使用音频 URL",
                  "value": {
                    "model": "scribe-v3",
                    "source_url": "https://example.com/audio.mp3"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "转写成功。响应直接透传 ElevenLabs 官方 JSON：单声道返回单条转写对象，\n多声道（`multichannel_output_style=separate`）返回 `transcripts` 数组。\n",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/ScribeV3Transcription"
                    },
                    {
                      "$ref": "#/components/schemas/ScribeV3MultichannelTranscription"
                    }
                  ]
                },
                "examples": {
                  "single": {
                    "summary": "单声道转写",
                    "value": {
                      "language_code": "eng",
                      "language_probability": 0.98,
                      "text": "The order number is 42.",
                      "words": [
                        {
                          "text": "The",
                          "start": 0,
                          "end": 0.12,
                          "type": "word",
                          "speaker_id": null,
                          "logprob": -0.05,
                          "channel_index": null
                        },
                        {
                          "text": "42",
                          "start": 1.02,
                          "end": 1.28,
                          "type": "word",
                          "speaker_id": null,
                          "logprob": -0.09,
                          "channel_index": null
                        }
                      ],
                      "transcription_id": "3c9f7a1b-2d4e-4f6a-8b7c-0123456789ab",
                      "audio_duration_secs": 5.06
                    }
                  },
                  "diarized": {
                    "summary": "说话人分离",
                    "value": {
                      "language_code": "cmn",
                      "language_probability": 0.99,
                      "text": "你好，我是小明。你好，我是小红。",
                      "words": [
                        {
                          "text": "你好",
                          "start": 0,
                          "end": 0.35,
                          "type": "word",
                          "speaker_id": "speaker_0",
                          "logprob": -0.08
                        },
                        {
                          "text": "小红",
                          "start": 2.8,
                          "end": 3.2,
                          "type": "word",
                          "speaker_id": "speaker_1",
                          "logprob": -0.09
                        }
                      ],
                      "transcription_id": "4d8a2b3c-5e6f-4a7b-9c8d-123456789abc",
                      "audio_duration_secs": 5.2
                    }
                  },
                  "multichannel": {
                    "summary": "多声道独立转写",
                    "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": "5e9b3c4d-6f7a-4b8c-8d9e-23456789abcd",
                      "audio_duration_secs": 5.06
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "请求参数错误，例如 `file` 与 `source_url` 都未提供、使用了 `stream`/`webhook`。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ScribeV3ErrorResponse"
                },
                "examples": {
                  "error": {
                    "$ref": "#/components/examples/ScribeV3Error"
                  }
                }
              }
            }
          },
          "401": {
            "description": "认证失败。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ScribeV3ErrorResponse"
                }
              }
            }
          },
          "default": {
            "description": "其他错误，上游 ElevenLabs 的错误信息会被透传。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ScribeV3ErrorResponse"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "API key",
        "description": "在 `Authorization` 头中传入 ModelVerse API Key（`Bearer <api_key>`）。"
      }
    },
    "schemas": {
      "ScribeV3Request": {
        "type": "object",
        "required": [
          "model"
        ],
        "description": "`file` 与 `source_url` 至少提供一个。其余字段与 ElevenLabs `POST /v1/speech-to-text`\n的参数保持一致，可直接使用原生能力。\n",
        "properties": {
          "model": {
            "type": "string",
            "const": "scribe-v3",
            "description": "模型名称，固定为 `scribe-v3`。"
          },
          "file": {
            "type": "string",
            "format": "binary",
            "description": "待转写的音频或视频文件，支持主流音视频格式。音频最短 100ms，文件大小需小于 5GB。\n与 `source_url` 至少提供一个。\n"
          },
          "source_url": {
            "type": "string",
            "format": "uri",
            "description": "音频或视频的公网 URL，支持托管音视频文件、YouTube、TikTok 等视频链接。\n与 `file` 至少提供一个。\n"
          },
          "language": {
            "type": "string",
            "description": "音频语言，ISO-639-1 或 ISO-639-3，如 `zh`、`en`、`eng`。\n提前指定可提升识别准确率；不传则由模型自动检测。\n"
          },
          "language_code": {
            "type": "string",
            "description": "ElevenLabs 原生字段，含义与 `language` 相同。两者同时传入时以 `language_code` 为准。\n"
          },
          "secondary_language_codes[]": {
            "type": "array",
            "maxItems": 10,
            "items": {
              "type": "string"
            },
            "description": "除 `language` 外可能出现的其他语言，ISO-639-1 或 ISO-639-3。\n用于提升混合语言音频的识别准确率，仅 `scribe-v3` 支持。\n同名键重复出现即可传多个，也兼容 `secondary_language_codes` 写法。\n"
          },
          "timestamps_granularity": {
            "type": "string",
            "enum": [
              "none",
              "word",
              "character"
            ],
            "default": "word",
            "description": "时间戳粒度。`word` 返回词级时间戳，`character` 返回字符级时间戳，`none` 不返回时间戳。\n同时兼容 OpenAI 的 `timestamp_granularities[]`：`segment` 会降级为 `word`。\n"
          },
          "numbers_format": {
            "type": "string",
            "enum": [
              "digits",
              "words"
            ],
            "description": "数字格式。`digits` 输出阿拉伯数字（如 `42`），`words` 输出文字（如 `forty-two`）。\n仅 `scribe-v3` 支持。\n"
          },
          "tag_audio_events": {
            "type": "boolean",
            "default": true,
            "description": "是否在转写文本中标注音频事件，如 `(laughter)`、`(footsteps)`。"
          },
          "diarize": {
            "type": "boolean",
            "default": false,
            "description": "是否进行说话人分离，开启后 `words[].speaker_id` 标识说话人。"
          },
          "num_speakers": {
            "type": "integer",
            "minimum": 1,
            "maximum": 32,
            "description": "音频中说话人的最大数量，最多支持 32 人。不传时由模型按支持的最大值推断。\n"
          },
          "diarization_threshold": {
            "type": "number",
            "description": "说话人分离阈值。值越高，同一说话人越不容易被拆成多个；值越低，越容易拆分出更多说话人。\n仅在 `diarize=true` 且未指定 `num_speakers` 时可设置。\n"
          },
          "temperature": {
            "type": "number",
            "minimum": 0,
            "maximum": 2,
            "description": "采样温度，范围 0.0–2.0。值越高结果越多样，越低越确定。"
          },
          "seed": {
            "type": "integer",
            "minimum": 0,
            "maximum": 2147483647,
            "description": "随机种子，相同种子与参数下尽量返回一致结果，但不保证完全确定。"
          },
          "no_verbatim": {
            "type": "boolean",
            "default": false,
            "description": "是否移除口头禅、false start 与非语音声音。"
          },
          "use_multi_channel": {
            "type": "boolean",
            "default": false,
            "description": "是否为多声道音频开启独立转写，最多支持 5 个声道，每个声道应只包含一个说话人。\n开启后每个声道按完整音频时长独立计费。\n"
          },
          "multichannel_output_style": {
            "type": "string",
            "enum": [
              "separate",
              "combined"
            ],
            "default": "separate",
            "description": "`separate` 在 `transcripts` 下为每个声道返回一条转写；`combined` 合并为单条转写，\n词按开始时间排序并带 `channel_index`。`combined` 要求时间戳粒度不为 `none`，\n且不支持实体检测与脱敏。\n"
          },
          "detect_speaker_roles": {
            "type": "boolean",
            "default": false,
            "description": "是否识别说话人角色（agent / customer）。需要 `diarize=true`，且不能与\n`use_multi_channel=true` 同时使用。开启后 `speaker_id` 为角色名。\n"
          },
          "use_speaker_library": {
            "type": "boolean",
            "default": false,
            "description": "是否使用工作区的说话人库识别已知说话人，仅在 `diarize=true` 时生效。\n"
          },
          "file_format": {
            "type": "string",
            "enum": [
              "pcm_s16le_16",
              "other"
            ],
            "default": "other",
            "description": "输入音频格式。`pcm_s16le_16` 表示 16kHz、16bit、单声道、小端序 PCM，延迟更低；\n其他格式使用 `other`。\n"
          },
          "keyterms[]": {
            "type": "array",
            "maxItems": 1000,
            "items": {
              "type": "string",
              "maxLength": 50
            },
            "description": "关键词提示词列表，用于提升专有名词识别准确率。最多 1000 个，单个不超过 50 字符、\n不超过 5 个单词；不支持 `<`、`>`、`{`、`}`、`[`、`]`、`\\`。\n同名键重复出现即可传多个，也兼容 `keyterms` 写法。使用该参数会在基础转写费用上加收 20%。\n"
          },
          "entity_detection": {
            "type": "string",
            "description": "实体检测。可传 `all`、分类（`pii`、`phi`、`pci`、`other`、`offensive_language`）\n或具体实体类型；也可重复传多个值。结果返回在 `entities` 字段。\n"
          },
          "entity_redaction": {
            "type": "string",
            "description": "实体脱敏。格式与 `entity_detection` 相同，且必须是其子集。开启后不返回 `entities`。\n"
          },
          "entity_redaction_mode": {
            "type": "string",
            "enum": [
              "redacted",
              "entity_type",
              "enumerated_entity_type"
            ],
            "default": "enumerated_entity_type",
            "description": "脱敏占位格式：`{REDACTED}`、`{ENTITY_TYPE}` 或 `{ENTITY_TYPE_N}`。\n仅在设置 `entity_redaction` 时生效。\n"
          },
          "transcript_edit": {
            "type": "string",
            "maxLength": 2000,
            "description": "自然语言编辑指令，用于对最终转写结果做二次编辑（最多 2000 字符），结果返回在\n`edited_transcript`。不能与 `entity_detection`、`entity_redaction`、\n`use_multi_channel` 同时使用。使用该参数会在基础费用上加收 30%，且至少按 10 秒计费。\n"
          },
          "enable_logging": {
            "type": "string",
            "enum": [
              "true",
              "false"
            ],
            "description": "是否允许上游记录本次请求。传 `false` 时启用零留存模式。\n"
          }
        }
      },
      "ScribeV3Transcription": {
        "type": "object",
        "description": "单声道转写结果（ElevenLabs 官方结构）。",
        "required": [
          "language_code",
          "text",
          "words"
        ],
        "properties": {
          "language_code": {
            "type": "string",
            "description": "检测到的语言代码，如 `eng`、`cmn`。"
          },
          "language_probability": {
            "type": "number",
            "minimum": 0,
            "maximum": 1,
            "description": "语言识别置信度，范围 0–1。"
          },
          "text": {
            "type": "string",
            "description": "完整转写文本。"
          },
          "words": {
            "type": "array",
            "description": "词与音频事件列表，含时间戳与说话人信息。",
            "items": {
              "$ref": "#/components/schemas/ScribeV3Word"
            }
          },
          "channel_index": {
            "type": [
              "integer",
              "null"
            ],
            "description": "多声道合并输出时标识所属声道；单声道为 `null`。"
          },
          "entities": {
            "type": "array",
            "description": "检测到的实体列表，仅在使用 `entity_detection` 时返回。",
            "items": {
              "$ref": "#/components/schemas/ScribeV3Entity"
            }
          },
          "edited_transcript": {
            "$ref": "#/components/schemas/ScribeV3EditedTranscript"
          },
          "transcription_id": {
            "type": "string",
            "description": "本次转写任务 ID。"
          },
          "audio_duration_secs": {
            "type": "number",
            "description": "音频时长（秒），也是计费用量的来源。"
          }
        }
      },
      "ScribeV3MultichannelTranscription": {
        "type": "object",
        "description": "多声道转写结果，每个声道一条转写。",
        "required": [
          "transcripts"
        ],
        "properties": {
          "transcripts": {
            "type": "array",
            "description": "声道转写列表，每个声道一个元素。",
            "items": {
              "$ref": "#/components/schemas/ScribeV3Transcription"
            }
          },
          "transcription_id": {
            "type": "string",
            "description": "本次转写任务 ID。"
          },
          "audio_duration_secs": {
            "type": "number",
            "description": "所有声道共用的音频时长（秒）。"
          }
        }
      },
      "ScribeV3Word": {
        "type": "object",
        "required": [
          "text",
          "start",
          "end",
          "type"
        ],
        "properties": {
          "text": {
            "type": "string",
            "description": "词或声音内容。"
          },
          "start": {
            "type": "number",
            "description": "开始时间（秒）。"
          },
          "end": {
            "type": "number",
            "description": "结束时间（秒）。"
          },
          "type": {
            "type": "string",
            "description": "类型。`word` 为正常词，`audio_event` 为非词语音（如笑声），`spacing` 为间隔。"
          },
          "speaker_id": {
            "type": [
              "string",
              "null"
            ],
            "description": "说话人标识，如 `speaker_0`；未开启 `diarize` 时为 `null`。"
          },
          "logprob": {
            "type": "number",
            "description": "该词的预测对数概率，范围 [-infinity, 0]，越高置信度越高。"
          },
          "channel_index": {
            "type": [
              "integer",
              "null"
            ],
            "description": "多声道转写时该词所属声道；单声道为 `null`。"
          },
          "characters": {
            "type": "array",
            "description": "字符级时间戳，仅在 `timestamps_granularity=character` 时返回。",
            "items": {
              "$ref": "#/components/schemas/ScribeV3Character"
            }
          }
        }
      },
      "ScribeV3Character": {
        "type": "object",
        "required": [
          "text",
          "start",
          "end"
        ],
        "properties": {
          "text": {
            "type": "string",
            "description": "字符内容。"
          },
          "start": {
            "type": "number",
            "description": "字符开始时间（秒）。"
          },
          "end": {
            "type": "number",
            "description": "字符结束时间（秒）。"
          }
        }
      },
      "ScribeV3Entity": {
        "type": "object",
        "required": [
          "text",
          "entity_type",
          "start_char",
          "end_char"
        ],
        "properties": {
          "text": {
            "type": "string",
            "description": "识别为实体的文本。"
          },
          "entity_type": {
            "type": "string",
            "description": "实体类型，如 `credit_card`、`email_address`、`person_name`。"
          },
          "start_char": {
            "type": "integer",
            "description": "实体在转写文本中的起始字符位置。"
          },
          "end_char": {
            "type": "integer",
            "description": "实体在转写文本中的结束字符位置。"
          }
        }
      },
      "ScribeV3EditedTranscript": {
        "type": "object",
        "description": "转写编辑结果，仅在使用 `transcript_edit` 时返回。",
        "required": [
          "kind",
          "text",
          "edited_text"
        ],
        "properties": {
          "kind": {
            "type": "string",
            "const": "transcript",
            "description": "结果类型，固定为 `transcript`。"
          },
          "text": {
            "type": "string",
            "description": "编辑后的转写文本。"
          },
          "edited_text": {
            "type": "string",
            "description": "编辑后的转写文本，与 `text` 相同。"
          }
        }
      },
      "ScribeV3ErrorResponse": {
        "type": "object",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "$ref": "#/components/schemas/ScribeV3Error"
          }
        }
      },
      "ScribeV3Error": {
        "type": "object",
        "required": [
          "message",
          "type",
          "code"
        ],
        "properties": {
          "message": {
            "type": "string",
            "description": "错误说明。"
          },
          "type": {
            "type": "string",
            "description": "错误类型。",
            "examples": [
              "invalid_request_error"
            ]
          },
          "code": {
            "type": "string",
            "description": "机器可读的错误码。",
            "examples": [
              "invalid_value"
            ]
          },
          "param": {
            "type": [
              "string",
              "null"
            ],
            "description": "出错的参数名。"
          },
          "trace_id": {
            "type": "string",
            "description": "请求追踪 ID，用于反馈或排查问题。"
          }
        }
      }
    },
    "examples": {
      "ScribeV3Error": {
        "summary": "标准 JSON 错误响应",
        "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"
          }
        }
      }
    }
  }
}
```