Skip to content

MOSS 本地音频转文字 API 使用文档 ​

通过 DMXAPI 的 MOSS 同步转写接口,以文件上传方式提交本地音频或视频,并直接获得识别结果。本示例使用 moss-transcribe-1.0 进行普通转写,适合本机录音文件的字幕、访谈记录和文本整理。

接口地址 ​

接口请求方式URL
本地音频转文字POSThttps://www.dmxapi.cn/moss-speech/v1/audio/transcriptions

WARNING

请妥善保管您的 API Key!下方示例直接在代码的 api_key 变量中填写密钥,请将占位值替换为您自己的 API Key,不要公开分享包含真实密钥的代码。

模型名称 ​

  • moss-transcribe-1.0:普通语音转文字。
  • moss-transcribe-diarize-pro:多说话人转写、热词和 SSE 流式输出使用。

本地音频转文字示例代码 ​

python
import json
import mimetypes
from pathlib import Path

import requests

# ===============================================================
# 步骤1:配置 API 连接信息
# ===============================================================

# DMXAPI 网关的 MOSS 同步音频转写接口地址
# 使用 DMXAPI 网关地址,正式站域名为 www.dmxapi.cn
url = "https://www.dmxapi.cn/moss-speech/v1/audio/transcriptions"

# DMXAPI API Key:直接将下方占位值替换为您自己的密钥
api_key = "YOUR_DMXAPI_API_KEY"

# 本地音频或视频文件路径,单文件最大 512 MB
input_path = Path("input/audio.wav")

# 转写结果保存路径;JSON 结果保存为格式化 JSON,text 结果保存为纯文本
output_path = Path("outputs/moss_transcription_file_result.json")

# 请求超时时间,单位:秒
request_timeout = 1000

# ===============================================================
# 步骤2:配置请求头
# ===============================================================

headers = {
    # multipart/form-data 的 Content-Type 由 requests 自动生成,不能手动固定 boundary
    "Authorization": f"Bearer {api_key}",  # DMXAPI 网关鉴权
    "Accept": "application/json",  # response_format=text 时也可以改成 text/plain
}

# ===============================================================
# 步骤3:配置请求参数
# ===============================================================

form_data = {
    # 【model】(string, 必填) 普通转写使用 moss-transcribe-1.0
    # 启用 diarize 或填写非空 keyterms 时,必须改为 moss-transcribe-diarize-pro
    "model": "moss-transcribe-1.0",

    # 【response_format】(string, 可选) json、text 、diarized_json或verbose_json
    # json;启用 diarize 时包含说话人分段
    # text/plain:  纯文本,仅适用于非流式。
    # diarized_json 会返回说话人分段,并要求使用专业模型
    # verbose_json: 仅适用于流式请求,返回包含增量文本、说话人分段、时间戳和用量信息的 SSE 事件。当前事件结构与其他流式格式一致。
    "response_format": "json",

    # 【diarize】(string, 可选) multipart 中使用 true/false 字符串
    # 设为 true 时必须使用 moss-transcribe-diarize-pro
    "diarize": "false",

    # 【keyterms】(string, 可选) multipart 中必须传 JSON 字符串数组
    # 例如 json.dumps(["MOSS", "SGLang"], ensure_ascii=False)
    # 空数组表示不启用热词;非空数组必须使用 moss-transcribe-diarize-pro
    "keyterms": json.dumps([], ensure_ascii=False),
}


# ===============================================================
# 步骤4:发送请求、处理响应并保存结果
# ===============================================================

def read_result(response, response_format):
    """成功的 text 响应按原文保留;其他响应优先解析 JSON。"""
    if response.ok and response_format == "text":
        return response.text
    try:
        return response.json()
    except ValueError:
        return response.text


def print_result(result):
    """格式化输出 JSON 或纯文本转写结果。"""
    if isinstance(result, (dict, list)):
        print(json.dumps(result, indent=2, ensure_ascii=False))
    else:
        print(result)


def save_result(result, output_path):
    """保存转写结果,不把错误响应当作成功结果保存。"""
    output_path.parent.mkdir(parents=True, exist_ok=True)
    if isinstance(result, (dict, list)):
        output_path.write_text(json.dumps(result, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
    else:
        output_path.write_text(str(result), encoding="utf-8")
    print("output_path:", output_path.resolve())


def main():
    if not api_key.strip() or api_key == "YOUR_DMXAPI_API_KEY":
        raise RuntimeError("请先在代码顶部的 api_key 中填写您的 DMXAPI API Key。")
    if not input_path.is_file():
        raise RuntimeError(f"找不到输入文件:{input_path.resolve()}")
    if input_path.stat().st_size > 512 * 1024 * 1024:
        raise RuntimeError("输入文件超过 MOSS 单文件 512 MB 限制。")

    mime_type = mimetypes.guess_type(input_path.name)[0] or "application/octet-stream"
    with input_path.open("rb") as input_file:
        response = requests.post(
            url,
            headers=headers,
            data=form_data,
            files={"file": (input_path.name, input_file, mime_type)},
            timeout=request_timeout,
        )

    header_request_id = response.headers.get("x-request-id", "")
    print("status_code:", response.status_code)
    if header_request_id:
        print("header_request_id:", header_request_id)

    content_type = response.headers.get("Content-Type", "")
    if "text/html" in content_type.lower():
        raise RuntimeError(
            f"网关返回了 HTML 页面而不是接口结果(HTTP {response.status_code}),"
            "请检查 url 是否为本文列出的完整接口地址。"
        )

    result = read_result(response, form_data.get("response_format", "json"))
    print_result(result)

    if not response.ok:
        request_id_detail = f",request_id={header_request_id}" if header_request_id else ""
        raise RuntimeError(
            f"MOSS 文件转写请求失败:HTTP {response.status_code}{request_id_detail}"
        )

    request_id = header_request_id
    if request_id:
        print("request_id:", request_id)
    save_result(result, output_path)


if __name__ == "__main__":
    main()

返回示例 ​

json
{
  "text": "你好,这是音色生成测试一二三四五六七。",
  "usage": {
    "completion_tokens": 13,
    "input_audio_seconds": 4.56,
    "prompt_tokens": 57,
    "seconds": 5,
    "total_tokens": 70,
    "type": "duration"
  }
}

© 2026 DMXAPI MOSS 本地音频转文字

一个 Key 用全球大模型