> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gravitex.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Lyria 3 Pro Preview

> Google Lyria 3 音乐生成，输出完整歌曲音频

## 简介

`lyria-3-pro-preview` 用于生成完整音乐，适合主歌、副歌、桥段等较完整的歌曲结构，输出为音频。

Gravitex 对外提供 Google Interactions 风格接口：

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

官方参考：

* [Google Lyria 3 音乐生成](https://ai.google.dev/gemini-api/docs/music-generation)

## 认证

<ParamField header="Authorization" type="string" required>
  Bearer Token，如 `Bearer sk-xxxxxxxxxxxxxxxx`
</ParamField>

<ParamField header="X-API-Key" type="string">
  也可使用 `X-API-Key: sk-xxxxxxxxxxxxxxxx`
</ParamField>

## 提交生成请求

**POST** `/v1beta/interactions`

根据是否传入 `background`，分为同步和异步两种模式。

### 同步生成（默认）

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

```bash theme={null}
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
  }'
```

成功响应：

```json theme={null}
{
  "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，之后需通过[查询任务结果](#查询任务结果)接口轮询。

```bash theme={null}
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
  }'
```

提交响应：

```json theme={null}
{
  "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`、日志和计费。客户端只需轮询本接口获取最终结果。

### 请求示例

```bash theme={null}
curl 'https://api.gravitex.ai/v1beta/interactions/task_xxxxxxxxx' \
  -H 'Authorization: Bearer sk-xxxxxxxxxxxxxxxx'
```

### 处理中（in\_progress）

```json theme={null}
{
  "id": "task_xxxxxxxxx",
  "object": "interaction",
  "role": "model",
  "model": "lyria-3-pro-preview",
  "status": "in_progress"
}
```

### 已完成（completed）

```json theme={null}
{
  "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）

```json theme={null}
{
  "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."
  }
}
```

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

## 参数说明

<ParamField body="model" type="string" required>
  固定为 `lyria-3-pro-preview`
</ParamField>

<ParamField body="input" type="string" required>
  音乐描述、编曲要求或歌词。Google 风格使用字符串
</ParamField>

<ParamField body="background" type="boolean">
  `true` 使用 Gravitex 本地异步任务；默认同步
</ParamField>

<ParamField body="store" type="boolean">
  与 Google Interactions 请求兼容。异步请求建议传 `true`
</ParamField>

<ParamField body="response_format" type="object">
  音频响应格式配置，传入 `{"type": "audio"}`；以当前渠道模型配置为准
</ParamField>

<ParamField body="previous_interaction_id" type="string">
  多轮 Interaction 关联 ID；Lyria 3 当前建议单次生成使用
</ParamField>

### 输入建议

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

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

示例：

```text theme={null}
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 参数错误：

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

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

## 音频处理示例

```javascript theme={null}
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);
}
```

## 注意事项

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