Lyria 3 Pro Preview

简介

lyria-3-pro-preview 用于生成完整音乐，适合主歌、副歌、桥段等较完整的歌曲结构，输出为音频。 Gravitex 对外提供 Google Interactions 风格接口：

接口	方法	说明
提交生成请求	`POST /v1beta/interactions`	同步或异步提交音乐生成任务
查询任务结果	`GET /v1beta/interactions/{interaction_id}`	轮询异步任务状态与结果

官方参考：

Google Lyria 3 音乐生成

认证

string

必填

Bearer Token，如 Bearer sk-xxxxxxxxxxxxxxxx

string

也可使用 X-API-Key: sk-xxxxxxxxxxxxxxxx

提交生成请求

POST /v1beta/interactions 根据是否传入 background，分为同步和异步两种模式。

同步生成（默认）

当请求不传 background，或显式传入 background: false 时，网关等待上游生成完成后返回结果，不写入异步任务表。

curl -X POST 'https://api.gravitex.ai/v1beta/interactions' \
  -H 'Authorization: Bearer sk-xxxxxxxxxxxxxxxx' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "lyria-3-pro-preview",
    "input": "Create a warm cinematic country song with acoustic guitar, gentle drums, a memorable chorus, and a calm journey-home atmosphere. Instrumental only.",
    "background": false,
    "store": false
  }'

成功响应：

{
  "id": "interaction_xxxxxxxxx",
  "object": "interaction",
  "role": "model",
  "model": "lyria-3-pro-preview",
  "status": "completed",
  "output_audio": {
    "data": "<base64-audio>",
    "mime_type": "audio/mpeg"
  },
  "output_text": "<generated lyrics or structure>"
}

output_audio.data 是 Base64 音频数据。mime_type 通常为 audio/mpeg。

异步生成

传入 background: true 时，Gravitex 在本地创建异步任务并立即返回任务 ID，之后需通过查询任务结果接口轮询。

curl -X POST 'https://api.gravitex.ai/v1beta/interactions' \
  -H 'Authorization: Bearer sk-xxxxxxxxxxxxxxxx' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "lyria-3-pro-preview",
    "input": "Create an instrumental country music track with acoustic guitar, birdsong, and soft summer insect ambience. No lyrics, no artist imitation, and no copyrighted melody.",
    "background": true,
    "store": true
  }'

提交响应：

{
  "id": "task_xxxxxxxxx",
  "object": "interaction",
  "role": "model",
  "model": "lyria-3-pro-preview",
  "status": "in_progress"
}

返回的 task_xxx ID 用于后续查询。

查询任务结果

GET /v1beta/interactions/{interaction_id} 异步任务由 Gravitex worker 负责调用上游服务，上游生成完成后更新 tasks、日志和计费。客户端只需轮询本接口获取最终结果。

请求示例

curl 'https://api.gravitex.ai/v1beta/interactions/task_xxxxxxxxx' \
  -H 'Authorization: Bearer sk-xxxxxxxxxxxxxxxx'

处理中（in_progress）

{
  "id": "task_xxxxxxxxx",
  "object": "interaction",
  "role": "model",
  "model": "lyria-3-pro-preview",
  "status": "in_progress"
}

已完成（completed）

{
  "id": "task_xxxxxxxxx",
  "object": "interaction",
  "role": "model",
  "model": "lyria-3-pro-preview",
  "status": "completed",
  "output_audio": {
    "data": "<base64-audio>",
    "mime_type": "audio/mpeg"
  },
  "output_text": "<generated lyrics or structure>"
}

失败（failed）

{
  "id": "task_xxxxxxxxx",
  "object": "interaction",
  "role": "model",
  "model": "lyria-3-pro-preview",
  "status": "failed",
  "error": {
    "code": "content_blocked",
    "message": "Request blocked for an unspecified policy reason. Please modify your input and retry."
  }
}

建议轮询间隔为 2～5 秒，并在 completed、failed、cancelled 时停止。

参数说明

string

必填

固定为 lyria-3-pro-preview

string

必填

