MaaS_Lyria

User Guide

It is recommended to call the Lyria music generation API according to the following process:

Select the invocation method
Vertex Native: generateContent or v1beta1 path, with the request body following the Google Vertex AI generateContent structure.
OpenAI Compatibility: chat/completions series of paths, with the request body in OpenAI Chat Completions format.
Send request and wait for full response Lyria is a synchronous interface that returns the complete result (lyric text + audio base64) in one POST, without task polling. The generation time is usually long, and it is recommended to have an HTTP read timeout of ≥ 120s. Streaming (stream: true) is not supported.
Get Audio
generateContent: Read from candidates[].content.parts[].inlineData, where the mimeType is like audio/mpeg and the data is base64-encoded audio.
chat/completions: Read base64 audio from choices[0].message.audio.data

Universal Request Header

Header	Required	Description
Authorization	is	Bearer
Content-Type	is (POST)	application/json

1. Text-to-Music — generateContent (Standard Path)

Request URL

POST https://genaiapi-m2.cloudsway.net/v1/ai/{endpointPath}/music/generateContent

Request Parameters

Field	Type	Position	Required	Description
endpointPath	string	path	is	Endpoint Path
body	object	body	is	Vertex generateContent Request Body

Request Body Fields

Field	Type	Required	Description
contents	array	is	Input content list
contents[].role	string	No	Content roles, such as user
contents[].parts	array	is	Content Fragment List
contents[].parts[].text	string	is	Music description / style / theme prompt
generationConfig	object	No	Generate Configuration
generationConfig.responseModalities	array	No	Expected output modalities, e.g., ["AUDIO", "TEXT"]

Response Parameters

Field	Type	Description
candidates	array	Model Output Candidate
candidates[].content	object	Generated Content
candidates[].content.role	string	If model
candidates[].content.parts	array	Output Segment
candidates[].content.parts[].text	string	Lyrics / Structural Text
candidates[].content.parts[].inlineData	object	Inline binary data
candidates[].content.parts[].inlineData.mimeType	string	如 audio/mpeg
candidates[].content.parts[].inlineData.data	string	Audio base64
candidates[].finishReason	string	End reason, such as STOP
usageMetadata	object	Token Usage
usageMetadata.promptTokenCount	integer	Number of input tokens
usageMetadata.candidatesTokenCount	integer	Number of output tokens
usageMetadata.totalTokenCount	integer	Total number of tokens
usageMetadata.promptTokensDetails	array	Input Token Modal Details
usageMetadata.promptTokensDetails[].modality	string	As TEXT
usageMetadata.promptTokensDetails[].tokenCount	integer	Number of tokens
usageMetadata.candidatesTokensDetails	array	Output token modality details
usageMetadata.candidatesTokensDetails[].modality	string	Such as AUDIO
usageMetadata.candidatesTokensDetails[].tokenCount	integer	Number of tokens
responseId	string	Response ID

Request Example A (Explicitly Specify role and responseModalities)

curl --request POST \
  --url 'https://genaiapi-m2.cloudsway.net/v1/ai/{endpointPath}/music/generateContent' \
  --header 'Authorization: Bearer {your AK}' \
  --header 'Content-Type: application/json' \
  --data '{
    "contents": [
      {
        "role": "user",
        "parts": [
          {
            "text": "Upbeat pop song about a summer road trip, catchy chorus, female vocal"
          }
        ]
      }
    ],
    "generationConfig": {
      "responseModalities": ["AUDIO", "TEXT"]
    }
  }'

Request Example B (only pass prompt)

curl --request POST \
  --url 'https://genaiapi-m2.cloudsway.net/v1/ai/{endpointPath}/music/generateContent' \
  --header 'Authorization: Bearer {your AK}' \
  --header 'Content-Type: application/json' \
  --data '{
    "contents": [
      {
        "parts": [
          {
            "text": "Calm piano instrumental for studying, 90 BPM"
          }
        ]
      }
    ]
  }'

Response Example

