Lyria API

This page documents the Exchange Token gateway entry for the Lyria series.

1. Overview

Exchange Token provides the Lyria series in a Gemini Interactions API compatible format.

Current scope:

• Supported models: lyria-3-clip-preview, lyria-3-pro-preview
• Supports non-streaming and SSE streaming
• Method: POST
• URL: https://api.exchangetoken.ai/v1beta/interactions

2. Authentication

Recommended header:

x-goog-api-key: YOUR_GATEWAY_API_KEY

3. Request

The downstream request body should stay close to the Interactions create schema.

Field	Type	Required	Description
model	string	Yes	Model name used to generate the interaction, for example lyria-3-clip-preview
input	string, content object, or content array	Yes	Primary interaction input, which can be plain text or structured multimodal content
stream	boolean	No	Whether to return the output as a server-sent event stream
system_instruction	string	No	High-level instruction that guides model behavior for the interaction

Non-streaming request example:

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

Streaming request example:

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. Response

4.1 Non-streaming response body

When stream=false, the API returns an Interaction object.

Common fields:

Field	Type	Description
id	string	Unique identifier of the interaction
object	string	Resource type identifier, typically interaction
status	string	Current interaction status, such as in_progress, completed, or failed
role	string	Role associated with the response payload, typically model
created	string	Interaction creation time in ISO 8601 format
updated	string	Last interaction update time in ISO 8601 format
model	string	Name of the model used for the interaction
steps	array	Ordered step objects returned by the interaction
usage	object	Token usage summary for the interaction when provided by upstream

Common steps fields:

Field	Type	Description
type	string	Step type, for example model_output
content	array	Content items carried by the step

Example:

{
  "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 Streaming response body

When stream=true, the API returns server-sent events. Common event_type values include:

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

After the stream finishes, the server sends the terminal marker data: [DONE].

Example:

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

The same content structure is used by request input and response steps[].content.

Possible Types

Polymorphic discriminator: type

TextContent

A text content block.

Field	Type	Description
type	string	Always set to "text".
text	string	The text content.

ImageContent

An image content block.

Field	Type	Description
type	string	Always set to "image".
data	string	Optional inline image content, typically base64 encoded.
uri	string	Optional URI of the image.
mime_type	string	Optional MIME type of the image. Common values include image/png, image/jpeg, and image/webp.

AudioContent

An audio content block.

Field	Type	Description
type	string	Always set to "audio".
data	string	Optional inline audio content, typically base64 encoded.
uri	string	Optional URI of the audio.
mime_type	string	Optional MIME type of the audio. Common values include audio/wav, audio/mp3, audio/aac, audio/ogg, audio/flac, audio/mpeg, and audio/m4a.
channels	integer	Optional number of audio channels.
sample_rate	integer	Optional sample rate of the audio.

Examples

Text

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

Image

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

Audio

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

5.2 Stream Event

The same stream event structure is used by streaming responses when stream=true.

Possible Types

Polymorphic discriminator: event_type

InteractionCreatedEvent

Sent when the interaction is created.

Field	Type	Description
event_type	string	Always set to "interaction.created".
interaction	object	Interaction snapshot for the newly created interaction.
event_id	string	Optional resume token for continuing the stream from the next event.

InteractionStatusUpdate

Sent when the interaction status changes.

Field	Type	Description
event_type	string	Always set to "interaction.status_update".
interaction_id	string	Identifier of the interaction whose status changed.
status	string	Updated interaction status, such as in_progress, completed, or failed.
event_id	string	Optional resume token for continuing the stream from the next event.

StepStart

Sent when a step starts streaming.

Field	Type	Description
event_type	string	Always set to "step.start".
index	integer	Zero-based index of the step in the interaction stream.
step	object	Metadata for the step that is starting.
event_id	string	Optional resume token for continuing the stream from the next event.

StepDelta

Sent for incremental streamed output.

Field	Type	Description
event_type	string	Always set to "step.delta".
index	integer	Zero-based index of the step in the interaction stream.
delta	object	Incremental output fragment, such as a text delta or audio delta.
event_id	string	Optional resume token for continuing the stream from the next event.

StepStop

Sent when a streamed step finishes.

Field	Type	Description
event_type	string	Always set to "step.stop".
index	integer	Zero-based index of the step in the interaction stream.
event_id	string	Optional resume token for continuing the stream from the next event.

InteractionCompletedEvent

Sent when the interaction finishes.

Field	Type	Description
event_type	string	Always set to "interaction.completed".
interaction	object	Final interaction snapshot.
event_id	string	Optional resume token for continuing the stream from the next event.

ErrorEvent

Sent when the stream fails.

Field	Type	Description
event_type	string	Always set to "error".
error	object	Error object describing the failure, typically including code and message.
event_id	string	Optional resume token for continuing the stream from the next event.

Examples

Interaction Created

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

Interaction Status Update

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

Step Start

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

Step Delta

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

Step Stop

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

Interaction Completed

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

Error Event

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

Done Marker

This terminates the stream and is not an event_type value.

data: [DONE]