Generate Voice

Generate a voice or speech preview from text and a voice description. This endpoint is driven by input (the text to synthesize) + instruction (a description of the voice style).

POST

/v1/audio/voice/generations

Generate a voice / speech preview from text. The request body is JSON; delivery_method=url returns JSON (containing a result URL), while delivery_method=audio (the default) returns the audio binary.

Authentication

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

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

Supported models

Field	Allowed values
model	`moss-voice-generator`

Request fields

Field	Type	Required	Description
model	string	Yes	Model name; the value is `moss-voice-generator`.
version	string	No	Optionally specify `moss-voice-generator-v1`; omit it to use the server's default.
input	string	Yes	The text to generate speech from.
instruction	string	Yes	A description of the voice style, age, emotion, speaking rate, and so on.
response_format	string	No	Audio format for synchronous requests, e.g. `mp3` / `wav`; asynchronous tasks are not guaranteed to output in this format.
delivery_method	string	No	`audio` returns the audio binary directly; `url` returns JSON and a result URL.
async	boolean	No	When set to `true`, creates an asynchronous task and immediately returns a task object.
webhook_url	string	No	The HTTPS URL called back after the asynchronous task completes.

Request example

curl https://api.mosi.cn/v1/audio/voice/generations \
  -H "Authorization: Bearer $MOSS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "moss-voice-generator",
    "input": "Welcome to tonight's show.",
    "instruction": "A gentle, natural young female voice with a hint of a smile",
    "delivery_method": "url",
    "response_format": "mp3"
  }'

Synchronous URL response fields

When delivery_method=url, JSON (containing a result URL) is returned:

Field	Type	Always returned	Description
id	string	Yes	Task / result ID.
object	string	Yes	Always `audio.voice_generation`.
status	string	Yes	Task status, for example `SUCCESS`.
url	string	Yes	The audio result URL.
response_format	string	Yes	The actual output audio format, for example `mp3` / `wav`.
content_type	string	Yes	The audio MIME type, for example `audio/mpeg` / `audio/wav`.
created_at	integer	Yes	Creation time, a Unix timestamp in seconds.

Response example

{
  "id": "task_abc123",
  "object": "audio.voice_generation",
  "status": "SUCCESS",
  "url": "https://cdn.example.com/out.mp3",
  "response_format": "mp3",
  "content_type": "audio/mpeg",
  "created_at": 1710000000
}

Synchronous audio response fields

When delivery_method is omitted or delivery_method=audio:

Field	Type	Always returned	Description
Content-Type	HTTP header	Yes	The audio MIME type, for example `audio/mpeg` / `audio/wav`.
body	binary	Yes	The audio binary content.

Asynchronous creation response fields

Returned immediately when async=true:

Field	Type	Always returned	Description
id	string	Yes	Task ID.
task_id	string	Yes	Task ID; use this value when querying the task.
object	string	Yes	Always `audio.voice_generation`.
status	string	Yes	Task status after creation, for example `PENDING`.
model_id	string	Yes	The model name actually used.
model_version	string	Yes	The model version actually used.
retry_after	integer	No	Suggested number of seconds to wait before querying the task again.
created_at	integer	Yes	Creation time, a Unix timestamp in seconds.
updated_at	integer	No	Update time, a Unix timestamp in seconds.

Next steps

List Voices

List the voices available to your account.

Single-speaker Speech

Text-to-speech endpoint.