스피치(Speech) 생성 API
인터페이스 설명
스피치는 연설 원고나 한 줄 설명을 "말하기/연설" 오디오로 생성하며, 배경 음악 여부를 선택할 수 있습니다. 연설, 축사, 내레이션, 나레이션 원고, 오디오 콘텐츠 같은 상황에 적합합니다.
알려드립니다: 이 엔드포인트가 생성하는 것은 말소리 오디오이며 노래가 아닙니다(멜로디도, 노래하는 보컬도 없습니다). 노래가 필요하면 영감 모드 생성 API 또는 프로 모드 생성 API를 사용하세요.
엔드포인트: POST /api/music/speech
과금: 유료, 현재 기본 1회 0.6위안. 보통 1회 호출에 2개의 오디오가 반환되며, 실제 청구 금액은 현재 백오피스 가격 설정을 따릅니다.
Max Mode / Variety: 이 엔드포인트는 선택 파라미터 max_mode와 variety(0-4)를 지원합니다.
max_mode를 켜면 이번 호출은 2배 가격으로 과금되며(0.6 → 1.2위안/회), variety는 추가 과금이 없습니다.
두 값의 의미와 사용법은 새 API 개요의 "고급 파라미터" 절을 참고하세요.
대기 시간과 타임아웃(중요): 이 엔드포인트는 동기 방식이며, 응답이 돌아온 시점에야 주문이 접수되어 생성에 넘겨집니다. 실측 기준 대부분의 요청은 수초(1~10초) 안에 반환되지만, 다른 동기 생성 엔드포인트와 마찬가지로 극단적인 경우 더 오래 걸릴 수 있습니다. 클라이언트 타임아웃을 300초 이상으로 설정하세요. 응답이 없다고 해서 생성되지 않은 것이 아니며, 타임아웃 직후 재시도하면 주문이 중복되고 요금이 두 번 청구됩니다. 연결이 끊겼다면 잠시 후
GET /api/music/songs로 확인할 수 있습니다. 자세한 내용은 새 API 개요의 "대기 시간과 타임아웃 설정"을 참고하세요.
콘텐츠 적합성: 플랫폼은 원고에 대해 저작권과 콘텐츠 정책 검사를 수행합니다. 저작권 자료(예: 타인의 가사 인용, 유명 작품 원문 그대로)로 판정되면 이번 생성은 실패하고 전액이 자동 환불됩니다. 자신의 표현으로 바꾸거나 인용을 바꿔 말하기로 고친 뒤 다시 시도하세요.
요청 파라미터
Headers
| 파라미터 | 타입 | 필수 | 설명 |
|---|---|---|---|
| Authorization | string | 예 | Bearer YOUR_API_KEY |
| Content-Type | string | 예 | application/json |
Body 파라미터
| 파라미터 | 타입 | 필수 | 기본값 | 설명 |
|---|---|---|---|---|
| script | string | 예 | - | 원고 전문. 최대 3000자(초과 시 400 반환, 과금 없음) |
| tone | string | 아니오 | - | 어조/속도/감정/장면 설명. 예: "열정적이고 힘차게, 속도는 느리게 시작해 점점 빠르게; 학교 강당". 최대 1000자 |
| song_title | string | 아니오 | - | 제목. 최대 100자 |
| gender | string | 아니오 | 제한 없음 | 화자 성별: m, f(male, female도 허용). 같은 값을 vocal_gender로 보내도 됩니다 |
| backing_music | boolean | 아니오 | true |
배경 음악을 넣을지 여부. false면 목소리만 있는 연설 |
| model | string | 아니오 | suno-v6 |
대고객 모델명: suno-v6, suno-v6-wild, suno-v6-mini |
| wait_completion | boolean | 아니오 | false |
생성 완료를 기다린 뒤 반환할지 여부 |
| max_mode | boolean | 아니오 | false |
켜면 이번 호출은 2배 가격으로 과금 |
| variety | integer | 아니오 | - | 스타일 변화 정도 0-4. 개요의 "고급 파라미터" 참고 |
이 엔드포인트는
duration(길이 파라미터)을 지원하지 않습니다: 보내면 HTTP 400을 반환하며, 조용히 무시하지 않습니다. 연설 길이는script의 내용 길이로 결정됩니다.
요청 예시
최소 요청(원고만)
curl -X POST https://www.suno-api.io/api/music/speech \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
--max-time 300 \
-d '{
"script": "선생님, 학생 여러분, 안녕하세요! 오늘 제 발표 주제는 「시간을 헛되이 보내지 않고 힘차게 나아가기」입니다."
}'
전체 요청(어조·성별 지정, 배경 음악 끔)
curl -X POST https://www.suno-api.io/api/music/speech \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
--max-time 300 \
-d '{
"script": "Good evening everyone, thank you all for coming to celebrate this special day with us.",
"tone": "warm and slow, wedding reception",
"song_title": "Wedding Toast",
"gender": "f",
"backing_music": false,
"model": "suno-v6"
}'
Python 예시
import requests
response = requests.post(
'https://www.suno-api.io/api/music/speech',
headers={'Authorization': 'Bearer YOUR_API_KEY'},
json={
'script': '동료 여러분, 안녕하세요. 이번 주 진행 상황을 보고드리겠습니다.',
'tone': '차분하고 명확하게, 회의 보고',
'gender': 'male',
'backing_music': True,
},
timeout=300,
)
response.raise_for_status()
items = response.json() # 보통 2개
for item in items:
print(item['song_id'], item['status'])
파라미터 설명
script(원고, 필수)
- 말하려는 내용을 그대로 붙여 넣으세요. 한 줄 설명을 써서 모델이 원고를 쓰게 할 수도 있습니다 (예: "20점 차로 뒤진 팀을 위한 하프타임 격려, 낮은 속삭임에서 온몸의 함성까지").
- 줄바꿈, 문단,
[멈춤]같은 무대 지시도 그대로 쓸 수 있고 모델이 최대한 따릅니다. - 상한은 3000자(유니코드 문자 기준, 한자는 1자)이며, 초과 시 400을 반환하고 과금되지 않습니다.
tone(어조와 장면, 선택)
"무엇을 말하는가"가 아니라 "어떻게 말하는가"를 설명합니다. 어조, 속도/리듬, 감정, 장면 네 가지 정보를 포함하는 것이 좋습니다.
열정적이고 힘차게, 속도는 느리게 시작해 점점 빠르게, 뚜렷한 멈춤; 학교 강당, 전교생 대상
따뜻하고 부드럽게, 완만한 속도; 결혼 피로연장
차분하고 절제된, 일정하고 명확한 속도; 이사회 보고
상한은 1000자. 입력하지 않으면 모델이 script 내용으로 판단합니다.
gender / vocal_gender(화자 성별, 선택)
- 남성은
m또는male, 여성은f또는female을 보냅니다. 서버는m/f로 정규화합니다. - 두 필드명 모두 지원하며 하나만 쓰면 됩니다: 이 엔드포인트의 권장 표기는
gender입니다. 이미 프로 모드를 쓰고 있다면vocal_gender를 그대로 써도 됩니다. - **보내지 않으면 "제한 없음"**이며 모델이 결정합니다.
backing_music(배경 음악, 선택)
- 기본은
true(배경 음악 포함)이며 Suno 웹 버전의 기본과 같습니다. false를 보내면 목소리만 있는 연설이 되어, 나중에 직접 BGM이나 나레이션을 얹기 좋습니다.- JSON 불리언
true/false를 써야 합니다. 문자열"true","1"도 허용되지만 불리언을 권장합니다.
model(모델, 선택)
세 가지 대고객 모델을 모두 쓸 수 있고 가격이 같습니다(1회 0.6위안). 연설은 Suno v6 계열 엔진으로 생성되며, 입력하지 않으면 기본
suno-v6으로 처리됩니다. 명확한 선호가 없다면 보통 이 필드는 보낼 필요가 없습니다.
파라미터 검증과 텍스트 상한
다음 경우 HTTP 400이 반환되며, 모두 과금 전에 차단되어 비용이 발생하지 않습니다:
| 상황 | 오류 메시지 |
|---|---|
script가 없거나 공백만 있음 |
script is required for speech |
gender가 m/f/male/female이 아님 |
gender must be one of m, f, male, female |
backing_music이 불리언이 아님 |
backing_music must be a boolean |
지원하지 않는 duration을 보냄 |
duration is not supported on /api/music/speech |
텍스트 필드 길이 상한
초과 시에도 HTTP 400이 반환되고 생성으로 넘어가지 않으며 선차감도 없습니다. 계산은 유니코드 문자 기준(한자 1자는 1자)이며
앞뒤 공백도 포함됩니다:
| 필드 | 상한 |
|---|---|
script(원고) |
3000자 |
tone(어조 설명) |
1000자 |
song_title(제목) |
100자 |
오류 메시지는 script must not exceed 3000 characters; received 4120 형태입니다.
첫 단어가 초과한 필드명이고 끝이 실제 글자 수이므로, 400을 받으면 이 두 숫자로 바로 잘라내면 됩니다.
응답 결과
응답은 다른 생성 엔드포인트와 완전히 동일한 곡 배열(보통 2개)입니다. song_id를 저장한 뒤
곡 조회 API로 최종 상태와 오디오 주소를 조회하세요:
[
{
"song_id": "b7529174-b495-465b-8c5e-cd21bea2df8c",
"song_title": "시간을 헛되이 보내지 않고",
"status": "pending",
"audio_url": "",
"cover_url": "",
"video_url": "",
"model_version": "suno-v6",
"generation_type": "generate",
"created_at": "2026-10-08T01:00:00Z"
}
]
| 필드 | 설명 |
|---|---|
song_id |
곡 ID. 이후 조회와 다운로드에 모두 이 값을 씁니다 |
status |
pending(제출됨, 생성 중), processing, completed(완료), failed(실패) |
song_title |
제목(song_title을 보내지 않으면 모델이 생성하며 비어 있을 수 있습니다) |
audio_url |
오디오 주소. 생성 완료 전에는 비어 있고, 완료 후에는 바로 재생·다운로드할 수 있습니다 |
생성 실패와 환불
생성에 실패하면 이번 비용은 자동으로 전액 환불되며 고객센터에 문의할 필요가 없습니다. 실패 사유는 응답 또는
곡 조회 API의 error_message에서 확인할 수 있습니다.
가장 흔한 실패 원인은 콘텐츠가 저작권 자료로 판정되는 것입니다. 예를 들어:
Your lyrics contain copyrighted material. Please change it and try again.
이 경우 원고를 자신의 표현으로 바꾸거나(또는 인용을 바꿔 말하기로 고친 뒤) 다시 제출하세요.
자주 묻는 질문
Q: 왜 노래가 아니라 "말하기"가 생성되나요? A: 이 엔드포인트는 연설용이며 출력이 말소리 오디오입니다. 노래가 필요하면 생성/프로 모드 엔드포인트를 사용하세요.
Q: 왜 매번 2개가 반환되나요?
A: 이 플랫폼의 다른 생성 엔드포인트와 마찬가지로 한 번의 생성에서 후보 2개가 나옵니다. song_id별로 조회해 마음에 드는 하나를 고르면 됩니다.
Q: 길이는 어떻게 제어하나요?
A: script의 길이로 결정되며, 이 엔드포인트는 duration 파라미터를 받지 않습니다.
Q: 음색(예: 제가 클론한 목소리)을 지정할 수 있나요?
A: 현재 버전에서는 지원하지 않습니다. 연설은 고정된 연설 음색을 사용하며 gender로 남성/여성을 지정할 수 있습니다.
본인 목소리가 필요하면 보이스 프로필 생성 API(권장)의 관련 기능을 사용하세요.
Q: tone을 입력하지 않으면 어떻게 되나요?
A: 모델이 script 내용으로 어조와 리듬을 판단합니다. 어떤 스타일을 안정적으로 재현하려면 어조·속도·장면을 tone에 적어 두세요.
호환 필드
| 권장 필드 | 호환 필드 | 설명 |
|---|---|---|
gender |
vocal_gender |
둘 중 하나만 보내면 되고 m/f/male/female 모두 가능 |
새로 연동할 때는 snake_case로 통일하세요. 나머지 필드(script, tone, song_title, backing_music)에는 camelCase 별칭이 없습니다.
다음 단계
song_id를 받은 뒤:
- 곡 조회 API로 생성 상태와 오디오 주소를 조회합니다;
- 완료 후 곡 미디어 다운로드 및 미리듣기 API로 내려받거나 들어봅니다;
- 일괄 다운로드나 자체 저장소로 옮기려면 다운로드 센터 관련 엔드포인트를 참고하세요.