> ## Documentation Index > Fetch the complete documentation index at: https://docs.evolink.ai/llms.txt > Use this file to discover all available pages before exploring further. # Suno 음악 생성 Beta > - Suno AI 음악 생성 모델, 텍스트 설명 또는 가사를 기반으로 완전한 음악 생성 지원 - 커스텀 모드 (스타일, 제목, 가사 세밀 제어) 및 심플 모드 (AI 자동 생성) 지원 - [Persona](/ko/api-manual/audio-series/suno/suno-persona-creation) 기능 지원, 생성된 보컬/스타일 특성을 재사용할 수 있습니다 - 비동기 처리 모드, 반환된 작업 ID로 [상태 조회](/ko/api-manual/task-management/get-task-detail) - 생성된 오디오 링크는 72시간 동안 유효하며, 즉시 저장해 주세요 - 각 요청마다 여러 음악 변형이 생성됩니다 ## OpenAPI ````yaml ko/api-manual/audio-series/suno/suno-music-generation.json POST /v1/audios/generations openapi: 3.1.0 info: title: Suno 음악 생성 API description: Suno AI 모델을 사용하여 음악을 생성하며, 보컬 및 인스트루멘탈 모드를 모두 지원합니다 license: name: MIT version: 1.0.0 servers: - url: https://api.evolink.ai description: 프로덕션 환경 security: - bearerAuth: [] paths: /v1/audios/generations: post: tags: - Audio Generation summary: Suno 음악 생성 API description: >- - Suno AI 음악 생성 모델, 텍스트 설명 또는 가사를 기반으로 완전한 음악 생성 지원 - 커스텀 모드 (스타일, 제목, 가사 세밀 제어) 및 심플 모드 (AI 자동 생성) 지원 - [Persona](/ko/api-manual/audio-series/suno/suno-persona-creation) 기능 지원, 생성된 보컬/스타일 특성을 재사용할 수 있습니다 - 비동기 처리 모드, 반환된 작업 ID로 [상태 조회](/ko/api-manual/task-management/get-task-detail) - 생성된 오디오 링크는 72시간 동안 유효하며, 즉시 저장해 주세요 - 각 요청마다 여러 음악 변형이 생성됩니다 operationId: createSunoMusicGeneration requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SunoMusicGenerationRequest' examples: simple_mode: summary: 간편 모드 (초보자 권장) value: model: suno-v5-beta prompt: A cheerful summer pop song about road trips and freedom custom_mode_with_lyrics: summary: 커스텀 모드 (가사 포함) value: model: suno-v5-beta custom_mode: true instrumental: false style: pop, electronic, upbeat, female vocals, 120bpm title: Summer Dreams prompt: |- [Verse 1] Driving down the highway, windows down The sun is shining on this little town Radio playing our favorite song Nothing could ever go wrong [Chorus] Summer dreams, summer nights Chasing stars and city lights With you by my side I feel so alive negative_tags: heavy metal, screaming, sad vocal_gender: f custom_mode_with_persona: summary: 커스텀 모드 (Persona 사용) value: model: suno-v5-beta custom_mode: true instrumental: false style: electronic pop, synth wave, 128bpm title: 네온 드리머 prompt: |- [Verse] 네온 불빛 아래 거리를 거닐며 도시의 맥박이 가슴 속에 뛰고 [Chorus] 우리는 꿈을 쫓는 자 별빛 아래 춤을 추며 persona_id: 5c57d49ef834110496fae5aa14fec441 persona_model: voice_persona instrumental_mode: summary: 연주 모드 value: model: suno-v4.5plus-beta custom_mode: true instrumental: true style: lo-fi, chill, ambient, piano, soft drums title: 비 오는 오후 responses: '200': description: 음악 작업 생성 성공 content: application/json: schema: $ref: '#/components/schemas/AudioGenerationResponse' '400': description: 요청 매개변수가 잘못되었습니다 content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: invalid_request message: Invalid request parameters type: invalid_request_error '401': description: 인증되지 않았거나 토큰이 유효하지 않거나 만료되었습니다 content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: unauthorized message: Invalid or expired token type: authentication_error '402': description: 할당량이 부족합니다. 충전이 필요합니다 content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: insufficient_quota message: Insufficient quota. Please top up your account. type: insufficient_quota '403': description: 접근이 거부되었습니다 content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: model_access_denied message: 'Token does not have access to model: suno-v5-beta' type: invalid_request_error '429': description: 요청 한도를 초과했습니다 content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: rate_limit_exceeded message: Too many requests, please try again later type: rate_limit_error '500': description: 서버 내부 오류 content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: internal_error message: Internal server error type: api_error '503': description: 서비스를 일시적으로 사용할 수 없습니다 content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: service_unavailable message: No available channel for the requested model type: api_error components: schemas: SunoMusicGenerationRequest: type: object required: - model - custom_mode - instrumental properties: model: type: string description: >- 모델 이름 **하위 호환성:** 이전에 통합된 모델명(예: `suno-v5`, `suno-v4.5`, `suno-v4.5plus`, `suno-v4.5all`, `suno-v4`)은 계속 사용 가능하며, 해당 `-beta` 버전으로 자동 매핑됩니다 **사용 가능한 옵션:** - `suno-v5-beta`: V5 최신 버전 (기본 권장), Voice Persona 지원, 뛰어난 음악 표현력, 더 빠른 생성, 프롬프트 최대 `5000`자, 스타일 최대 `1000`자 - `suno-v4.5plus-beta`: V4.5+ 향상 버전, 더 풍부한 톤, 새로운 창작 방법, 최대 8분, 프롬프트 최대 `5000`자, 스타일 최대 `1000`자 - `suno-v4.5all-beta`: V4.5 전체 기능 버전, 더 스마트한 프롬프트, 더 빠른 생성, 최대 8분, 프롬프트 최대 `5000`자, 스타일 최대 `1000`자 - `suno-v4.5-beta`: V4.5 버전, 더 스마트한 프롬프트, 더 빠른 생성, 최대 8분, 프롬프트 최대 `5000`자, 스타일 최대 `1000`자 - `suno-v4-beta`: V4 버전, 향상된 보컬 품질, 최대 4분, 프롬프트 최대 `3000`자, 스타일 최대 `200`자 enum: - suno-v5-beta - suno-v4.5plus-beta - suno-v4.5all-beta - suno-v4.5-beta - suno-v4-beta example: suno-v5-beta custom_mode: type: boolean description: |- 커스텀 모드 활성화 **설명:** - `false`: 심플 모드, `prompt`만 제공하면 AI가 가사와 스타일을 자동 생성 - `true`: 커스텀 모드, `style`, `title`, 가사 등을 세밀하게 제어 가능 **커스텀 모드 필수 파라미터:** - `style`: 필수 - `title`: 필수 - `prompt`: `instrumental=false`일 때 필수 (가사로 사용) example: false instrumental: type: boolean description: |- 인스트루멘탈 음악 생성 (보컬 없음) **설명:** - `false`: 보컬이 포함된 음악 생성 - `true`: 보컬 없는 인스트루멘탈/배경 음악 생성 **참고:** - 비커스텀 모드에서는 이 파라미터가 필수 필드에 영향을 주지 않습니다 - 커스텀 모드에서 `true`로 설정하면 `prompt`가 선택 사항이 됩니다 example: false prompt: type: string description: |- 프롬프트, 원하는 음악 내용을 설명합니다 **비커스텀 모드 (`custom_mode=false`):** - 필수, 음악 설명으로 사용되며 AI가 가사와 스타일을 자동 생성 - 최대 길이: `500`자 **커스텀 모드 (`custom_mode=true`):** - `instrumental=false`일 때 필수, 정확한 가사로 사용 - `instrumental=true`일 때 선택 사항 - 최대 길이: V4는 `3000`자, V4.5+는 `5000`자 **가사 형식 제안:** - `[Verse]`, `[Chorus]`, `[Bridge]` 등의 태그로 가사 구조를 구성하세요 example: A cheerful summer pop song about road trips and freedom style: type: string description: >- 음악 스타일 지정 **설명:** - 사용자 정의 모드(`custom_mode=true`)에서 필수 - 음악의 장르, 분위기 또는 예술적 방향을 정의합니다 - 영어로 쉼표로 구분된 태그 사용을 권장합니다 **문자 제한:** - V4: 최대 `200`자 - V4.5+: 최대 `1000`자 **일반적인 스타일 태그:** - 장르: pop, rock, jazz, classical, electronic, hip-hop, r&b, country, folk - 분위기: happy, sad, energetic, calm, romantic, dark, uplifting - 악기: piano, guitar, drums, bass, violin, saxophone, synthesizer - 보컬: male vocals, female vocals, choir, harmonies - 템포: slow, fast, upbeat, groovy, 120bpm example: pop, electronic, upbeat, female vocals title: type: string description: |- 곡 제목 **설명:** - 사용자 정의 모드(`custom_mode=true`)에서 필수 - 플레이어 인터페이스 및 파일명에 표시됩니다 - 최대 길이: `80`자 maxLength: 80 example: Summer Dreams negative_tags: type: string description: |- 제외 스타일, 피하고 싶은 음악 스타일이나 특성을 지정합니다 **예시:** - `heavy metal, screaming, sad` - `rap, fast tempo` example: heavy metal, screaming vocal_gender: type: string description: |- 보컬 성별 선호 **옵션:** - `m`: 남성 목소리 - `f`: 여성 목소리 **참고:** - `custom_mode=true`일 때만 적용됩니다 - 이 매개변수는 확률만 높이며, 지정된 성별이 반드시 따라지는 것을 보장하지 않습니다 enum: - m - f example: f style_weight: type: number description: |- 스타일 가중치, 지정된 스타일에 대한 준수도를 제어합니다 **범위:** `0.0` ~ `1.0`, 소수점 한 자리 **설명:** - 높은 값일수록 지정된 스타일에 더 가깝게 준수합니다 - `0` 값은 미설정으로 처리됩니다 minimum: 0 maximum: 1 example: 0.7 weirdness_constraint: type: number description: |- 기이함 제약, 출력의 창의성/실험적 정도를 제어합니다 **범위:** `0.0` ~ `1.0`, 소수점 한 자리 **설명:** - 높은 값일수록 더 창의적이고 실험적인 출력 - 낮은 값일수록 더 전통적이고 보수적인 출력 - `0` 값은 미설정으로 처리됩니다 minimum: 0 maximum: 1 example: 0.3 audio_weight: type: number description: |- 오디오 가중치, 오디오 특성의 가중치를 제어합니다 **범위:** `0.0` ~ `1.0`, 소수점 한 자리 **설명:** - `0` 값은 미설정으로 처리됩니다 minimum: 0 maximum: 1 example: 0.5 persona_id: type: string description: >- Persona ID, 이미 생성된 Persona 스타일을 이번 음악 생성에 적용합니다 `custom_mode=true`일 때만 사용 가능합니다. [Suno Persona 생성](/ko/api-manual/audio-series/suno/suno-persona-creation) API를 통해 획득하며, 적용 후 일관된 보컬 및 스타일 특성을 유지할 수 있습니다 **획득 방법:** Persona 작업 완료 후 `result_data.persona_id`에서 가져옵니다 example: 5c57d49ef834110496fae5aa14fec441 persona_model: type: string description: >- Persona 적용 방식 **옵션:** 1. `style_persona`: 스타일 지향형, 음악 스타일 특성(편곡, 리듬, 음색)에 중점, 모든 모델 버전 지원 2. `voice_persona`: 보컬 지향형, 보컬 특성(음색, 창법, 음역)에 중점, **V5만 지원** `custom_mode=true`일 때만 사용 가능하며, 일반적으로 `persona_id`와 함께 사용합니다. `voice_persona` 사용 시 모델이 `suno-v5-beta`여야 하며, 그렇지 않으면 오류가 반환됩니다 enum: - style_persona - voice_persona example: style_persona callback_url: type: string description: >- 작업 완료 알림을 위한 HTTPS 콜백 URL **콜백 단계:** - 콜백 프로세스는 세 단계로 구성: `text` (텍스트 생성), `first` (첫 번째 트랙 완료), `complete` (모두 완료) - 경우에 따라 `text` 및 `first` 단계가 건너뛰어지고 `complete`가 직접 반환될 수 있음 **보안 제한:** - HTTPS 프로토콜만 지원 - 내부 IP 주소로의 콜백 금지 - URL 길이는 `2048`자를 초과할 수 없음 **콜백 메커니즘:** - 타임아웃: `10`초 - 실패 시 최대 `3`회 재시도 - 콜백 URL이 2xx 상태 코드를 반환하면 성공으로 간주 format: uri example: https://your-domain.com/webhooks/suno-callback AudioGenerationResponse: type: object properties: created: type: integer description: 작업 생성 타임스탬프 example: 1766319090 id: type: string description: 작업 ID, 작업 상태 및 결과를 조회하는 데 사용됩니다 example: task-unified-1766319089-oqs9cue4 model: type: string description: 실제 사용된 모델 이름 example: suno-v5-beta object: type: string enum: - audio.generation.task description: 작업 유형 progress: type: integer description: 작업 진행률 (0-100) minimum: 0 maximum: 100 example: 0 status: type: string description: 작업 상태 enum: - pending - processing - completed - failed example: pending task_info: $ref: '#/components/schemas/AudioTaskInfo' description: 오디오 작업 상세 type: type: string enum: - audio description: 작업 출력 유형 example: audio usage: $ref: '#/components/schemas/Usage' description: 사용량 및 과금 정보 ErrorResponse: type: object properties: error: type: object properties: code: type: string description: 오류 코드 식별자 message: type: string description: 오류 설명 type: type: string description: 오류 유형 AudioTaskInfo: type: object properties: can_cancel: type: boolean description: 작업 취소 가능 여부 example: true estimated_time: type: integer description: 예상 완료 시간 (초) example: 120 Usage: type: object description: 사용량 및 과금 정보 properties: billing_rule: type: string description: 과금 규칙 enum: - per_call - per_token - per_second example: per_call credits_reserved: type: number description: 예상 소비 크레딧 minimum: 0 example: 10 user_group: type: string description: 사용자 그룹 카테고리 enum: - default - vip example: default securitySchemes: bearerAuth: type: http scheme: bearer description: |- ##모든 API는 Bearer Token 인증이 필요합니다## **API Key 받기:** [API Key 관리 페이지](https://evolink.ai/dashboard/keys)를 방문하여 API Key를 받으세요 **요청 헤더에 추가:** ``` Authorization: Bearer YOUR_API_KEY ``` ````