가사 생성 API
인터페이스 설명
가사 생성은 주제, 기존 가사 문맥, 스타일 요구사항을 바탕으로 가사를 만들거나 고쳐 씁니다. 현재 엔드포인트는 최신 가사 생성 계약으로 업그레이드되어 프로페셔널 모드 생성에 바로 사용할 수 있습니다.
엔드포인트: POST /api/lyrics/generate
과금: 무료 한도 내에서는 무료(사용자당 분당 최대 10회, 하루 최대 300회)이며, 무료 한도를 넘으면 호출당 0.1 위안입니다.
한도 초과 감지: 무료 한도를 초과해도 요청은 정상 실행되며, 응답 헤더에 X-Suno-Helper-Free: false와 X-Suno-Helper-Over-Limit: minute(또는 day)이 실립니다. 이를 근거로 이번 호출이 과금되었음을 클라이언트에서 알릴 수 있습니다.
권장 모델: suno-v6. suno-v6, suno-v6-wild, suno-v6-mini를 사용할 수 있습니다.
인증
| 파라미터 | 타입 | 필수 | 설명 |
|---|---|---|---|
| Authorization | string | 예 | Bearer YOUR_API_KEY |
| Content-Type | string | 예 | application/json |
요청 파라미터
| 파라미터 | 타입 | 필수 | 기본값 | 설명 |
|---|---|---|---|---|
| model | string | 예 | - | 대고객 모델명: suno-v6, suno-v6-wild, suno-v6-mini |
| instruction | string | 예 | - | 가사 주제 또는 생성 요구사항 |
| style | string | 아니오 | - | 스타일 요구사항 |
| title | string | 아니오 | - | 곡 제목 또는 제목 제약 |
| selected | string | 아니오 | "" |
고쳐 쓸 대상으로 선택된 텍스트 |
| context_before | string | 아니오 | "" |
앞 문맥 |
| context_after | string | 아니오 | "" |
뒤 문맥 |
| mode | string | 아니오 | apply_user_request |
가사 생성 모드 |
| references | array | 아니오 | [] |
참고 자료 목록 |
| num_variants | integer | 아니오 | null |
원하는 가사 변형 개수 |
| lyricist_id | string | 아니오 | null |
특정 작사가 ID(작사가 목록은 종료되어 신규 연동은 권장하지 않음) |
| metadata | object | 아니오 | - | 확장 파라미터. lyrics_model, enable_thinking 지원 |
| lyrics_project_id | string | 아니오 | null |
기존 가사 프로젝트 ID(가사 프로젝트 시리즈는 종료되어 신규 연동은 권장하지 않음) |
instruction은 예전 필드 theme과 prompt도 받습니다. metadata.lyrics_model의 기본값은 default, metadata.enable_thinking의 기본값은 false입니다.
언어 제어
현재 엔드포인트에는 별도의 language 요청 필드가 없습니다. 가사의 언어는 instruction 내용으로 결정되며, style은 보조적인 역할만 합니다.
중국어 가사를 만들려면 instruction에 목표 언어를 명확히 적으세요. 예:
{
"model": "suno-v6",
"instruction": "请用中文写歌词，主题是夏夜海边重逢",
"style": "Mandopop, 中文流行"
}
"Write the lyrics in Chinese about ..."라고 써도 됩니다. 영어 가사를 만들려면 "请用英文写歌词" 또는 "Write the lyrics in English"라고 씁니다. 영어 주제만 넘기고 목표 언어를 적지 않으면 결과가 영어일 수 있습니다.
요청 예시
curl -X POST https://www.suno-api.io/api/lyrics/generate \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "suno-v6",
"instruction": "졸업 시즌과 새로운 출발에 관한 한국어 가사",
"style": "팝 록, 진솔함, 기억에 남는 후렴",
"title": "다시 출발",
"metadata": {
"lyrics_model": "default",
"enable_thinking": false
}
}'
응답 결과
{
"code": 200,
"message": "success",
"data": {
"lyrics": "[Verse]\n바람이 운동장을 스쳐 간다\n우리는 어제에게 손을 흔든다",
"edited_lyrics": "[Verse]\n바람이 운동장을 스쳐 간다\n우리는 어제에게 손을 흔든다",
"lyrics_id": "lyrics_id",
"lyrics_request_id": "lyrics_request_id"
}
}
edited_lyrics는 가사 입력란에 넣어야 하는 완성된 가사입니다. lyrics_id와 lyrics_request_id는 추적용이며 엔드포인트 반환 상황에 따라 비어 있을 수 있습니다. 곡 ID로 취급하지 마세요.
호환성 설명
- 예전 필드
theme,prompt도 사용할 수 있으며instruction으로 매핑됩니다. - '가사 프로젝트 / 작사가' 계열 엔드포인트는 종료되었습니다. 생성 결과를 보관해야 한다면 엔드포인트가 반환하는
edited_lyrics를 직접 저장하세요.