音乐描述、编曲要求或歌词。Google 风格使用字符串

boolean

true 使用 Gravitex 本地异步任务；默认同步

boolean

与 Google Interactions 请求兼容。异步请求建议传 true

object

音频响应格式配置，传入 {"type": "audio"}；以当前渠道模型配置为准

string

多轮 Interaction 关联 ID；Lyria 3 当前建议单次生成使用

输入建议

建议在 prompt 中明确以下内容：

音乐类型：country、pop、jazz、cinematic 等
乐器：acoustic guitar、piano、drums 等
情绪：warm、dreamy、energetic 等
速度和调性：例如 90 BPM、G major
是否需要人声或歌词
歌曲结构：[Intro]、[Verse]、[Chorus]、[Bridge]
时长要求：Pro 模型可在 prompt 中描述目标时长

示例：

Create a 2-minute warm cinematic country song at 90 BPM in G major, with acoustic guitar, pedal steel, soft drums, verse, chorus, and bridge. Add gentle birdsong and summer evening ambience. Instrumental only.

状态与错误码

HTTP 状态	code	含义
`200`	-	请求已接受、处理中或生成成功；异步请求通过 `status` 判断最终状态
`400`	`invalid_request` / `invalid_argument`	请求格式或上游参数不合法
`401`	`unauthenticated`	API Key 无效或缺失
`403`	`permission_denied` / `content_blocked`	权限不足、分组无权限或内容安全策略拦截
`404`	`not_found`	模型、渠道或任务不存在
`429`	`resource_exhausted`	额度、速率或上游配额不足
`500`	`internal`	网关或上游内部错误
`502`	`bad_gateway`	上游响应异常或无法解析
`503`	`unavailable`	上游服务暂不可用
`504`	`deadline_exceeded`	上游请求超时

内容安全拦截

以下错误表示 prompt 被 Google 安全过滤器拦截，不是 JSON 参数错误：

{
  "error": {
    "code": "content_blocked",
    "message": "Request blocked for an unspecified policy reason. Please modify your input and retry."
  }
}

不要对完全相同的 prompt 无限重试，应修改 prompt，避免指定艺人声音、受版权保护歌词或受限制内容。

音频处理示例

const response = await fetch('https://api.gravitex.ai/v1beta/interactions/task_xxxxxxxxx', {
  headers: {
    Authorization: 'Bearer sk-xxxxxxxxxxxxxxxx'
  }
});

const interaction = await response.json();

if (interaction.status === 'completed') {
  const audioBase64 = interaction.output_audio?.data;
  const mimeType = interaction.output_audio?.mime_type || 'audio/mpeg';
  console.log(mimeType, audioBase64);
}

if (interaction.status === 'failed') {
  console.error(interaction.error?.code, interaction.error?.message);
}

注意事项

lyria-3-pro-preview 输出为音乐音频，不是文本聊天结果。
不要把 top_p、temperature 等通用文本模型参数强行传给 Lyria，具体可用参数以渠道配置和官方模型文档为准。
异步请求必须使用返回的 Gravitex task_xxx ID 轮询。
生成音频包含 Google 的音频水印机制，具体以官方模型政策为准。

API 文档

对话与文本

安全与音频

图像系列

视频系列

文本补全和向量嵌入

接口模块

简介

认证

提交生成请求

同步生成（默认）

异步生成

查询任务结果

请求示例

处理中（in_progress）

已完成（completed）

失败（failed）

参数说明

输入建议

状态与错误码

内容安全拦截

音频处理示例

注意事项

​简介

​认证

​提交生成请求

​同步生成（默认）

​异步生成

​查询任务结果

​请求示例

​处理中（in_progress）

​已完成（completed）

​失败（failed）

​参数说明

​输入建议

​状态与错误码

​内容安全拦截

​音频处理示例

​注意事项

简介

认证

提交生成请求

同步生成（默认）

异步生成

查询任务结果

请求示例

处理中（in_progress）

已完成（completed）

失败（failed）

参数说明

输入建议

状态与错误码

内容安全拦截

音频处理示例

注意事项