{
  "candidates": [
    {
      "content": {
        "role": "model",
        "parts": [
          {
            "text": "[Verse]\n...\n[Chorus]\n..."
          },
          {
            "inlineData": {
              "mimeType": "audio/mpeg",
              "data": "<base64-encoded-mp3>"
            }
          }
        ]
      },
      "finishReason": "STOP"
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 14,
    "candidatesTokenCount": 3199,
    "totalTokenCount": 3213,
    "promptTokensDetails": [
      { "modality": "TEXT", "tokenCount": 14 }
    ],
    "candidatesTokensDetails": [
      { "modality": "AUDIO", "tokenCount": 3199 }
    ]
  },
  "responseId": "******"
}

2. Text-to-Music — generateContent (Native v1beta1)

Request URL

POST https://genaiapi-m2.cloudsway.net/{endpointPath}/music/v1beta1/publishers/google/models/{modelName}:generateContent

Request Parameters

Field	Type	Position	Required	Description
endpointPath	string	path	is	Endpoint Path
modelName	string	path	is	Model name, e.g., lyria-3-pro-preview
body	object	body	is	Vertex generateContent Request Body

Request Body Fields

Field	Type	Required	Description
contents	array	is	Input content list
contents[].role	string	No	Content roles, such as user
contents[].parts	array	is	Content Fragment List
contents[].parts[].text	string	is	Music description / style / theme prompt
generationConfig	object	No	Generate Configuration
generationConfig.responseModalities	array	No	Expected output modalities, e.g., ["AUDIO", "TEXT"]

Response Parameters

Field	Type	Description
candidates	array	Model Output Candidate
candidates[].content	object	Generated Content
candidates[].content.role	string	If model
candidates[].content.parts	array	Output Segment
candidates[].content.parts[].text	string	Lyrics / Structural Text
candidates[].content.parts[].inlineData	object	Inline binary data
candidates[].content.parts[].inlineData.mimeType	string	如 audio/mpeg
candidates[].content.parts[].inlineData.data	string	Audio base64
candidates[].finishReason	string	End reason, such as STOP
usageMetadata	object	Token Usage
usageMetadata.promptTokenCount	integer	Number of input tokens
usageMetadata.candidatesTokenCount	integer	Number of output tokens
usageMetadata.totalTokenCount	integer	Total number of tokens
usageMetadata.promptTokensDetails	array	Input Token Modal Details
usageMetadata.promptTokensDetails[].modality	string	As TEXT
usageMetadata.promptTokensDetails[].tokenCount	integer	Number of tokens
usageMetadata.candidatesTokensDetails	array	Output token modality details
usageMetadata.candidatesTokensDetails[].modality	string	Such as AUDIO
usageMetadata.candidatesTokensDetails[].tokenCount	integer	Number of tokens
responseId	string	Response ID

Request Example A (Explicitly Specify role and responseModalities)

curl --request POST \
  --url 'https://genaiapi-m2.cloudsway.net/{endpointPath}/music/v1beta1/publishers/google/models/lyria-3-pro-preview:generateContent' \
  --header 'Authorization: Bearer {your AK}' \
  --header 'Content-Type: application/json' \
  --data '{
    "contents": [
      {
        "role": "user",
        "parts": [
          {
            "text": "Upbeat pop song about a summer road trip, catchy chorus, female vocal"
          }
        ]
      }
    ],
    "generationConfig": {
      "responseModalities": ["AUDIO", "TEXT"]
    }
  }'

Request Example B (only pass prompt)

curl --request POST \
  --url 'https://genaiapi-m2.cloudsway.net/{endpointPath}/music/v1beta1/publishers/google/models/lyria-3-pro-preview:generateContent' \
  --header 'Authorization: Bearer {your AK}' \
  --header 'Content-Type: application/json' \
  --data '{
    "contents": [
      {
        "parts": [
          {
            "text": "Calm piano instrumental for studying, 90 BPM"
          }
        ]
      }
    ]
  }'

Response Example

