跳转至

MaaS_Lyria

使用指南

推荐按以下流程调用 Lyria 音乐生成接口：

  1. 选择调用方式

  2. Vertex 原生：generateContent 或 v1beta1 路径，请求体遵循 Google Vertex AI generateContent 结构。

  3. OpenAI 兼容：chat/completions 系列路径，请求体为 OpenAI Chat Completions 格式。

  4. 发送请求并等待完整响应 Lyria 为同步接口，一次 POST 返回完整结果（歌词文本 + 音频 base64），无任务轮询。生成耗时通常较长，建议 HTTP 读超时 ≥ 120s。不支持流式（stream: true）。

  5. 获取音频

  6. generateContent：从 candidates[].content.parts[].inlineData 读取，mimeType 如 audio/mpeg，data 为 base64 编码音频。

  7. chat/completions：从 choices[0].message.audio.data 读取 base64 音频

通用请求头

Header 必填 说明
Authorization 是 Bearer
Content-Type 是（POST） application/json

1. 文生音乐 — generateContent（标准路径）

请求 URL

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

请求参数

字段 类型 位置 必填 说明
endpointPath string path 是 端点路径
body object body 是 Vertex generateContent 请求体

请求体字段

字段 类型 必填 说明
contents array 是 输入内容列表
contents[].role string 否 内容角色，如 user
contents[].parts array 是 内容片段列表
contents[].parts[].text string 是 音乐描述 / 风格 / 主题 prompt
generationConfig object 否 生成配置
generationConfig.responseModalities array 否 期望输出模态，如 ["AUDIO","TEXT"]

响应参数

字段 类型 说明
candidates array 模型输出候选
candidates[].content object 生成内容
candidates[].content.role string 如 model
candidates[].content.parts array 输出片段
candidates[].content.parts[].text string 歌词 / 结构文本
candidates[].content.parts[].inlineData object 内联二进制数据
candidates[].content.parts[].inlineData.mimeType string 如 audio/mpeg
candidates[].content.parts[].inlineData.data string 音频 base64
candidates[].finishReason string 结束原因，如 STOP
usageMetadata object Token 用量
usageMetadata.promptTokenCount integer 输入 token 数
usageMetadata.candidatesTokenCount integer 输出 token 数
usageMetadata.totalTokenCount integer 总 token 数
usageMetadata.promptTokensDetails array 输入 token 模态明细
usageMetadata.promptTokensDetails[].modality string 如 TEXT
usageMetadata.promptTokensDetails[].tokenCount integer token 数
usageMetadata.candidatesTokensDetails array 输出 token 模态明细
usageMetadata.candidatesTokensDetails[].modality string 如 AUDIO
usageMetadata.candidatesTokensDetails[].tokenCount integer token 数
responseId string 响应 ID

请求示例 A（显式指定 role 与 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"]
    }
  }'

请求示例 B（仅传 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"
          }
        ]
      }
    ]
  }'

响应示例

{
  "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. 文生音乐 — generateContent（原生 v1beta1）

请求 URL

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

请求参数

字段 类型 位置 必填 说明
endpointPath string path 是 端点路径
modelName string path 是 模型名，如 lyria-3-pro-preview
body object body 是 Vertex generateContent 请求体

请求体字段

字段 类型 必填 说明
contents array 是 输入内容列表
contents[].role string 否 内容角色，如 user
contents[].parts array 是 内容片段列表
contents[].parts[].text string 是 音乐描述 / 风格 / 主题 prompt
generationConfig object 否 生成配置
generationConfig.responseModalities array 否 期望输出模态，如 ["AUDIO","TEXT"]

响应参数

字段 类型 说明
candidates array 模型输出候选
candidates[].content object 生成内容
candidates[].content.role string 如 model
candidates[].content.parts array 输出片段
candidates[].content.parts[].text string 歌词 / 结构文本
candidates[].content.parts[].inlineData object 内联二进制数据
candidates[].content.parts[].inlineData.mimeType string 如 audio/mpeg
candidates[].content.parts[].inlineData.data string 音频 base64
candidates[].finishReason string 结束原因，如 STOP
usageMetadata object Token 用量
usageMetadata.promptTokenCount integer 输入 token 数
usageMetadata.candidatesTokenCount integer 输出 token 数
usageMetadata.totalTokenCount integer 总 token 数
usageMetadata.promptTokensDetails array 输入 token 模态明细
usageMetadata.promptTokensDetails[].modality string 如 TEXT
usageMetadata.promptTokensDetails[].tokenCount integer token 数
usageMetadata.candidatesTokensDetails array 输出 token 模态明细
usageMetadata.candidatesTokensDetails[].modality string 如 AUDIO
usageMetadata.candidatesTokensDetails[].tokenCount integer token 数
responseId string 响应 ID

请求示例 A（显式指定 role 与 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"]
    }
  }'

