README
¶
🎧 Lyria REST
🚀 概要 (About) - Lyria を REST で直接呼び、WAV で受け取ります。保存も作詞もしません
Lyria REST は、音楽生成モデル Lyria を REST（generateContent）で直接呼び、WAV を受け取る ための Go ライブラリです。返すのは音声バイト列と、モデルが返すテキストだけで、保存先は決めません。 歌詞や楽曲レシピを作る工程も持ちません。
[!IMPORTANT] これは、genai SDK が出力フォーマットの指定に対応するまでの繋ぎです。既定の入口は genai-kit の
lyriaのほうです。
google.golang.org/genaiのGenerateContentConfigには Lyria の出力フォーマットを指定する フィールドが無く、既定のエンコード結果しか受け取れません。WAV が要る用途——無劣化で結合する、 後段でマスタリングする、可逆のまま原盤を残す——では、そこが天井になります。REST にはその口が あるので、その 1 点のために SDK を迂回するのがこのライブラリです。逆に言えば、WAV が要らないならこれを使う理由はありません。 そして SDK が対応した時点で、 このリポジトリは役目を終えます。
シグネチャ・フィールド・エラーの一覧は pkg.go.dev にあります。ここに書くのは、 godoc を読んでも気付けないことだけです。
✨ 提供機能 (Features)
- genai-kit の
gemini.Generatorをそのまま満たします: これが設計の中心です。genai-kit のlyria.Newにlyria.WithAudioGenerator(client)で渡すと、音声生成だけがこちらを通り、 作詞・作曲・Track・呼び出しガード・プロンプト構築は genai-kit のものがそのまま動きます。 SDK に戻すときはオプションを外すだけです。genai-kit を import するのは型を共有するためで、 SDK の呼び出しは含みません。 - WAV 前提です: 出力フォーマットを選ばせる口は置きません。フォーマットを選びたいのではなく
WAV が欲しいからこのライブラリがあるので、選択肢を持つと存在理由がぼやけます。
GenerateOptionsで何を渡しても WAV の指定が勝ちます。 Configは genai-kit と同じ組み立てです:ProjectID/LocationIDなら Vertex AI （認証は Application Default Credentials）、APIKeyなら Gemini API。併用はエラーです。 設定の間違いに対するエラーの分類も genai-kit と揃えてあります。- 失敗の分類は genai-kit のセンチネルで判定できます: ブロックは
gemini.ErrBlocked、 空レスポンスはgemini.ErrEmptyResponseでerrors.Isが通ります。genai-kit の経路に 戻しても、呼び出し側の分岐は同じです。 - リトライを持ちません: SDK 内蔵のリトライは通りません。2xx 以外は
HTTPError（StatusCode付き、errors.Is(err, ErrHTTP)）で返すので、再試行の判断は呼び出し側で 行ってください。発射間隔・上限時間・重複排除が要る場合は、genai-kit のcallguardで包み、 テキスト生成と 1 つのガードを共有する形でワークフロー層に置いてください。 - 保存も後処理もしません: 返すのはバイト列です。GCS への書き出しは go-remote-io、WAV の無劣化結合や読みの正規化は audio が持ちます。
🔀 genai-kit の lyria との使い分け
genai-kit の lyria |
lyria-rest | |
|---|---|---|
| 位置づけ | 既定の入口 | SDK が追いつくまでの繋ぎ |
| 呼び出し経路 | genai SDK | REST を直接 |
| 出力 | モデル既定のエンコード | WAV |
| 担当範囲 | 作詞 → レシピ → 音声の 3 段ワークフロー | 音声生成 1 回だけ（gemini.Generator 1 メソッド） |
| リトライ | SDK 内蔵 | 無し |
まず genai-kit を見てください。 こちらを選ぶ理由は「WAV が要る」の 1 点だけです。
併用するときも、こちらは genai-kit の lyria に差し込んで使います。
🚦 使い方 (Usage)
go get github.com/shouni/lyria-rest
単体で 1 回呼ぶなら、genai-kit の gemini.Generator と同じ呼び方です。
package main
import (
"context"
"log"
"os"
"github.com/shouni/genai-kit/gemini"
"github.com/shouni/lyria-rest"
)
func main() {
ctx := context.Background()
client, err := lyriarest.New(lyriarest.Config{APIKey: os.Getenv("GEMINI_API_KEY")})
if err != nil {
log.Fatal(err)
}
resp, err := client.Generate(ctx, "lyria-3.5",
"Title: 'Light Me Up'. Euphoric festival EDM pop, 126 BPM, F minor.",
nil, gemini.GenerateOptions{})
if err != nil {
log.Fatal(err)
}
// Attachments[0] が WAV です。resp.Text にはモデルが返す譜面テキストが入ります。
if err := os.WriteFile("track.wav", resp.Audios[0], 0o644); err != nil {
log.Fatal(err)
}
}
genai-kit のワークフローに差し込むなら、lyria.New のオプションに渡します。
作詞・作曲は従来どおり SDK のクライアントが担い、音声だけがこちらを通ります。
workflow, err := lyria.New(sdkClient, textPrompts, audioPrompts,
lyria.WithGeminiModel("gemini-3.8-flash"),
lyria.WithLyriaModel("lyria-3.5"),
lyria.WithAudioGenerator(client), // ← SDK が WAV に対応したら、この 1 行を外す
)
🤝 依存関係 (Dependencies)
- genai-kit -
gemini.Generator/Attachment/GenerateOptions/Responseの型を共有するため。SDK の呼び出しは含みません - cloud.google.com/go/auth - Vertex AI 経路の Application Default Credentials
📜 ライセンス (License)
MIT License. 詳細は LICENSE を参照してください。
Documentation
¶
Overview ¶
Package lyriarest は、Vertex AI / Gemini API の Lyria を REST で直接呼び、WAV を受け取ります。
genai SDK には Lyria の出力フォーマットを指定する口が無く、既定のエンコード結果しか 受け取れません。REST の generateContent にはその口があるため、その 1 点のために SDK を 迂回するのがこのパッケージです。SDK が対応した時点で役目を終えます。
Client は genai-kit の gemini.Generator を満たします。genai-kit の lyria.New には lyria.WithAudioGenerator でこの Client を渡せるので、Workflow・Track・呼び出しガード・ プロンプト構築はすべて genai-kit のものをそのまま使い回せます。戻すときはオプションを 外すだけです。genai-kit を import するのは型（Generator / Attachment / GenerateOptions / Response）を共有するためで、SDK の呼び出しは含みません。
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ( // ErrConfigRequired は、ProjectID/LocationID と APIKey のいずれも設定されていない場合に返されます。 ErrConfigRequired = errors.New("lyriarest: either ProjectID/LocationID or APIKey is required") // ErrExclusiveConfig は、ProjectID/LocationID と APIKey が同時に設定された場合に返されます。 ErrExclusiveConfig = errors.New("lyriarest: ProjectID/LocationID and APIKey are mutually exclusive") // ErrIncompleteVertexConfig は、ProjectID と LocationID の一方のみが設定された場合に返されます。 ErrIncompleteVertexConfig = errors.New("lyriarest: Vertex AI requires both ProjectID and LocationID") // ErrEmptyModelName は、モデル名が空の場合に返されます。 ErrEmptyModelName = errors.New("lyriarest: model name is empty") // ErrEmptyParts は、プロンプトも添付も無く送るものが無い場合に返されます。 ErrEmptyParts = errors.New("lyriarest: generation parts are empty") // ErrInvalidAttachment は、添付の指定が不正な場合に返されます。 // Data と URI の併用、および Data に MIME type が無い場合が該当します。 ErrInvalidAttachment = errors.New("lyriarest: invalid attachment") // ErrInvalidSeed は、Seed が int32 の範囲外の場合に返されます。 ErrInvalidSeed = errors.New("lyriarest: seed must fit in int32") // ErrHTTP は、API が 2xx 以外を返したことを示します。詳細は HTTPError にあります。 ErrHTTP = errors.New("lyriarest: request failed") // ErrResponseTooLarge は、レスポンス本文がサイズ上限を超えた場合に返されます。 ErrResponseTooLarge = errors.New("lyriarest: response body exceeds the size limit") )
センチネルの文言は英語 + "lyriarest: " プレフィックスで統一しています。深いラップの 中に埋まってもどのパッケージ由来か判別できるようにするためで、人間向けの文脈は ラップする側（fmt.Errorf の %w）が日本語で補います。
Functions ¶
This section is empty.
Types ¶
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
Client は Lyria の REST クライアントです。
func New ¶
New は提供された設定に基づいてクライアントを作成します。
Vertex AI の場合はここで Application Default Credentials を検出します。 見つからなければエラーで、呼び出し時まで先送りしません。検出は通信を伴わないため context を取りません（トークンの取得は Generate の context で行います）。
func (*Client) Generate ¶
func (c *Client) Generate(ctx context.Context, model string, prompt string, attachments []gemini.Attachment, opts gemini.GenerateOptions) (*gemini.Response, error)
Generate は、プロンプトと添付から生成を実行します。genai-kit の gemini.Generator と同じ契約です。
リトライは持ちません。SDK 内蔵のリトライは通らないため、必要なら呼び出し側で genai-kit の callguard などで包んでください。打ち切りは呼び出し側の context に従います。
type Config ¶
type Config struct {
ProjectID string // Vertex AI: Google Cloud Project ID
LocationID string // Vertex AI: Location（"us-central1" や "global"）
APIKey string // Gemini API（Google AI Studio）のキー。ProjectID/LocationID と排他
// HTTPClient は REST 呼び出しに使う HTTP クライアントです。nil なら http.Client の
// ゼロ値（タイムアウト無し）を使い、打ち切りは呼び出し側の context にのみ従います。
//
// genai-kit と違い、渡したクライアントの認証を付け直す処理はありません。認証はヘッダで
// 行うため、Transport を差し替えても失われないからです。
HTTPClient *http.Client
// Endpoint はベース URL の上書きです。空なら公式ホストを使います。
// テストや私設プロキシ向けで、通常は設定しません。
Endpoint string
}
Config は初期化用の設定です。
genai-kit の gemini.Config と同じ組み立てです。ProjectID と LocationID を渡せば Vertex AI （認証は Application Default Credentials）、APIKey を渡せば Gemini API になります。 両方を渡すことはできません。
type HTTPError ¶
HTTPError は、API が 2xx 以外のステータスを返した場合のエラーです。 errors.Is(err, ErrHTTP) で分類でき、StatusCode で再試行の可否を判断できます。
type ResponseError ¶
type ResponseError struct {
// Reason は分類用のセンチネルです。
Reason error
// FinishReason は、ブロック時にモデルが返した終了理由です。無ければ空文字列です。
FinishReason string
// Message は人間向けの説明です。
Message string
}
ResponseError は、API との通信は成功したがレスポンスが利用できない場合のエラーです。
Reason には genai-kit の gemini.ErrBlocked / gemini.ErrEmptyResponse を入れます。 genai-kit の経路に戻したときも呼び出し側の errors.Is が同じ分岐を通るように、 センチネルを独自に持たず借りています。
func (*ResponseError) Error ¶
func (e *ResponseError) Error() string
func (*ResponseError) Unwrap ¶
func (e *ResponseError) Unwrap() error
Unwrap は分類用センチネルを返し、errors.Is による判定を可能にします。
Source Files