Lyria API

本文档说明 Exchange Token 对 Lyria 系列模型提供的网关入口。

1. 概述

Exchange Token 以兼容 Gemini Interactions API 的格式提供 Lyria 系列模型。

当前范围：

支持模型：lyria-3-clip-preview、lyria-3-pro-preview
支持非流式和 SSE 流式
方法：POST
地址：https://api.exchangetoken.ai/v1beta/interactions

2. 鉴权方式

推荐请求头：

http

x-goog-api-key: YOUR_GATEWAY_API_KEY

3. Request

下游请求体应尽量贴近 Interactions create schema。

字段	类型	必填	说明
`model`	string	是	用于生成 interaction 的模型名称，例如 `lyria-3-clip-preview`
`input`	string、content object 或 content array	是	interaction 的主输入内容，可以是纯文本，也可以是结构化多模态内容
`stream`	boolean	否	是否以 server-sent events 流式返回输出
`system_instruction`	string	否	用于控制模型整体行为的高层系统提示

非流式请求示例：

bash

curl "https://api.exchangetoken.ai/v1beta/interactions" \
  -H "x-goog-api-key: $YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{
    "model": "lyria-3-pro-preview",
    "input": "Create a cinematic electronic track with warm analog synths and a slow emotional build."
  }'

流式请求示例：

bash

curl "https://api.exchangetoken.ai/v1beta/interactions" \
  -H "x-goog-api-key: $YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -N \
  -X POST \
  -d '{
    "model": "lyria-3-clip-preview",
    "input": "Generate a 30-second upbeat house intro with vocal chops.",
    "stream": true
  }'

4. 响应

4.1 非流式响应体

当 stream=false 时，接口返回一个 Interaction 对象。

常见字段：

字段	类型	说明
`id`	string	interaction 的唯一标识
`object`	string	资源类型标识，通常为 `interaction`
`status`	string	当前 interaction 状态，例如 `in_progress`、`completed`、`failed`
`role`	string	响应载荷对应的角色，通常为 `model`
`created`	string	interaction 的 ISO 8601 创建时间
`updated`	string	interaction 的 ISO 8601 更新时间
`model`	string	本次 interaction 使用的模型名称
`steps`	array	interaction 返回的有序步骤对象
`usage`	object	上游返回时附带的 token usage 汇总信息

常见的 steps 字段：

字段	类型	说明
`type`	string	步骤类型，例如 `model_output`
`content`	array	该步骤携带的内容项

示例：

json

{
  "id": "14sWasiVAZGq88EP4dq2iAE",
  "status": "completed",
  "role": "model",
  "created": "2026-05-27T06:15:03Z",
  "updated": "2026-05-27T06:15:03Z",
  "steps": [
    {
      "content": [
        {
          "text": "",
          "type": "text"
        }
      ],
      "type": "model_output"
    },
    {
      "content": [
        {
          "text": "Caption: This track is a quintessential piece of melancholic Jazz Fusion...\nMosic: 4.5\nBPM: 100.0",
          "type": "text"
        }
      ],
      "type": "model_output"
    },
    {
      "content": [
        {
          "mime_type": "audio/mpeg",
          "data": "...",
          "type": "audio"
        }
      ],
      "type": "model_output"
    }
  ],
  "object": "interaction",
  "model": "lyria-3-clip-preview"
}

4.2 流式响应体

当 stream=true 时，接口返回 server-sent events。常见 event_type 包括：

interaction.created
interaction.status_update
step.start
step.delta
step.stop
interaction.completed
error

流结束后，服务端会发送终止标记 data: [DONE]。

示例：

text

event: interaction.created
data: {"interaction":{"id":"","status":"in_progress","object":"interaction","model":"lyria-3-clip-preview"},"event_type":"interaction.created"}

event: interaction.status_update
data: {"interaction_id":"","status":"in_progress","event_type":"interaction.status_update"}

event: step.start
data: {"index":0,"step":{"type":"model_output"},"event_type":"step.start"}

event: step.delta
data: {"index":0,"delta":{"text":"Caption: A melancholic and sophisticated Jazz Fusion instrumental track...\nMosic: 4.5\nBPM: 100.0","type":"text"},"event_type":"step.delta"}

event: step.delta
data: {"index":0,"delta":{"mime_type":"audio/mpeg","data":"...","type":"audio"},"event_type":"step.delta"}

event: step.stop
data: {"index":0,"event_type":"step.stop"}

event: interaction.completed
data: {"interaction":{"id":"","status":"completed","object":"interaction","model":"lyria-3-clip-preview"},"event_type":"interaction.completed"}

event: done
data: [DONE]

5. Data Models

5.1 Content

同一套 content 结构同时用于请求里的 input 和响应里的 steps[].content。

可选类型

多态判别字段：type

TextContent

文本内容块。

字段	类型	说明
`type`	string	固定为 `"text"`。
`text`	string	文本内容。

ImageContent

图像内容块。

字段	类型	说明
`type`	string	固定为 `"image"`。
`data`	string	可选的内联图像内容，通常为 base64 编码。
`uri`	string	可选的图像 URI。
`mime_type`	string	可选的图像 MIME 类型，常见值包括 `image/png`、`image/jpeg`、`image/webp`。