请求示例 B（仅传 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"
          }
        ]
      }
    ]
  }'

响应示例

{
  "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

请求 URL

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

请求参数

字段 类型 位置 必填 说明
endpointPath string path 是 端点路径
body object body 是 OpenAI Chat Completions 请求体

请求体字段

字段 类型 必填 说明
model string 是 模型名，如 lyria-3-pro-preview
messages array 是 对话消息列表
messages[].role string 是 消息角色，如 user
messages[].content string 是 音乐描述 prompt
stream boolean 否 是否流式；Lyria 不支持流式
modalities array 否 输出模态，如 ["audio","text"]

响应参数

字段 类型 说明
id string 响应 ID
object string 对象类型，如 chat.completion
choices array 生成结果
choices[].index integer 结果索引
choices[].message object 助手消息
choices[].message.role string 如 assistant
choices[].message.content string 歌词文本
choices[].message.audio object 音频数据
choices[].message.audio.data string 音频 base64
choices[].message.audio.mime_type string 如 audio/mpeg
choices[].finish_reason string 结束原因，如 stop
usage object Token 用量
usage.prompt_tokens integer 输入 token 数
usage.completion_tokens integer 输出 token 数
usage.total_tokens integer 总 token 数

请求示例 A（显式指定 stream 与 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"]
  }'

请求示例 B（最简参数）

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"
      }
    ]
  }'

响应示例

{
  "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 兼容 — chat/completions（端点路径模式）

请求 URL

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

请求参数

字段 类型 位置 必填 说明
endpointPath string path 是 端点路径
body object body 是 OpenAI Chat Completions 请求体

请求体字段

字段 类型 必填 说明
model string 是 模型名，如 lyria-3-pro-preview
messages array 是 对话消息列表
messages[].role string 是 消息角色，如 user
messages[].content string 是 音乐描述 prompt
stream boolean 否 是否流式；Lyria 不支持流式
modalities array 否 输出模态，如 ["audio","text"]

响应参数

字段 类型 说明
id string 响应 ID
object string 对象类型，如 chat.completion
choices array 生成结果
choices[].index integer 结果索引
choices[].message object 助手消息
choices[].message.role string 如 assistant
choices[].message.content string 歌词文本
choices[].message.audio object 音频数据
choices[].message.audio.data string 音频 base64
choices[].message.audio.mime_type string 如 audio/mpeg
choices[].finish_reason string 结束原因，如 stop
usage object Token 用量
usage.prompt_tokens integer 输入 token 数
usage.completion_tokens integer 输出 token 数
usage.total_tokens integer 总 token 数

请求示例 A（显式指定 stream 与 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"]
  }'

请求示例 B（最简参数）

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"
      }
    ]
  }'

响应示例

{
  "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 兼容 — chat/completions（兼容模式）

请求 URL

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

URL 不含 endpointPath。

请求参数

字段 类型 位置 必填 说明
body object body 是 OpenAI Chat Completions 请求体

请求体字段

字段 类型 必填 说明
model string 是 模型名，如 MaaS_Lyria_3_pro_preview
messages array 是 对话消息列表
messages[].role string 是 消息角色，如 user
messages[].content string 是 音乐描述 prompt
stream boolean 否 是否流式；Lyria 不支持流式
modalities array 否 输出模态，如 ["audio","text"]

响应参数

字段 类型 说明
id string 响应 ID
object string 对象类型，如 chat.completion
choices array 生成结果
choices[].index integer 结果索引
choices[].message object 助手消息
choices[].message.role string 如 assistant
choices[].message.content string 歌词文本
choices[].message.audio object 音频数据
choices[].message.audio.data string 音频 base64
choices[].message.audio.mime_type string 如 audio/mpeg
choices[].finish_reason string 结束原因，如 stop
usage object Token 用量
usage.prompt_tokens integer 输入 token 数
usage.completion_tokens integer 输出 token 数
usage.total_tokens integer 总 token 数

请求示例 A（显式指定 stream 与 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"]
  }'

请求示例 B（最简参数）

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"
      }
    ]
  }'

响应示例

{
  "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
  }
}