Create Transcription

Audio transcription endpoint. Supports multipart file, file_id, url, and audio_url; audio_data is not supported.

POST

/v1/audio/transcriptions

Speech recognition. The request body is multipart/form-data or JSON. moss-transcribe-1.0 returns { text } synchronously; moss-transcribe-diarize-pro with diarize=true returns structured segments, and you can additionally pass stream=true to return transcription events over SSE.

Authentication

Add Authorization: Bearer <API_KEY> to the request headers to authenticate. You can generate a key on the console "API Keys" page.

curl -X POST https://api.mosi.cn/v1/audio/transcriptions \
  -H "Authorization: Bearer $MOSS_API_KEY"

Supported models

Field	Allowed values
model	`moss-transcribe-1.0` / `moss-transcribe-diarize-pro`

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 fields

Field	Type	Required	Description
model	string	Yes	See "Choose transcription mode" for values.
diarize	boolean	No	Whether to return speaker-separation results; recommended to pass `true` when using `moss-transcribe-diarize-pro`.
stream	boolean	No	`moss-transcribe-diarize-pro` supports `true`, which returns transcription events over SSE; it cannot be combined with `async=true`.
response_format	string	No	`json` returns JSON; `diarized_json` returns structured JSON with speakers and time ranges; `text` returns plain text. Pass `json` or `diarized_json` for streaming scenarios.
keyterms	string[]	No	List of keyterms used to improve recognition accuracy for proper nouns, personal names, brand names, terminology, and similar content. Supported by the current `moss-transcribe-diarize-pro`; up to 20 keyterms, with a maximum of 30 characters each; omit it or pass `[]` to disable this feature.
async	boolean	No	Creates an asynchronous task when set to `true`.
webhook_url	string	No	The HTTPS URL to call back once the asynchronous task completes.
file	multipart file	Conditionally required	Local file; maximum 512 MB per file.
file_id	string	Conditionally required	File ID returned by `/v1/files`.
url	string	Conditionally required	Public audio URL; it must not point to localhost, a loopback address, or a private network address.
audio_url	string	Conditionally required	Compatibility field for `url`; the same access restrictions apply.

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.

Request example

{
  "model": "moss-transcribe-1.0",
  "file_id": "<file_id>",
  "response_format": "json"
}

{
  "model": "moss-transcribe-diarize-pro",
  "file_id": "<file_id>",
  "diarize": true,
  "response_format": "json"
}

{
  "model": "moss-transcribe-diarize-pro",
  "file_id": "<file_id>",
  "diarize": true,
  "response_format": "diarized_json",
  "keyterms": ["MOSS", "SGLang", "矩池云"]
}

{
  "model": "moss-transcribe-diarize-pro",
  "file_id": "<file_id>",
  "diarize": true,
  "stream": true,
  "response_format": "json"
}

Response fields

Standard transcription (`response_format=json`)

Field	Type	Always returned	Description
text	string	Yes	The full recognized text.

Multi-speaker transcription

Field	Type	Always returned	Description
task	string	Yes	Task type, currently returns `transcribe`.
duration	number	Yes	Audio duration, in seconds.
text	string	Yes	The full transcription text.
segments	array	Yes	Segment list; may be an empty array for short audio or when there are no valid segments.
segments[].type	string	When segmented	Segment event type.
segments[].id	string	When segmented	Segment ID.
segments[].start	number	When segmented	Segment start time, in seconds.
segments[].end	number	When segmented	Segment end time, in seconds.
segments[].text	string	When segmented	Text of the segment.
segments[].speaker	string	When segmented	Speaker label, for example `S01`.

Text response (`response_format=text`)

Multi-speaker streaming output (SSE)

When stream=true, text/event-stream is returned; SSE frames consist only of data: lines (no event: line), and the event type is carried in the type field of each frame's JSON.

Field	Type	Always returned	Description
task.created	SSE event	Yes	Streaming task creation event, carrying `task_id` / `object` / `status` / `model`.
transcript.text.delta	SSE event	As applicable	Incremental text event, carrying a `delta` text fragment.
transcript.segment.done	SSE event	As applicable	Segment completion event, carrying `content_index` / `speaker` / `text` and other fields.
transcript.text.done	SSE event	Yes	Transcription completion event, may carry the full `text` or `usage`.
usage	object	Optional in events	Usage information, returned according to the actual server events.

data: {"type":"task.created","task_id":"<task_id>","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","text":"大家好，"}

data: {"type":"transcript.segment.done","content_index":1,"speaker":"S02","text":"你好。"}

data: {"type":"transcript.text.done","text":"大家好，你好。","usage":{"prompt_tokens":142,"completion_tokens":12,"total_tokens":154}}

Asynchronous creation response (`async=true`)

Field	Type	Always returned	Description
id	string	Yes	Task ID.
task_id	string	Yes	Task query ID, usually the same as `id`.
object	string	Yes	Always `audio.transcription`.
status	string	Yes	Initial status, for example `PENDING`.
retry_after	integer	No	Suggested polling interval, in seconds.
created_at	integer	Yes	Creation time, a Unix timestamp in seconds.
updated_at	integer	No	Update time, a Unix timestamp in seconds.

For the result fields after an asynchronous task completes, see GET /v1/audio/tasks/{task_id}.

Next steps

Upload File

Upload an audio file and obtain a file_id.

List Voices

List the voices available to your account.

Errors

The following cases return a parameter error:

keyterms is not an array of strings.
keyterms contains a non-string element.
A non-empty keyterms value is provided for the standard moss-transcribe-1.0 model.