Create Transcription

Choose transcription mode

Scenario	model	Response format
Standard audio transcription	`moss-transcribe-1.0`	JSON / text
Multi-speaker transcription	`moss-transcribe-diarize-pro`	JSON with `segments`; pass `stream=true` to return SSE

Request parameters

FieldTypeRequiredDescription

model: stringRequired

Model ID. Use moss-transcribe-1.0 for standard transcription; use moss-transcribe-diarize-pro for multi-speaker transcription, keyterms, and SSE streaming output.

file: multipart fileChoose one of four

Upload a local audio or video file directly via multipart/form-data, without first calling the file upload endpoint. Without async=true, the transcription result is returned synchronously. Maximum 512 MB per file.

file_id: stringChoose one of four

Reference the file ID returned by POST /v1/files.

url: stringChoose one of four

Public audio URL accessible to the server; it must not point to localhost, a loopback address, or a private network address.

audio_url: stringChoose one of four

Compatibility field for url with the same access restrictions; use url for new calls.

diarize: booleanOptional

When set to true, returns speaker diarization results. Only moss-transcribe-diarize-pro supports this field; omit it or pass false to return only the complete text.

keyterms: string[]Optional

List of keyterms used to improve recognition accuracy for proper nouns, personal names, brand names, and business terminology. Only moss-transcribe-diarize-pro supports this field; up to 20 keyterms, with a maximum of 30 characters each; omit it or pass [] to disable it. With multipart/form-data, pass a JSON-encoded string array such as ["MOSS","SGLang"].

stream: booleanOptional

Only moss-transcribe-diarize-pro supports true, which returns transcription events over SSE; it cannot be combined with async=true.

response_format: stringOptional

Transcription result format. Non-streaming requests default to json; streaming always returns SSE events, so explicitly use verbose_json.

async: booleanOptional

When set to true, creates an asynchronous task and immediately returns a task object; cannot be combined with stream=true.

webhook_url: stringOptional

The HTTPS URL called back after the asynchronous task completes.

Supported formats and upload limits

Item	Description
File size	Maximum 512 MB; direct uploads use the same limit as `/v1/files`.
Supported formats	AAC, AMR, FLAC, M4A, ALAC, MOV, MP3, MP4, MPG, OGG, OPUS, WAV, WebM, WMA
Audio/video containers	MOV, MP4, MPG, and WebM can be transcribed.

Return value

Standard JSON: object

Returns the complete transcription text when response_format=json and diarize is not enabled.

Speaker diarization: object

Returns the complete text and speaker segments when diarize is enabled or response_format=diarized_json is used.

Text: string

Returns plain text directly when response_format=text.

SSE: event stream

When stream=true, server-sent events are returned continuously until completion or failure; the example uses the streaming-only verbose_json format.

Asynchronous task: object

When async=true, immediately returns a task object; retrieve the result from the task query endpoint.

Error codes

HTTPerror.codeTrigger and suggested action

400: 4 error codes

An invalid input source, stream / async combination, or keyterms.

Error details

The following cases return a parameter error:

keyterms is not an array of strings.
keyterms contains non-string elements.
The standard moss-transcribe-1.0 model is used with non-empty keyterms.

Next steps

Upload File

Upload an audio file and obtain a file_id.

List Voices

List the voices available to your account.

Request example

curl -X POST "https://api.mosi.cn/v1/audio/transcriptions" \
  -H "Authorization: Bearer $MOSS_API_KEY" \
  -F "model=moss-transcribe-1.0" \
  -F "file=@./audio.mp3" \
  -F "response_format=json"

import os
import requests

with open("./audio.mp3", "rb") as file:
    response = requests.post(
        "https://api.mosi.cn/v1/audio/transcriptions",
        headers={
        "Authorization": f"Bearer {os.environ['MOSS_API_KEY']}",
        },
        data={
            "model": "moss-transcribe-1.0",
            "response_format": "json",
        },
        files={"file": file},
    )

response.raise_for_status()
print(response.json())

import { readFile } from "node:fs/promises"

