Skip to content

MOSS 音频 URL 转文字 API 使用文档 ​

通过 DMXAPI 的 MOSS 同步转写接口,将服务端可访问的公网音频或视频链接转换为文字。适合已有云端音频地址的会议、访谈等场景。本示例使用 moss-transcribe-diarize-pro 并启用说话人分离;请求完成后直接返回结果,无需查询任务状态。

接口地址 ​

接口请求方式URL
音频 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 流式输出使用。

启用上述任一专业能力时,都必须选择 moss-transcribe-diarize-pro。

音频 URL 转文字示例代码 ​

python
import json
from pathlib import Path
from urllib.parse import urlparse

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"

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

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

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

headers = {
    "Content-Type": "application/json",  # JSON 请求体
    "Authorization": f"Bearer {api_key}",  # DMXAPI 网关鉴权
    "Accept": "application/json",  # response_format=text 时也可以改成 text/plain
}

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

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

    # 【url】(string, 四选一) 服务端可访问的公网音频或视频 URL
    # 不能使用 localhost、回环地址或私网地址
    "url": "https://arkdocs.tos-cn-beijing.volces.com/files/advanced-usage/audio_demo_video_multispeaker_02.m4a",

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

    # 【diarize】(boolean, 可选) 是否启用说话人分离
    # 设为 True 时必须使用 moss-transcribe-diarize-pro
    "diarize": True,

    # 【keyterms】(string[], 可选) 热词列表,最多 20 个,每个最多 30 个字符
    # 空数组表示不启用热词;非空数组必须使用 moss-transcribe-diarize-pro
    "keyterms": [],
}


# ===============================================================
# 步骤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 validate_public_url(value):
    """检查配置的输入地址是否为 HTTP(S) URL。"""
    parsed = urlparse(value)
    if parsed.scheme not in {"http", "https"} or not parsed.netloc:
        raise RuntimeError(f"payload['url'] 不是有效的 HTTP(S) 地址:{value!r}")


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。")
    validate_public_url(payload["url"])

    response = requests.post(
        url,
        headers=headers,
        json=payload,
        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, payload.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 URL 转写请求失败: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
{
  "duration": 6.5698125,
  "segments": [
    {
      "end": 1.55,
      "id": "seg_001",
      "speaker": "S01",
      "start": 0.63,
      "text": "太厉害了 真能上班",
      "type": "transcript.text.segment"
    },
    {
      "end": 3.28,
      "id": "seg_002",
      "speaker": "S02",
      "start": 1.51,
      "text": "没错 我觉得这个排版真的是让我",
      "type": "transcript.text.segment"
    },
    {
      "end": 4.56,
      "id": "seg_003",
      "speaker": "S01",
      "start": 3.29,
      "text": "这不很多朋友就",
      "type": "transcript.text.segment"
    },
    {
      "end": 5.59,
      "id": "seg_004",
      "speaker": "S02",
      "start": 4.57,
      "text": "神清气爽",
      "type": "transcript.text.segment"
    },
    {
      "end": 5.97,
      "id": "seg_005",
      "speaker": "S01",
      "start": 5.56,
      "text": "解放了",
      "type": "transcript.text.segment"
    }
  ],
  "task": "transcribe",
  "text": "太厉害了 真能上班没错 我觉得这个排版真的是让我这不很多朋友就神清气爽解放了",
  "usage": {
    "completion_tokens": 103,
    "input_audio_seconds": 6.5698125,
    "prompt_tokens": 170,
    "total_tokens": 273,
    "type": "duration"
  }
}

© 2026 DMXAPI MOSS 音频 URL 转文字

一个 Key 用全球大模型