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 |
|---|---|
| Text generation and chat | Choose model=nex-n2.6 and call Chat Completions, Responses, or Messages according to your client's protocol. |
| 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 |
Language models usually use a JSON request body. Chat Completions and Messages take messages, and Responses takes input. Multi-turn history is passed with the request.
The inputs available on the same endpoint vary by model. Taking /v1/responses as an example, Nex supports plain text, while MOSS-VL requires both a text instruction and media.
Text Generation and Chat · Create Response (Nex)
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 MOSS Create 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.
When a language model needs to show its reply progressively, use SSE streaming output and handle incremental and completion events according to the chosen protocol.
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. |
| Chat Completions object | Read the reply from choices[0].message.content. |
| Messages object | Iterate over the content array and read the content blocks whose type is text. |
| 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.