AudioContent

音频内容块。

字段	类型	说明
`type`	string	固定为 `"audio"`。
`data`	string	可选的内联音频内容，通常为 base64 编码。
`uri`	string	可选的音频 URI。
`mime_type`	string	可选的音频 MIME 类型，常见值包括 `audio/wav`、`audio/mp3`、`audio/aac`、`audio/ogg`、`audio/flac`、`audio/mpeg`、`audio/m4a`。
`channels`	integer	可选的音频声道数。
`sample_rate`	integer	可选的音频采样率。

示例

Text

json

{
  "type": "text",
  "text": "Write a warm ambient piano theme."
}

Image

json

{
  "type": "image",
  "data": "BASE64_ENCODED_IMAGE",
  "mime_type": "image/png"
}

Audio

json

{
  "type": "audio",
  "data": "BASE64_ENCODED_AUDIO",
  "mime_type": "audio/wav"
}

5.2 Stream Event

当 stream=true 时，流式响应里的每个 data: 负载都使用同一套 stream event 结构。

可选类型

多态判别字段：event_type

InteractionCreatedEvent

在 interaction 创建后发送。

字段	类型	说明
`event_type`	string	固定为 `"interaction.created"`。
`interaction`	object	新创建 interaction 的快照。
`event_id`	string	可选的续传标记，用于从下一个事件继续恢复流。

InteractionStatusUpdate

在 interaction 状态变化时发送。

字段	类型	说明
`event_type`	string	固定为 `"interaction.status_update"`。
`interaction_id`	string	状态发生变化的 interaction 标识。
`status`	string	更新后的 interaction 状态，例如 `in_progress`、`completed`、`failed`。
`event_id`	string	可选的续传标记，用于从下一个事件继续恢复流。

StepStart

在某个 step 开始流式输出时发送。

字段	类型	说明
`event_type`	string	固定为 `"step.start"`。
`index`	integer	该 step 在 interaction 流中的从零开始序号。
`step`	object	当前开始的 step 元数据。
`event_id`	string	可选的续传标记，用于从下一个事件继续恢复流。

StepDelta

在流式增量输出时发送。

字段	类型	说明
`event_type`	string	固定为 `"step.delta"`。
`index`	integer	该 step 在 interaction 流中的从零开始序号。
`delta`	object	增量输出片段，例如文本增量或音频增量。
`event_id`	string	可选的续传标记，用于从下一个事件继续恢复流。

StepStop

在某个流式 step 结束时发送。

字段	类型	说明
`event_type`	string	固定为 `"step.stop"`。
`index`	integer	该 step 在 interaction 流中的从零开始序号。
`event_id`	string	可选的续传标记，用于从下一个事件继续恢复流。

InteractionCompletedEvent

在 interaction 完成时发送。

字段	类型	说明
`event_type`	string	固定为 `"interaction.completed"`。
`interaction`	object	最终的 interaction 快照。
`event_id`	string	可选的续传标记，用于从下一个事件继续恢复流。

ErrorEvent

在流式响应失败时发送。

字段	类型	说明
`event_type`	string	固定为 `"error"`。
`error`	object	描述失败原因的错误对象，通常包含 `code` 和 `message`。
`event_id`	string	可选的续传标记，用于从下一个事件继续恢复流。

示例

Interaction Created

json

{
  "event_type": "interaction.created",
  "interaction": {
    "id": "14sWasiVAZGq88EP4dq2iAE",
    "status": "in_progress",
    "object": "interaction",
    "model": "lyria-3-clip-preview"
  }
}

Interaction Status Update

json

{
  "event_type": "interaction.status_update",
  "interaction_id": "14sWasiVAZGq88EP4dq2iAE",
  "status": "in_progress"
}

Step Start

json

{
  "event_type": "step.start",
  "index": 0,
  "step": {
    "type": "model_output"
  }
}

Step Delta

json

{
  "event_type": "step.delta",
  "index": 0,
  "delta": {
    "type": "text",
    "text": "Caption: A melancholic and sophisticated Jazz Fusion instrumental track..."
  }
}

Step Stop

json

{
  "event_type": "step.stop",
  "index": 0
}

Interaction Completed

json

{
  "event_type": "interaction.completed",
  "interaction": {
    "id": "14sWasiVAZGq88EP4dq2iAE",
    "status": "completed",
    "object": "interaction",
    "model": "lyria-3-clip-preview"
  }
}

Error Event

json

{
  "event_type": "error",
  "error": {
    "code": "internal_error",
    "message": "Upstream stream closed unexpectedly."
  }
}

Done Marker

它用于终止流，不属于 event_type 枚举值。

text

data: [DONE]

Lyria API ​

1. 概述 ​

2. 鉴权方式 ​

3. Request ​

4. 响应 ​

4.1 非流式响应体 ​

4.2 流式响应体 ​

5. Data Models ​

5.1 Content ​

5.2 Stream Event ​

Lyria API

1. 概述

2. 鉴权方式

3. Request

4. 响应

4.1 非流式响应体

4.2 流式响应体

5. Data Models

5.1 Content

5.2 Stream Event