Music Generation API 接口文档

版本: v1.0.0 | 更新日期: 2026-06-18 | 模型: lyria-3-pro-preview | 状态: Preview
本文档基于线上实测请求/响应编写，所有字段名、类型、取值均与实际 API 返回严格一致。

1. 概述

通过 Gemini 兼容接口 (generateContent) 调用 Google DeepMind Lyria 系列模型，实现高保真 AI 音乐生成。

能力	说明
Text-to-Music	基于自然语言描述生成完整歌曲
Full-length Song	单次生成最长约 150 秒的完整乐曲
Vocal + Instrumental	支持人声演唱与多轨乐器编排
Auto Lyrics	自动生成带精确时间戳的歌词与段落结构标注
Music Analysis	返回 BPM、时长、段落配器分析等元数据
MP3 Output	输出为标准 MP3 格式 (`audio/mpeg`)，可直接播放

协议兼容性：请求/响应格式与 Google Gemini API generateContent 接口一致。

2. 认证

所有请求须在 HTTP Header 中携带 API Key：

Authorization: Bearer YOUR_API_KEY

必需请求头：

Header	值	必填
`Authorization`	`Bearer <API_KEY>`	是
`Content-Type`	`application/json`	是

安全提示：API Key 为敏感凭证，请勿在客户端代码、公开仓库或日志中暴露。建议通过环境变量或密钥管理服务注入。

3. 可用模型

Model ID	说明	输出格式	最大时长	状态
`lyria-3-pro-preview`	Google DeepMind 旗舰音乐生成模型。支持高保真全曲创作，含人声演唱、多轨乐器编排、自动歌词生成与乐曲结构分析。	`audio/mpeg` (MP3)	~150 秒	Preview

4. 生成内容

4.1 接口地址

POST https://platform.dataeyes.ai/v1/models/{model_id}:generateContent

路径参数：

参数	类型	说明
`model_id`	`string`	模型标识符，当前可用值：`lyria-3-pro-preview`

4.2 请求体 (Request Body)

参数说明

参数	类型	必填	说明
`contents`	`array<object>`	是	会话内容数组。
`contents[].parts`	`array<object>`	是	内容分块数组，至少包含一个 `text` 分块。
`contents[].parts[].text`	`string`	是	生成指令 (prompt)。用自然语言描述期望的音乐风格、乐器、情绪、节奏、演唱方式等。
`generationConfig`	`object`	否	生成配置。
`generationConfig.responseModalities`	`array<string>`	是	响应模态列表。音乐生成必须包含 `"AUDIO"`；推荐同时传 `"TEXT"` 以获取歌词与分析。可选值：`"AUDIO"`、`"TEXT"`。

完整 Schema

{
  "contents": [
    {
      "parts": [
        {
          "text": "<音乐生成 prompt>"
        }
      ]
    }
  ],
  "generationConfig": {
    "responseModalities": ["AUDIO", "TEXT"]
  }
}

4.3 响应体 (Response Body)

成功时返回 HTTP 200。

顶层字段

字段	类型	说明
`candidates`	`array<object>`	候选结果数组。当前固定返回 1 个候选项。
`usageMetadata`	`object`	Token 用量统计。
`modelVersion`	`string`	实际使用的模型版本，如 `"lyria-3-pro-preview"`。
`createTime`	`string` (ISO 8601)	响应创建时间，如 `"2026-06-18T11:59:11.049072Z"`。
`responseId`	`string`	本次响应的唯一标识符，可用于问题排查与日志追踪。

candidates[] 结构

字段	类型	说明
`content.role`	`string`	固定值 `"model"`。
`content.parts`	`array<object>`	内容分块数组，见下方详细说明。
`finishReason`	`string`	生成终止原因。

finishReason 取值：

值	含义
`STOP`	正常完成，输出完整。
`MAX_TOKENS`	达到 token 上限，输出可能被截断。
`SAFETY`	触发内容安全策略，请求被拦截。

content.parts[] 详细说明

音乐生成响应固定包含 3 个 part（基于实测验证）：

