Lyria 3 Pro Preview

소개

lyria-3-pro-preview는 완전한 음악을 생성하며, 벌스·코러스·브리지 등 비교적 완성도 높은 곡 구조에 적합하고 출력은 오디오입니다. Gravitex는 Google Interactions 스타일 인터페이스를 제공합니다:

인터페이스	메서드	설명
생성 요청 제출	`POST /v1beta/interactions`	음악 생성 작업 제출(동기 또는 비동기)
작업 결과 조회	`GET /v1beta/interactions/{interaction_id}`	비동기 작업 상태 및 결과 폴링

공식 참고:

Google Lyria 3 음악 생성

인증

string

필수

Bearer Token, 예: Bearer sk-xxxxxxxxxxxxxxxx

string

또는 X-API-Key: sk-xxxxxxxxxxxxxxxx 사용 가능

생성 요청 제출

POST /v1beta/interactions background 전달 여부에 따라 동기와 비동기 두 가지 모드로 나뉩니다.

동기 생성(기본값)

요청에 background를 전달하지 않거나 명시적으로 background: false를 전달하면, 게이트웨이는 업스트림 생성이 완료될 때까지 기다린 후 결과를 반환하며 비동기 작업 테이블에 기록하지 않습니다.

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

성공 응답:

{
  "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를 반환합니다. 이후 작업 결과 조회 인터페이스로 폴링해야 합니다.

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

제출 응답:

{
  "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, 로그, 과금이 업데이트됩니다. 클라이언트는 이 인터페이스를 폴링하여 최종 결과를 확인하기만 하면 됩니다.

요청 예시

curl 'https://api.gravitex.ai/v1beta/interactions/task_xxxxxxxxx' \
  -H 'Authorization: Bearer sk-xxxxxxxxxxxxxxxx'

처리 중(in_progress)

{
  "id": "task_xxxxxxxxx",
  "object": "interaction",
  "role": "model",
  "model": "lyria-3-pro-preview",
  "status": "in_progress"
}

완료(completed)

{
  "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)

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

폴링 간격은 2~5초를 권장하며, completed, failed, cancelled 상태에서 중지하세요.

파라미터

string

필수

lyria-3-pro-preview로 고정

string

필수

음악 설명, 편곡 요구 사항 또는 가사. Google 스타일은 문자열 사용

boolean

true는 Gravitex 로컬 비동기 작업 사용. 기본값은 동기

boolean

Google Interactions 요청과 호환. 비동기 요청에는 true 권장

object

오디오 응답 형식 설정. {"type": "audio"} 전달. 현재 채널 모델 설정에 따름

string

멀티턴 Interaction 연결 ID. Lyria 3는 현재 단회 생성 권장

프롬프트 작성 팁

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

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

예시:

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 파라미터 오류가 아닙니다:

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

오디오 처리 예시

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);
}

주의 사항

lyria-3-pro-preview는 텍스트 채팅 결과가 아닌 음악 오디오를 출력합니다.
top_p, temperature 등 일반 텍스트 모델 파라미터를 Lyria에 강제로 전달하지 마세요. 사용 가능한 파라미터는 채널 설정과 공식 모델 문서를 따릅니다.
비동기 요청은 반환된 Gravitex task_xxx ID로 폴링해야 합니다.
생성된 오디오에는 Google의 오디오 워터마크 메커니즘이 포함되어 있으며, 자세한 내용은 공식 모델 정책을 따릅니다.

API 문서

대화 및 텍스트

안전 및 오디오

이미지 시리즈

비디오 시리즈

텍스트 완성 및 임베딩

인터페이스 모듈

소개

인증

생성 요청 제출

동기 생성(기본값)

비동기 생성

작업 결과 조회

요청 예시

처리 중(in_progress)

완료(completed)

실패(failed)

파라미터

프롬프트 작성 팁

상태 코드 및 오류

콘텐츠 안전 차단

오디오 처리 예시

주의 사항

​소개

​인증

​생성 요청 제출

​동기 생성(기본값)

​비동기 생성

​작업 결과 조회

​요청 예시

​처리 중(in_progress)

​완료(completed)

​실패(failed)

​파라미터

​프롬프트 작성 팁

​상태 코드 및 오류

​콘텐츠 안전 차단

​오디오 처리 예시

​주의 사항

소개

인증

생성 요청 제출

동기 생성(기본값)

비동기 생성

작업 결과 조회

요청 예시

처리 중(in_progress)

완료(completed)

실패(failed)

파라미터

프롬프트 작성 팁

상태 코드 및 오류

콘텐츠 안전 차단

오디오 처리 예시

주의 사항