Core Concepts
Understand model IDs, input formats, request execution, and response types in the Moss API.
Models and scenarios
Start with the business scenario when choosing a model. Use cases provide recommended calls and copyable examples, while the API Reference documents complete request parameters, responses, and errors.
| What you want to do | Start here |
|---|---|
| Make your first call quickly | Quickstart |
| Choose the right model | Model List |
| Integrate by business scenario | Use cases |
| Confirm fields and response structures | API Overview |
| Scenario | How to call it |
|---|---|
| Single-speaker speech generation | model=moss-tts-1.5-flash |
| Multi-speaker transcription | model=moss-transcribe-diarize-pro |
| Image and video understanding | model=moss-vl-1.0 |
Input methods
Different endpoints accept different input methods. Text and configuration usually go in a JSON request body. Upload local files with multipart/form-data. Reference previously uploaded or hosted files with a file_id or URL.
| Method | Description | Common uses |
|---|---|---|
| JSON fields | Pass text, parameters, and reference IDs directly in the request body. | TTS input, VL input_text, voice_id |
| Local file | Upload using the file field specified by the endpoint, such as file; use audio_sample when creating a voice. | Audio transcription, voice creation, file upload |
file_id | Upload a file first, then reuse it in a capability endpoint. | Audio transcription, multimodal understanding |
| URL | Pass a public or object-storage URL that the server can access. | Audio transcription, multimodal understanding |
voice_id
voice_id uniquely identifies a voice used for speech generation. TTS and TTSD accept only a voice ID; they do not accept voice_url, voice_data, inline audio, or reference audio as a voice input.
| How to obtain it | Description |
|---|---|
| List voices | Call GET /v1/audio/voices to retrieve voices available to the current account. |
| Create a voice | Call POST /v1/audio/voices to upload reference audio and create a new voice. |
| Copy from the voice library | Copy the ID from a voice card in the Mossland voice library. |
Synchronous, asynchronous, and streaming
Synchronous, asynchronous, and streaming are different execution modes. Streaming is not the same as asynchronous processing or a bidirectional real-time conversation.
| Mode | Description | Suitable for |
|---|---|---|
| Synchronous | Keep the request connected and return the result when processing completes. | Short-text TTS, short audio transcription, image understanding |
| Asynchronous | Use async=true to create a task; query the complete result with task_id, and optionally receive a terminal-state notification through webhook_url. | Longer speech generation and audio processing |
| Streaming | Use stream=true so the server continuously returns audio chunks or events. | Low-latency TTS and real-time transcription events |
When an endpoint supports streaming, its API Reference documents stream, stream_format, and the corresponding response events. In general, do not send stream=true together with async=true.
Response types and how to read them
Response objects differ by endpoint. Read the fields required by the relevant Reference page, and ignore unused compatibility fields.
| Response type | How to read it |
|---|---|
| Audio binary | When Content-Type is audio/*, read the response body directly and save or play the audio; do not parse it as JSON. |
| Audio result JSON | After confirming status=SUCCESS, read url to obtain the generated audio and download the result file promptly. |
| Asynchronous creation JSON | Read task_id and retry_after, then call GET /v1/audio/tasks/{task_id} to query the task. |
| Task query JSON | Use status to determine the task state; on success, read url, text, or segments as appropriate for the capability; on failure, read error. |
| Transcription JSON | For standard transcription, read text; for speaker diarization results, read text and segments. |
| Responses API object | After confirming status=completed, read output[].content[].text; when status=incomplete, check incomplete_details. |
| SSE event stream | When Content-Type is text/event-stream, parse the JSON in each data: entry in order, and use type to handle incremental and completion events. |
| Error JSON | When a request fails, read fields such as error.code, error.message, and error.param to identify the issue. |
Errors and troubleshooting
| Symptom | Common causes |
|---|---|
| 400 | The request structure, field value, file count, or input format is invalid. |
| 401 | The API Key is missing, invalid, or expired. |
| 403 | Account permissions, model permissions, or security policies blocked the request. |
| 404 | The requested resource does not exist. |
| 413 | The file or request body exceeds a limit. |
| 429 | The request rate or concurrency limit was exceeded. |
| 5xx | A server or upstream model failed; retry according to the error message or contact support. |
When troubleshooting, first confirm the endpoint, model, input method, file size, URL accessibility, and error.code in the error body. See Error Codes for the complete error structure.