const bytes = await readFile("./audio.mp3")
const form = new FormData()
form.append("model", "moss-transcribe-1.0")
form.append("file", new Blob([bytes]), "audio.mp3")
form.append("response_format", "json")

const response = await fetch("https://api.mosi.cn/v1/audio/transcriptions", {
  method: "POST",
  headers: {
    "Authorization": "Bearer " + process.env.MOSS_API_KEY,
  },
  body: form,
})

if (!response.ok) throw new Error(`HTTP ${response.status}`)
console.log(await response.json())

curl -X POST "https://api.mosi.cn/v1/audio/transcriptions" \
  -H "Authorization: Bearer $MOSS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "moss-transcribe-1.0",
  "file_id": "<file_id>",
  "response_format": "json"
}'

import os
import requests

response = requests.post(
        "https://api.mosi.cn/v1/audio/transcriptions",
        headers={
        "Authorization": f"Bearer {os.environ['MOSS_API_KEY']}",
        "Content-Type": "application/json",
        },
        json={
            "model": "moss-transcribe-1.0",
            "file_id": "<file_id>",
            "response_format": "json",
        },
)

response.raise_for_status()
print(response.json())

const response = await fetch("https://api.mosi.cn/v1/audio/transcriptions", {
  method: "POST",
  headers: {
    "Authorization": "Bearer " + process.env.MOSS_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "model": "moss-transcribe-1.0",
    "file_id": "<file_id>",
    "response_format": "json"
  }),
})

if (!response.ok) throw new Error(`HTTP ${response.status}`)
console.log(await response.json())

curl -X POST "https://api.mosi.cn/v1/audio/transcriptions" \
  -H "Authorization: Bearer $MOSS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "moss-transcribe-diarize-pro",
  "file_id": "<file_id>",
  "diarize": true,
  "response_format": "json"
}'

import os
import requests

response = requests.post(
        "https://api.mosi.cn/v1/audio/transcriptions",
        headers={
        "Authorization": f"Bearer {os.environ['MOSS_API_KEY']}",
        "Content-Type": "application/json",
        },
        json={
            "model": "moss-transcribe-diarize-pro",
            "file_id": "<file_id>",
            "diarize": True,
            "response_format": "json",
        },
)

response.raise_for_status()
print(response.json())

const response = await fetch("https://api.mosi.cn/v1/audio/transcriptions", {
  method: "POST",
  headers: {
    "Authorization": "Bearer " + process.env.MOSS_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "model": "moss-transcribe-diarize-pro",
    "file_id": "<file_id>",
    "diarize": true,
    "response_format": "json"
  }),
})

if (!response.ok) throw new Error(`HTTP ${response.status}`)
console.log(await response.json())

curl -X POST "https://api.mosi.cn/v1/audio/transcriptions" \
  -H "Authorization: Bearer $MOSS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "moss-transcribe-diarize-pro",
  "file_id": "<file_id>",
  "diarize": true,
  "response_format": "json",
  "keyterms": [
    "MOSS",
    "SGLang",
    "矩池云"
  ]
}'

import os
import requests

response = requests.post(
        "https://api.mosi.cn/v1/audio/transcriptions",
        headers={
        "Authorization": f"Bearer {os.environ['MOSS_API_KEY']}",
        "Content-Type": "application/json",
        },
        json={
            "model": "moss-transcribe-diarize-pro",
            "file_id": "<file_id>",
            "diarize": True,
            "response_format": "json",
            "keyterms": [
                "MOSS",
                "SGLang",
                "矩池云",
            ],
        },
)

response.raise_for_status()
print(response.json())

const response = await fetch("https://api.mosi.cn/v1/audio/transcriptions", {
  method: "POST",
  headers: {
    "Authorization": "Bearer " + process.env.MOSS_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "model": "moss-transcribe-diarize-pro",
    "file_id": "<file_id>",
    "diarize": true,
    "response_format": "json",
    "keyterms": [
      "MOSS",
      "SGLang",
      "矩池云"
    ]
  }),
})

if (!response.ok) throw new Error(`HTTP ${response.status}`)
console.log(await response.json())