{
  "candidates": [
    {
      "content": {
        "role": "model",
        "parts": [
          {
            "text": "[Verse]\n...\n[Chorus]\n..."
          },
          {
            "inlineData": {
              "mimeType": "audio/mpeg",
              "data": "<base64-encoded-mp3>"
            }
          }
        ]
      },
      "finishReason": "STOP"
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 14,
    "candidatesTokenCount": 3199,
    "totalTokenCount": 3213,
    "promptTokensDetails": [
      { "modality": "TEXT", "tokenCount": 14 }
    ],
    "candidatesTokensDetails": [
      { "modality": "AUDIO", "tokenCount": 3199 }
    ]
  },
  "responseId": "********"
}

3. OpenAI — google/chat/completions

Request URL

POST https://genaiapi-m2.cloudsway.net/v1/ai/{endpointPath}/music/google/chat/completions

Request Parameters

Field	Type	Position	Required	Description
endpointPath	string	path	is	Endpoint Path
body	object	body	is	OpenAI Chat Completions Request Body

Request Body Fields

Field	Type	Required	Description
model	string	is	Model name, e.g., lyria-3-pro-preview
messages	array	is	Conversation Message List
messages[].role	string	is	Message role, such as user
messages[].content	string	is	Music description prompt
stream	boolean	No	Streaming support; Lyria does not support streaming
modalities	array	No	Output modes, such as ["audio", "text"]

Response Parameters

Field	Type	Description
id	string	Response ID
object	string	Object type, such as chat.completion
choices	array	Generated Results
choices[].index	integer	Result Index
choices[].message	object	Assistant Message
choices[].message.role	string	As assistant
choices[].message.content	string	Lyric Text
choices[].message.audio	object	Audio Data
choices[].message.audio.data	string	Audio base64
choices[].message.audio.mime_type	string	如 audio/mpeg
choices[].finish_reason	string	End reason, e.g., stop
usage	object	Token Usage
usage.prompt_tokens	integer	Number of input tokens
usage.completion_tokens	integer	Number of output tokens
usage.total_tokens	integer	Total number of tokens

Request Example A (Explicitly Specify Stream and Modalities)

curl --request POST \
  --url 'https://genaiapi-m2.cloudsway.net/v1/ai/{endpointPath}/music/google/chat/completions' \
  --header 'Authorization: Bearer {your AK}' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "lyria-3-pro-preview",
    "stream": false,
    "messages": [
      {
        "role": "user",
        "content": "Upbeat pop song about a summer road trip, catchy chorus, female vocal"
      }
    ],
    "modalities": ["audio", "text"]
  }'

Request Example B (Minimum Parameters)

curl --request POST \
  --url 'https://genaiapi-m2.cloudsway.net/v1/ai/{endpointPath}/music/google/chat/completions' \
  --header 'Authorization: Bearer {your AK}' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "lyria-3-pro-preview",
    "messages": [
      {
        "role": "user",
        "content": "Calm piano instrumental for studying, 90 BPM"
      }
    ]
  }'

Response Example

{
  "id": "chatcmpl-xxx",
  "object": "chat.completion",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "[Verse]\n...\n[Chorus]\n...",
        "audio": {
          "data": "<base64-encoded-mp3>",
          "mime_type": "audio/mpeg"
        }
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 14,
    "completion_tokens": 3199,
    "total_tokens": 3213
  }
}

4. OpenAI Compatibility — chat/completions (Endpoint Path Pattern)

Request URL

POST https://genaiapi-m2.cloudsway.net/v1/ai/{endpointPath}/music/chat/completions

Request Parameters

Field	Type	Position	Required	Description
endpointPath	string	path	is	Endpoint Path
body	object	body	is	OpenAI Chat Completions Request Body

Request Body Fields

Field	Type	Required	Description
model	string	is	Model name, e.g., lyria-3-pro-preview
messages	array	is	Conversation Message List
messages[].role	string	is	Message role, such as user
messages[].content	string	is	Music description prompt
stream	boolean	No	Streaming support; Lyria does not support streaming
modalities	array	No	Output modes, such as ["audio", "text"]

Response Parameters

Field	Type	Description
id	string	Response ID
object	string	Object type, such as chat.completion
choices	array	Generated Results
choices[].index	integer	Result Index
choices[].message	object	Assistant Message
choices[].message.role	string	As assistant
choices[].message.content	string	Lyric Text
choices[].message.audio	object	Audio Data
choices[].message.audio.data	string	Audio base64
choices[].message.audio.mime_type	string	audio/mpeg
choices[].finish_reason	string	End reason, e.g., stop
usage	object	Token Usage
usage.prompt_tokens	integer	Number of input tokens
usage.completion_tokens	integer	Number of output tokens
usage.total_tokens	integer	Total number of tokens

