> ## 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>

### 프롬프트 작성 팁

프롬프트에 다음 내용을 명시하는 것이 좋습니다:

* 장르: country, pop, jazz, cinematic 등
* 악기: acoustic guitar, piano, drums 등
* 분위기: warm, dreamy, energetic 등
* 속도와 조성: 예: `90 BPM`, `G major`
* 보컬 또는 가사 필요 여부
* 곡 구조: `[Intro]`, `[Verse]`, `[Chorus]`, `[Bridge]`
* 길이 요구: Pro 모델은 프롬프트에서 목표 길이를 설명할 수 있음

예시:

```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`                     | 업스트림 요청 시간 초과                                    |

### 콘텐츠 안전 차단

다음 오류는 프롬프트가 Google 안전 필터에 의해 차단되었음을 의미하며, JSON 파라미터 오류가 아닙니다:

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

<Warning>
  동일한 프롬프트를 무한히 재시도하지 말고, 프롬프트를 수정하여 아티스트 목소리, 저작권이 있는 가사 또는 제한된 콘텐츠를 지정하지 마세요.
</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의 오디오 워터마크 메커니즘이 포함되어 있으며, 자세한 내용은 공식 모델 정책을 따릅니다.