curl -N -X POST "https://api.mosi.cn/v1/audio/transcriptions" \
  -H "Authorization: Bearer $MOSS_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{
  "model": "moss-transcribe-diarize-pro",
  "file_id": "<file_id>",
  "diarize": true,
  "stream": true,
  "response_format": "verbose_json"
}'

import os
import requests

with requests.post(
        "https://api.mosi.cn/v1/audio/transcriptions",
        headers={
        "Authorization": f"Bearer {os.environ['MOSS_API_KEY']}",
        "Content-Type": "application/json",
        "Accept": "text/event-stream",
        },
        json={
            "model": "moss-transcribe-diarize-pro",
            "file_id": "<file_id>",
            "diarize": True,
            "stream": True,
            "response_format": "verbose_json",
        },
        stream=True,
    ) as response:
    response.raise_for_status()
    for line in response.iter_lines(decode_unicode=True):
        if line:
            print(line)

const response = await fetch("https://api.mosi.cn/v1/audio/transcriptions", {
  method: "POST",
  headers: {
    "Authorization": "Bearer " + process.env.MOSS_API_KEY,
    "Content-Type": "application/json",
    "Accept": "text/event-stream",
  },
  body: JSON.stringify({
    "model": "moss-transcribe-diarize-pro",
    "file_id": "<file_id>",
    "diarize": true,
    "stream": true,
    "response_format": "verbose_json"
  }),
})

if (!response.ok || !response.body) throw new Error(`HTTP ${response.status}`)
const reader = response.body.getReader()
const decoder = new TextDecoder()
while (true) {
  const { done, value } = await reader.read()
  if (done) break
  process.stdout.write(decoder.decode(value, { stream: true }))
}

Response example

{
  "text": "This is a short transcription test audio."
}

{
  "task": "transcribe",
  "duration": 5.18,
  "text": "欢迎使用 Moss API。",
  "segments": [
    {
      "type": "transcript.text.segment",
      "id": "seg_001",
      "start": 0.16,
      "end": 5.18,
      "text": "欢迎使用 Moss API。",
      "speaker": "S01"
    }
  ]
}

data: {"type":"task.created","task_id":"task-123","object":"audio.transcription","status":"PROCESSING","model":"moss-transcribe-diarize-pro"}

data: {"type":"transcript.text.delta","delta":"欢迎"}

data: {"type":"transcript.segment.done","content_index":0,"speaker":"S01","start":0.16,"end":5.18,"text":"欢迎使用 Moss API。","session_usage":{"prompt_tokens":153,"completion_tokens":32,"total_tokens":185}}

data: {"type":"transcript.text.done","text":"欢迎使用 Moss API。","usage":{"prompt_tokens":153,"completion_tokens":32,"total_tokens":185}}

data: {"type":"task.created","task_id":"task-123","object":"audio.transcription","status":"PROCESSING","model":"moss-transcribe-diarize-pro"}

data: {"type":"transcript.text.delta","delta":"欢迎"}

data: {"type":"transcript.segment.done","content_index":0,"speaker":"S01","start":0.16,"end":5.18,"text":"欢迎使用 Moss API。","session_usage":{"prompt_tokens":153,"completion_tokens":32,"total_tokens":185}}

data: {"type":"transcript.text.done","text":"欢迎使用 Moss API。","usage":{"prompt_tokens":153,"completion_tokens":32,"total_tokens":185}}

data: {"type":"task.created","task_id":"task-123","object":"audio.transcription","status":"PROCESSING","model":"moss-transcribe-diarize-pro"}

data: {"type":"transcript.text.delta","delta":"欢迎"}

data: {"type":"transcript.segment.done","content_index":0,"speaker":"S01","start":0.16,"end":5.18,"text":"欢迎使用 Moss API。","session_usage":{"prompt_tokens":153,"completion_tokens":32,"total_tokens":185}}

data: {"type":"transcript.text.done","text":"欢迎使用 Moss API。","usage":{"prompt_tokens":153,"completion_tokens":32,"total_tokens":185}}