Request Example A (Explicitly Specify Stream and Modalities)

curl --request POST \
  --url 'https://genaiapi-m2.cloudsway.net/v1/ai/{endpointPath}/music/chat/completions' \
  --header 'Authorization: Bearer {your AK}' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "lyria-3-pro-preview",
    "stream": false,
    "messages": [
      {
        "role": "user",
        "content": "Upbeat pop song about a summer road trip, catchy chorus, female vocal"
      }
    ],
    "modalities": ["audio", "text"]
  }'

Request Example B (Minimum Parameters)

curl --request POST \
  --url 'https://genaiapi-m2.cloudsway.net/v1/ai/{endpointPath}/music/chat/completions' \
  --header 'Authorization: Bearer {your AK}' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "lyria-3-pro-preview",
    "messages": [
      {
        "role": "user",
        "content": "Calm piano instrumental for studying, 90 BPM"
      }
    ]
  }'

Response Example

{
  "id": "chatcmpl-xxx",
  "object": "chat.completion",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "[Verse]\n...\n[Chorus]\n...",
        "audio": {
          "data": "<base64-encoded-mp3>",
          "mime_type": "audio/mpeg"
        }
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 14,
    "completion_tokens": 3199,
    "total_tokens": 3213
  }
}

5. OpenAI Compatibility — chat/completions (compatibility mode)

Request URL

POST https://genaiapi-m2.cloudsway.net/v1/music/chat/completions

The URL does not contain the endpointPath.

Request Parameters

Field	Type	Position	Required	Description
body	object	body	is	OpenAI Chat Completions Request Body

Request Body Fields

Field	Type	Required	Description
model	string	is	Model name, such as MaaS_Lyria_3_pro_preview
messages	array	is	Conversation Message List
messages[].role	string	is	Message role, such as user
messages[].content	string	is	Music description prompt
stream	boolean	No	Streaming support; Lyria does not support streaming
modalities	array	No	Output modes, such as ["audio", "text"]

Response Parameters

Field	Type	Description
id	string	Response ID
object	string	Object type, such as chat.completion
choices	array	Generated Results
choices[].index	integer	Result Index
choices[].message	object	Assistant Message
choices[].message.role	string	As assistant
choices[].message.content	string	Lyric Text
choices[].message.audio	object	Audio Data
choices[].message.audio.data	string	Audio base64
choices[].message.audio.mime_type	string	如 audio/mpeg
choices[].finish_reason	string	End reason, e.g., stop
usage	object	Token Usage
usage.prompt_tokens	integer	Number of input tokens
usage.completion_tokens	integer	Number of output tokens
usage.total_tokens	integer	Total number of tokens

Request Example A (Explicitly Specify Stream and Modalities)

curl --request POST \
  --url 'https://genaiapi-m2.cloudsway.net/v1/music/chat/completions' \
  --header 'Authorization: Bearer {your AK}' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "MaaS_Lyria_3_pro_preview",
    "stream": false,
    "messages": [
      {
        "role": "user",
        "content": "Upbeat pop song about a summer road trip, catchy chorus, female vocal"
      }
    ],
    "modalities": ["audio", "text"]
  }'

Request Example B (Minimum Parameters)

curl --request POST \
  --url 'https://genaiapi-m2.cloudsway.net/v1/music/chat/completions' \
  --header 'Authorization: Bearer {your AK}' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "MaaS_Lyria_3_pro_preview",
    "messages": [
      {
        "role": "user",
        "content": "Calm piano instrumental for studying, 90 BPM"
      }
    ]
  }'

Response Example

{
  "id": "chatcmpl-xxx",
  "object": "chat.completion",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "[Verse]\n...\n[Chorus]\n...",
        "audio": {
          "data": "<base64-encoded-mp3>",
          "mime_type": "audio/mpeg"
        }
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 14,
    "completion_tokens": 3199,
    "total_tokens": 3213
  }
}