序号	类型	字段	说明	实测示例
Part 0	文本	`text`	歌词：含段落标识 `[[X0]]` 和精确时间戳 `[sec:]`，详见 4.4 歌词格式规范	1,497 字符
Part 1	文本	`text`	乐曲分析：BPM、时长、质量评分及逐段落配器/声乐/情绪分析，详见 4.5 乐曲分析元数据	7,263 字符
Part 2	二进制	`inlineData`	音频文件：Base64 编码的 MP3 数据	3.39 MB (解码后)

inlineData 对象

字段	类型	说明
`mimeType`	`string`	MIME 类型，固定为 `"audio/mpeg"`。
`data`	`string`	Base64 编码的音频数据。解码后为标准 MP3 文件。

usageMetadata 对象

字段	类型	说明
`promptTokenCount`	`integer`	输入消耗的 token 数。
`candidatesTokenCount`	`integer`	生成内容消耗的 token 数（含音频 token）。
`totalTokenCount`	`integer`	总计 = `promptTokenCount` + `candidatesTokenCount`。
`trafficType`	`string`	流量类型，如 `"ON_DEMAND"`。
`promptTokensDetails`	`array<object>`	输入 token 按模态明细。每项含 `modality`（如 `"TEXT"`）和 `tokenCount`。
`candidatesTokensDetails`	`array<object>`	输出 token 按模态明细。每项含 `modality`（如 `"AUDIO"`）和 `tokenCount`。

实测响应示例

以下为 2026-06-18 实测响应（音频数据已截断）：

