Quickstart: Single-Speaker Speech Generation

Synthesize a piece of text into speech with a single voice, suited to narration, customer-service scripts, announcements, and audio content generation.

Workflow

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

   Fill in the text and the voice. For streaming, use stream=true.

   {
     "model": "moss-tts-1.5-flash",
     "input": "Welcome to the Moss API.[pause 0.8s]Now generating speech.",
     "voice_id": "94aa4989-c7e9-5007-ae42-ab401823e6c9",
     "response_format": "mp3",
     "delivery_method": "url"
   }
   

   {
     "model": "moss-tts-1.5-flash",
     "input": "Welcome to the Moss API.",
     "voice_id": "94aa4989-c7e9-5007-ae42-ab401823e6c9",
     "stream": true,
     "response_format": "pcm",
     "stream_format": "sse"
   }
   

   Preview a voice and copy its Voice ID into your request.

   15 voices

   Browse more voices in the Mossland voice library.

   Preview	Voice name	Voice ID	Description	Language
   	Mambo (Accented)	c6c0a40a-ea82-4468-9a21-333d3c4a76f6	Anime, Character Dubbing · Brisk, Cute, Funny	Chinese · Mandarin
   	Ming Taizu (Hongwu Emperor)	f80b6698-0066-430b-88a0-f0fb8796db34	Character Dubbing, Film & TV · Aloof, Calm, Domineering CEO	Chinese · Mandarin
   	VOX AKUMA	ddc6e38b-6f55-4415-b21b-a88cad2cc1d9	Podcast, Social Media · Lazy, Magnetic, Professional	English · British English
   	Li Bai	7662a8a1-700c-466a-b66b-57ece9e2e231	Film & TV, People · Ancient Style, Passionate	Chinese · Mandarin
   	Jake (Narrator)	f9a1416b-d006-4b77-9581-8f0e8ec1e401	Character Dubbing, People · Calm, Magnetic, Professional	English · British English
   	Experienced Female Teacher	faf7f550-0627-4fc6-8db0-d3bfdad49358	Education, Social Media · Aloof, Natural	Chinese · Mandarin
   	Youthful Male Voice	fe85a513-9bf3-4ef7-aa0b-8b2d11e4db93	Audiobook, Narration · Gentle, Magnetic, Natural	Chinese · Mandarin
   	Male History Narrator	0804710c-8e5e-4b67-acda-5785ef13c309	Audiobook, Film & TV Commentary · Calm, Magnetic	Chinese · Mandarin
   	Elegant British Lady	9d1e88e9-3b9c-4992-a414-7a1cb3ff7ab5	Film & TV, People · Gentle, Magnetic, Natural	English · British English
   	Bright & Lively Female Voice	806c9695-6160-404e-8722-4f788d935af3	Customer Service, Trending Play · Brisk, Lively, Natural	Chinese · Mandarin
   	Classical Chinese Poetry Recitation	2fdf194e-c16e-4587-9027-0d3464e09b4e	Education, Narration · Calm, Magnetic, Professional	Chinese · Mandarin
   	Forbidden City Documentary	133bd03b-d717-4a55-8974-7ffc9afc1b51	Documentary, Narration · Calm, Magnetic, Professional	Chinese · Mandarin
   	Brother Hu (Northeast China)	26838557-6890-4505-bc7c-e8198443a141	Entertainment, Social Media · Funny, Lazy	Chinese · Mandarin
   	Melancholy Autumn	19411508-8731-4b68-901d-7e4b8a98e23f	Film & TV, People · Gentle, Lazy	Chinese · Mandarin
   	Agriculture & Rural Affairs Narrator	944eb93b-3820-49f3-b2c0-4e37a31d1161	Documentary, Narration · Brisk, Magnetic, Professional	Chinese · Mandarin

3. Send the first request

   Send a request to POST /v1/audio/speech. Non-streaming returns JSON and a result URL synchronously when delivery_method=url; streaming returns an SSE event stream when stream_format=sse.

   Non-streamingStreaming

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

   import json
   import os
   import requests
   
   payload = json.load(open("request.json"))
   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),
   })
   

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

   import json
   import os
   import requests
   
   payload = json.load(open("stream-request.json"))
   with requests.post(
       "https://api.mosi.cn/v1/audio/speech",
       headers={"Authorization": f"Bearer {os.environ['MOSS_API_KEY']}"},
       json=payload,
       stream=True,
   ) as resp:
       for line in resp.iter_lines(decode_unicode=True):
           if not line or not line.startswith("data: "):
               continue
           event = json.loads(line[len("data: "):])
           print(event["type"])
           if event["type"] in ("speech.audio.done", "error"):
               break
   

   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),
   })
   
   const reader = resp.body?.getReader()
   if (!reader) throw new Error('The response has no readable stream')
   const decoder = new TextDecoder()
   let buffer = ''
   
   while (true) {
     const { done, value } = await reader.read()
     if (done) break
     buffer += decoder.decode(value, { stream: true })
     const lines = buffer.split('\n')
     buffer = lines.pop() ?? ''
     for (const line of lines) {
       if (!line.startsWith('data: ')) continue
       const event = JSON.parse(line.slice('data: '.length))
       console.log(event.type)
     }
   }
   

4. Retrieve the result

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

   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

   Success indicator: you obtain the result audio (delivery_method=audio) or a result URL (delivery_method=url), and can download or play the generated audio.

Control pauses

input supports the inline pause marker [pause X.Ys], which inserts a pause at the specified position. X.Y is the pause duration in seconds and supports values from 0.1 to 10.0, for example [pause 1.5s]. Pause control applies to both non-streaming and streaming calls.

{
  "model": "moss-tts-1.5-flash",
  "input": "Please note[pause 1.5s]After payment succeeds, the system automatically sends a confirmation message.",
  "voice_id": "<voice_id>",
  "response_format": "mp3",
  "delivery_method": "url"
}

Short pauses may overlap with punctuation and the model's natural rhythm. For a clearly audible pause, use 1.0s or longer. Use the standard format [pause 1.5s].

Next steps