MOSS 上传文件并使用 file_id 转文字 API 使用文档
通过 DMXAPI 的 MOSS 接口,先上传本地音频或视频取得 file_id,再使用该标识获取识别文字。本文提供两个可独立运行的示例:第一部分上传文件并输出文件标识;第二部分填写该标识并执行转写。已有可用 file_id 时,可以直接使用第二部分。
file_id 转写实测异常(2026-11-04)
本次实测中,两次文件上传均返回 HTTP 200,但响应中的 file_id 与 id 相同,都是 task_...。将返回的 file_id 原样传入转写接口,首次调用、稍后重试及重新上传后的调用均返回 HTTP 404:外层错误码为 task_not_found,内层错误码为 file_not_found。
当前测试环境的上传后转写链路尚未通过,需要服务端排查返回的文件标识及其解析。相同音频已通过本地音频转文字实测,也可使用音频 URL 转文字。下方保留调用代码及历史成功响应,便于接口修复后复测。
接口地址
| 步骤 | 请求方式 | URL | 请求体类型 |
|---|---|---|---|
| 上传文件 | POST | https://www.dmxapi.cn/moss-speech/v1/files | multipart/form-data |
| 使用 file_id 转文字 | POST | https://www.dmxapi.cn/moss-speech/v1/audio/transcriptions | application/json |
WARNING
请妥善保管您的 API Key!下方两个示例均需在各自代码的 api_key 变量中填写密钥,请将占位值替换为您自己的 API Key,不要公开分享包含真实密钥的代码。
调用流程
- 运行第一部分,用
file字段上传本地文件,purpose填写transcription。 - 从终端输出中复制
file_id。上传响应也会保存到本地,便于后续查看。 - 将标识填写到第二部分的
payload["file_id"],配置模型和转写参数。 - 运行第二部分,打印并保存识别结果。
后续需要再次识别同一个文件时,可以直接在第二部分复用已取得的 file_id。
模型名称
| 步骤 | 模型要求 |
|---|---|
| 上传文件 | 无需填写 model |
| 普通转写 | moss-transcribe-1.0 |
| 说话人分离、热词或分段 JSON | moss-transcribe-diarize-pro |
第一步:上传文件获取 file_id
import json
import mimetypes
from pathlib import Path
import requests
# ===============================================================
# 步骤1:配置 API 连接信息
# ===============================================================
# DMXAPI 网关的 MOSS 文件上传接口地址
url = "https://www.dmxapi.cn/moss-speech/v1/files"
# DMXAPI API Key(请替换为您自己的密钥;这里只放占位值)
api_key = "YOUR_DMXAPI_API_KEY"
# 要上传的本地音频或视频文件路径,单文件最大 512 MB
input_path = Path(r"C:\Users\Y\Desktop\马尾辫\audio_demo_video_multispeaker_02(1).m4a")
# 上传结果保存路径
output_path = Path("moss_file_upload_result.json")
# 请求超时时间,单位:秒
request_timeout = 1000
# ===============================================================
# 步骤2:配置请求头
# ===============================================================
headers = {
# multipart/form-data 的 Content-Type 由 requests 自动生成,不能手动固定 boundary
"Authorization": f"Bearer {api_key}", # DMXAPI 网关鉴权
"Accept": "application/json", # 文件上传接口返回 JSON
}
# ===============================================================
# 步骤3:配置请求参数
# ===============================================================
form_data = {
# 【purpose】(string, 必填) 文件用途;音频文件使用官方值 audio
"purpose": "audio",
}
def print_result(result):
"""格式化输出上传接口返回的 JSON。"""
print(json.dumps(result, indent=2, ensure_ascii=False))
def save_result(result, output_path):
"""保存成功的上传结果。"""
output_path.parent.mkdir(parents=True, exist_ok=True)
output_path.write_text(json.dumps(result, indent=2, ensure_ascii=False) + "\n", 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("请先在步骤1配置区填写真实的 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)
try:
result = response.json()
except ValueError as error:
raise RuntimeError("文件上传接口返回的不是 JSON。") from error
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}"
)
file_id = result.get("file_id") or result.get("id")
if not isinstance(file_id, str) or not file_id.strip():
raise RuntimeError("文件上传成功响应中没有 file_id 或 id。")
if file_id.startswith("task_"):
raise RuntimeError(
"网关返回的是公开 task_id,不是 MOSS 文件 file_id;"
"请先更新 moss-speech 插件到 2.4.4 或更高版本。"
)
print("file_id:", file_id)
save_result(result, output_path)
if __name__ == "__main__":
main()上传返回示例
以下为历史成功测试中上传 audio.wav 后的实际返回,用于说明响应结构;当前实测异常见页首说明。该文件由音色生成示例的试听音频转换得到。
{
"bytes": 218958,
"created_at": 1793681093,
"file_id": "59d3247a-de98-4aa7-978c-cc760589501f",
"filename": "audio.wav",
"id": "task_5ysSyUWSU0Dpa9i3mxolfLw56v4Uk074",
"object": "file",
"purpose": "transcription",
"status": "processed"
}第二步请使用响应中的 file_id。本次响应里的 id 是上传请求的任务标识;文件标识请以您实际上传时返回的值为准。
第二步:使用 file_id 转文字
将代码另存为 moss_transcribe_file_id.py,填写该示例中的 api_key,并将第一步获得的标识替换到 payload["file_id"],运行 python moss_transcribe_file_id.py。此示例只调用转写接口,无需读取本地音频或第一部分的代码。
import json
from pathlib import Path
import requests
# ===============================================================
# 步骤1:配置转写接口和结果路径
# ===============================================================
transcription_url = "https://www.dmxapi.cn/moss-speech/v1/audio/transcriptions"
api_key = "YOUR_DMXAPI_API_KEY"
transcription_result_path = Path("outputs/moss_transcription_file_id_result.json")
request_timeout = 1000 # 客户端请求超时时间,单位:秒
# ===============================================================
# 步骤2:配置请求头和转写参数
# ===============================================================
headers = {
"Authorization": f"Bearer {api_key}",
"Content-Type": "application/json",
"Accept": "application/json",
}
payload = {
# 普通转写使用 moss-transcribe-1.0
# 启用说话人分离、非空热词或 diarized_json 时改为 moss-transcribe-diarize-pro
"model": "moss-transcribe-1.0",
# 填写第一部分返回的实际文件标识,也可以复用已有的 file_id
"file_id": "YOUR_FILE_ID",
"response_format": "json", # json、text 或 diarized_json
"diarize": False,
"keyterms": [], # 最多 20 个,每个最多 30 个字符
# 使用 file_id 时,不要再添加 file、url 或 audio_url
}
# ===============================================================
# 步骤3:提交转写请求,打印并保存结果
# ===============================================================
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 main():
if not api_key.strip() or api_key == "YOUR_DMXAPI_API_KEY":
raise RuntimeError("请先在代码顶部的 api_key 中填写您的 DMXAPI API Key。")
file_id = payload.get("file_id")
if not isinstance(file_id, str) or not file_id.strip() or file_id.strip() == "YOUR_FILE_ID":
raise RuntimeError("请在 payload[\"file_id\"] 中填写第一部分返回的实际文件标识。")
payload["file_id"] = file_id.strip()
request_headers = dict(headers)
if payload.get("response_format") == "text":
request_headers["Accept"] = "text/plain"
response = requests.post(
transcription_url,
headers=request_headers,
json=payload,
timeout=request_timeout,
)
print("status_code:", response.status_code)
request_id = response.headers.get("x-request-id") or response.headers.get("request-id")
if request_id:
print("request_id:", request_id)
content_type = response.headers.get("Content-Type", "").lower()
if "text/html" in content_type:
raise RuntimeError(
f"网关返回了 HTML 页面而不是转写结果(HTTP {response.status_code}),"
"请检查 transcription_url 是否为本文列出的完整接口地址。"
)
result = read_result(response, payload.get("response_format", "json"))
if isinstance(result, (dict, list)):
text = json.dumps(result, indent=2, ensure_ascii=False) + "\n"
else:
text = str(result)
print(text)
if not response.ok:
raise RuntimeError(f"MOSS file_id 转写失败:HTTP {response.status_code}")
transcription_result_path.parent.mkdir(parents=True, exist_ok=True)
transcription_result_path.write_text(text, encoding="utf-8")
print("output_path:", transcription_result_path.resolve())
if __name__ == "__main__":
main()转写返回示例
以下为历史成功测试中使用第一步返回的 file_id,按上方 response_format="json" 配置执行转写的实际返回;本次复测未获得该成功结果,详见页首说明。
{
"text": "你好,这是音色生成测试一二三四五六七。",
"usage": {
"completion_tokens": 13,
"input_audio_seconds": 4.56,
"prompt_tokens": 57,
"seconds": 5,
"total_tokens": 70,
"type": "duration"
}
}© 2026 DMXAPI MOSS 上传文件并使用 file_id 转文字