{
  "candidates": [
    {
      "content": {
        "role": "model",
        "parts": [
          {
            "text": "[[A0]]\n[[B1]]\n[10.9:] The kettle's singing in the morning light,\n[:] Dusting off the shadows of the night.\n[:] My boots are heavy but my heart is high,\n[:] Matching every color in the eastern sky.\n..."
          },
          {
            "text": "mosic: 4.5\nbpm: 110.0\nduration_secs: 150.5\ngood_crop: 1.0\n[[A0]]\n[0.0:] A bright and inviting Acoustic Folk intro defined by its rhythmic clarity..."
          },
          {
            "inlineData": {
              "mimeType": "audio/mpeg",
              "data": "<Base64 编码，解码后 3,554,545 字节 / 3.39 MB>"
            }
          }
        ]
      },
      "finishReason": "STOP"
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 13,
    "candidatesTokenCount": 3199,
    "totalTokenCount": 3212,
    "trafficType": "ON_DEMAND",
    "promptTokensDetails": [
      { "modality": "TEXT", "tokenCount": 13 }
    ],
    "candidatesTokensDetails": [
      { "modality": "AUDIO", "tokenCount": 3199 }
    ]
  },
  "modelVersion": "lyria-3-pro-preview",
  "createTime": "2026-06-18T11:59:11.049072Z",
  "responseId": "j90zarD_Asaa9LsP5t7F8QU"
}

4.4 歌词格式规范

Part 0 的 text 字段采用结构化标注格式，包含段落标识符和时间戳两类标记。

段落标识符 `[[LetterNumber]]`

字母表示段落功能类型，数字为该段落在整曲中的出场序号（从 0 起）。

字母	类型	说明	实测出现
`A`	Intro / Interlude / Solo	器乐段落（前奏、间奏、独奏），无人声	`[[A0]]`, `[[A5]]`
`B`	Verse	主歌段落，叙事性演唱	`[[B1]]`, `[[B3]]`
`C`	Chorus	副歌段落，旋律重复、能量最高	`[[C2]]`, `[[C4]]`, `[[C6]]`
`D`	Outro	尾声段落，渐弱收束	`[[D7]]`

注意：A 类型并非仅指"前奏"。实测中 [[A0]] 为前奏，[[A5]] 为曲中口琴独奏间奏。字母指示的是功能角色（器乐/无人声），而非固定位置。

时间戳格式

标记	含义	示例
`[秒数:]`	该行歌词的绝对起始时间（秒）	`[10.9:]` = 第 10.9 秒
`[:]`	紧跟上一行，无独立时间标记	—

实测歌词结构示例

[[A0]]                          ← 前奏（纯器乐，无歌词行）
[[B1]]                          ← 主歌 1
[10.9:] The kettle's singing    ← 10.9 秒起
[:] in the morning light,       ← 紧接
[:] Dusting off the shadows...
[[C2]]                          ← 副歌
[37.1:] Oh, let the good...    ← 37.1 秒起
[[B3]]                          ← 主歌 2
[54.6:] I met a friend...      ← 54.6 秒起
[[C4]]                          ← 副歌（重复）
[80.8:] Oh, let the good...
[[A5]]                          ← 间奏/口琴独奏（纯器乐）
[[C6]]                          ← 副歌（最终）
[111.3:] Oh, let the good...
[[D7]]                          ← 尾声
[128.8:] The luckiest man...

4.5 乐曲分析元数据

Part 1 的 text 字段为模型自动生成的乐曲分析，采用 key-value 头部 + 逐段落描述 的结构。

全局指标（头部 4 行）

字段	类型	说明	实测值
`mosic`	`float`	音乐质量评分 (Music Quality Score)，模型自评，范围 0~5	`4.5`
`bpm`	`float`	节拍速度 (Beats Per Minute)	`110.0`
`duration_secs`	`float`	音频总时长（秒）	`150.5`
`good_crop`	`float`	可用裁剪比例，`1.0` 表示全曲可用	`1.0`

注意：字段名 mosic 是 API 实际返回值（非 music 的拼写错误），代码中应按原样解析。

逐段落描述

头部之后，每个段落标识符（如 [[A0]]）后跟该段的详细音乐学分析，包含：

分析维度	说明	示例摘录
配器 (Instrumentation)	使用的乐器及演奏方式	"steel-string acoustic guitar playing a steady, rhythmic strumming pattern"
节奏型 (Rhythm)	节拍模式与律动特征	"rhythmic hand-clapping on the two and four beats"
声乐特征 (Vocals)	声线类型、音域、演唱风格	"male tenor with a warm, crystalline, and slightly raspy timbre"
情绪/氛围 (Mood)	段落的情感基调	"jubilant atmosphere of collective celebration"
音乐参考 (Reference)	类似的音乐风格或场景联想	"reminiscent of traveling singer-songwriters"

每个段落描述还附带时间戳 [sec:]，标注该段落在音频中的起始时间。

5. 完整示例

5.1 cURL

提示：音乐生成耗时较长（30~120 秒），如使用 curl 建议添加 --max-time 180 防止超时。

5.2 Python

5.3 Node.js

6. 错误码

HTTP 状态码	错误码	说明	处理建议
`400`	`INVALID_ARGUMENT`	请求参数无效。缺少 `contents`、`parts` 格式错误，或 `responseModalities` 未包含 `"AUDIO"`。	检查 JSON 结构完整性，对照 4.2 请求体中的 Schema。
`401`	`UNAUTHENTICATED`	API Key 缺失、格式错误或已失效。	确认 Header 格式为 `Authorization: Bearer <key>`，检查 Key 是否过期或被撤销。
`403`	`PERMISSION_DENIED`	当前 Key 无权访问指定模型。	确认账户已开通音乐生成权限，或联系管理员调整模型授权。
`429`	`RESOURCE_EXHAUSTED`	请求频率超限或 token 配额不足。	降低请求频率；查看响应头中的限流信息；必要时升级订阅计划。
`500`	`INTERNAL`	服务端内部错误。	使用指数退避重试（见 7. 速率限制）。若持续出现，携带 `responseId` 联系技术支持。
`503`	`UNAVAILABLE`	服务暂时不可用或过载。	使用指数退避重试。

7. 速率限制

音乐生成为计算密集型任务，受以下维度约束（具体限额取决于订阅计划）：

指标	说明
RPM (Requests Per Minute)	每分钟最大请求数，超限返回 `429`。
TPM (Tokens Per Minute)	每分钟最大 token 消耗量，音频输出按 AUDIO token 计量。
并发数 (Concurrent Requests)	最大同时处理的请求数。单次生成耗时 30~120 秒，需合理控制并发。

重试策略

遇到 429 或 503 时，建议使用 指数退避 + 随机抖动 (Exponential Backoff with Jitter)：

wait = min(base * 2^attempt + random(0, 1), max_wait)

参数	推荐值
`base` (初始等待)	1 秒
`max_wait` (最大等待)	32 秒
`max_attempts` (最大重试次数)	5 次

8. 最佳实践

8.1 Prompt 编写

具体化：明确指定风格 (acoustic folk, electronic, jazz)、乐器 (guitar, piano, drums)、情绪 (cheerful, melancholic, energetic)。

演唱指定：可指定声线类型与风格（如 "male tenor vocal", "female soprano, breathy tone"）。

避免模糊："make a song" 远不如 "Create a melancholic jazz ballad with piano and saxophone, slow tempo, female vocal" 效果好。

8.2 音频处理

响应中音频为 Base64 编码的 MP3，需 Base64 解码后写入 .mp3 文件。

实测单曲约 3~5 MB（解码后），请确保客户端内存足够处理完整响应体。

HTTP 超时务必设置为 至少 120 秒，推荐 180 秒。音乐生成需要较长的模型推理时间。

8.3 响应解析

按 part 类型 (text / inlineData) 分别处理，不要硬编码 parts 数组的索引或长度——未来模型版本可能调整 part 数量。

始终检查 finishReason，仅 "STOP" 表示输出完整。

8.4 成本优化

通过 usageMetadata 跟踪 token 消耗，AUDIO 模态的 candidatesTokenCount 为主要成本项。

生产环境建议对相同 prompt 做去重/缓存，避免重复生成。

开发测试阶段使用简短 prompt 降低成本。

9. 变更记录

日期	版本	变更内容
2026-06-18	v1.0.0	初始发布。支持 `lyria-3-pro-preview` 模型。

本文档基于 2026-06-18 线上实测编写。测试 Prompt: "Create a cheerful acoustic folk song with guitar and harmonica, bright mood"。实测响应: promptTokenCount=13, candidatesTokenCount=3199, totalTokenCount=3212, 音频 3.39 MB, 时长 150.5 秒。

Google DeepMind Lyria API文档

Music Generation API 接口文档

目录

1. 概述

2. 认证

3. 可用模型

4. 生成内容

4.1 接口地址

4.2 请求体 (Request Body)

参数说明

完整 Schema

4.3 响应体 (Response Body)

顶层字段

candidates[] 结构

content.parts[] 详细说明

inlineData 对象

usageMetadata 对象

实测响应示例

4.4 歌词格式规范

段落标识符 `[[LetterNumber]]`

时间戳格式

实测歌词结构示例

4.5 乐曲分析元数据

全局指标（头部 4 行）

逐段落描述

5. 完整示例

5.1 cURL

5.2 Python

5.3 Node.js

6. 错误码

7. 速率限制

重试策略

8. 最佳实践

8.1 Prompt 编写

8.2 音频处理

8.3 响应解析

8.4 成本优化

9. 变更记录

Google DeepMind Lyria API文档

Music Generation API 接口文档#

目录#

1. 概述#

2. 认证#

3. 可用模型#

4. 生成内容#

4.1 接口地址#

4.2 请求体 (Request Body)#

参数说明#

完整 Schema#

4.3 响应体 (Response Body)#

顶层字段#

candidates[] 结构#

content.parts[] 详细说明#

inlineData 对象#

usageMetadata 对象#

实测响应示例#

4.4 歌词格式规范#

段落标识符 [[LetterNumber]]#

时间戳格式#

实测歌词结构示例#

4.5 乐曲分析元数据#

全局指标（头部 4 行）#

逐段落描述#

5. 完整示例#

5.1 cURL#

5.2 Python#

5.3 Node.js#

6. 错误码#

7. 速率限制#

重试策略#

8. 最佳实践#

8.1 Prompt 编写#

8.2 音频处理#

8.3 响应解析#

8.4 成本优化#

9. 变更记录#

Music Generation API 接口文档

目录

1. 概述

2. 认证

3. 可用模型

4. 生成内容

4.1 接口地址

4.2 请求体 (Request Body)

参数说明

完整 Schema

4.3 响应体 (Response Body)

顶层字段

candidates[] 结构

content.parts[] 详细说明

inlineData 对象

usageMetadata 对象

实测响应示例

4.4 歌词格式规范

段落标识符 `[[LetterNumber]]`

时间戳格式

实测歌词结构示例

4.5 乐曲分析元数据

全局指标（头部 4 行）

逐段落描述

5. 完整示例

5.1 cURL

5.2 Python

5.3 Node.js

6. 错误码

7. 速率限制

重试策略

8. 最佳实践

8.1 Prompt 编写

8.2 音频处理

8.3 响应解析

8.4 成本优化

9. 变更记录