Quickstart: Single-Speaker Speech Generation

Synthesize a piece of text into speech in a single voice — well suited for narration, customer-service scripts, announcements, and audio content generation.

1. Create an API Key

   Open the API Key management platform, create an API Key, and save it as an environment variable. Do not write the API Key into client-side code or commit it to a repository.

   export MOSS_API_KEY="<your-api-key>"
   

2. Prepare the request input

   Use model to specify the model and fill in the input fields required for single-speaker speech generation. For the reference voice, first create it with POST /v1/audio/voices, then use the resulting voice_id here.

   input: text to synthesize voice or voice_id: target voice response_format: output format, defaults to mp3 delivery_method: audio or url

   {
     "model": "moss-tts",
     "input": "Welcome to the Mossland API.",
     "voice_id": "<voice_id>",
     "response_format": "mp3",
     "delivery_method": "url"
   }
   

3. Make your first request

   Send a request to /v1/audio/speech. When delivery_method=url, JSON with a result URL is returned synchronously.

   cURLPythonTypeScript

   curl https://api.mosi.cn/v1/audio/speech \
     -H "Authorization: Bearer $MOSS_API_KEY" \
     -H "Content-Type: application/json" \
     -d @request.json
   

   import os
   import requests
   
   resp = requests.post(
       "https://api.mosi.cn/v1/audio/speech",
       headers={"Authorization": f"Bearer {os.environ['MOSS_API_KEY']}"},
       json=payload,
   )
   print(resp.json())
   

   const resp = await fetch('https://api.mosi.cn/v1/audio/speech', {
     method: 'POST',
     headers: {
       Authorization: `Bearer ${apiKey}`,
       'Content-Type': 'application/json',
     },
     body: JSON.stringify(payload),
   })
   

4. Retrieve the result

   When delivery_method=url, read the result URL directly from the synchronous response JSON. If you passed async=true, the endpoint first returns a task_id, which you then use to query the task.

   cURLPythonTypeScript

   curl https://api.mosi.cn/v1/audio/tasks/$TASK_ID \
     -H "Authorization: Bearer $MOSS_API_KEY"
   

   resp = requests.get(
       f"https://api.mosi.cn/v1/audio/tasks/{task_id}",
       headers={"Authorization": f"Bearer {os.environ['MOSS_API_KEY']}"},
   )
   print(resp.json())
   

   const resp = await fetch(`https://api.mosi.cn/v1/audio/tasks/${taskId}`, {
     headers: { Authorization: `Bearer ${apiKey}` },
   })
   

5. Verify success

   Sign of success: you obtain the result audio (delivery_method=audio) or the result URL (delivery_method=url), and can download or play the generated audio.

Next steps