【Рекомендуется】 API голосового профиля

Обновлено 2026-09-18 · команда Suno-API

✅ Для новых интеграций рекомендуем именно эту цепочку. По результатам реальных оценок многих пользователей песни, созданные этим путём, очень хорошо сохраняют исходный голос: вокал в готовой записи ближе к тому человеку, чей образец вы загрузили, поэтому сейчас это основной путь, который мы рекомендуем клиентам.

Для сравнения: прежний API клонирования голоса и генерации с заданным голосом тоже работает, но в навигации он помечен как «не рекомендуется» и для новых интеграций не советуется.

• Дата документа: 2026-09-26
• Охват: создать свой голос → сделать кавер выбранной песни / спеть новую песню этим голосом → следить за прогрессом → скачать готовое
• Все эндпоинты, поля и ответы проверены реальными вызовами (пункты с пометкой «измерено» проверены подробно)

Примечание: этот документ описывает только те эндпоинты, которые вызываете вы. Обработку материалов, планирование задач и проверку контента сервер делает автоматически; клиент их не реализует.

0. Начало за пять минут

Четырёх шагов достаточно, чтобы из одного образца голоса получить две готовые песни.

① Создать голос    POST /api/music/voice-profile/create      → получить voice_id (status=ready)
② Сделать кавер    POST /api/music/voice-profile/cover       → сразу получить 2 song_id
③ Следить          POST /api/music/query                     → опрашивать до status=completed
④ Скачать           GET  /api/music/download?song_id=…&kind=mp3

Минимальный рабочий пример (curl):

API_KEY="sk-ваш-ключ"
BASE="https://www.suno-api.io"

# ① Создать голос (загрузить образец вокала; рекомендуем 10 с и больше, до 10 МБ)
curl -sS -X POST "$BASE/api/music/voice-profile/create" \
  -H "Authorization: Bearer $API_KEY" \
  -F "file=@./my-voice.mp3" \
  -F "title=Мой голос" \
  -F "source_kind=upload"
# → {"success":true,"message":"","data":{"voice_id":"vp_2026…","status":"ready", …}}

# ② Сделать кавер на песню этим голосом (song_clip_id = clip id песни для кавера)
curl -sS -X POST "$BASE/api/music/voice-profile/cover" \
  -H "Authorization: Bearer $API_KEY" \
  -H "X-Create-Ui-Client-Request-Id: cover-$(date +%s)" \
  -H "Content-Type: application/json" \
  -d '{
        "model": "suno-v6",
        "voice_id": "vp_2026…",
        "song_clip_id": "5b773e9a-…",
        "lyrics": "[Verse 1]\nтекст песни…",
        "style_requirements": "медленный фолк, акустическая гитара",
        "audio_weight": 0.85,
        "max_mode": false
      }'
# → {"code":200,"message":"success","data":{"resolved_scene":"cover","clips":[{…},{…}]}}

# ③ Опрос (несколько id сразу, через запятую)
curl -sS -X POST "$BASE/api/music/query" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"suno-v6","song_ids":"id1,id2"}'

# ④ Скачать mp3 после завершения (файл появляется только при status=completed)
curl -sS -L "$BASE/api/music/download?song_id=id1&kind=mp3" \
  -H "Authorization: Bearer $API_KEY" -o song1.mp3

1. Общие соглашения

1.1 Домен и окружение

Все пути ниже указаны относительно Base URL; например, полный адрес POST /api/music/voice-profile/create — https://www.suno-api.io/api/music/voice-profile/create.

1.2 Аутентификация

Все эндпоинты используют один и тот же заголовок запроса, значение которого — созданный вами в консоли API-ключ:

Authorization: Bearer sk-xxxxxxxx

• Префикс Bearer необязателен; префикс sk- тоже (Authorization: sk-xxx работает так же).
• Ключ отсутствует или недействителен → HTTP 401, тело вида {"success":false,"message":"…"} (текст зависит от языка запроса).
• Каждый ключ видит и может изменять только песни и голоса своего аккаунта.

1.3 Форматы тела запроса

• Создание голоса: рекомендуется multipart/form-data (загрузка файла); также поддерживается application/json (URL или base64).
• Остальные эндпоинты: application/json.

1.4 Две оболочки ответа (клиенту нужно знать только эти две)

Эндпоинты «управления голосами» (create / create-from-clip / list / detail / delete) используют бизнес-оболочку:

{ "success": true, "message": "", "data": { } }

{ "success": false, "message": "voice_id is required" }

«Кавер с голосом» идёт по каналу генерации и использует оболочку генерации: успех — это code/message/data, ошибка — объект error:

{ "code": 200, "message": "success", "data": { } }

{ "error": { "message": "voice not found: vp_xxx", "type": "bad_response_status_code", "param": "", "code": "bad_response_status_code" } }

Как определять: сначала код состояния HTTP, затем success === false, затем code !== 200 или наличие error. Бизнес-ошибка не гарантирует HTTP, отличный от 200 (эндпоинты управления голосами возвращают HTTP 200 даже при ошибке), поэтому ориентироваться только на код состояния нельзя.

1.5 Идемпотентность

Создание голоса (включая «создать из существующего аудио») действительно идемпотентно: под одним и тем же ключом повторная отправка того же client_request_id создаёт только один голос, а вторая попытка сразу возвращает первый результат (success=true, тот же voice_id). Смысл в том, что клиент сам генерирует id (например, UUID) и при повторе после тайм-аута использует то же значение.

Отправка кавера не дедуплицируется на уровне запроса (это платная генерация), поэтому учтите два момента:

1. Идентификатор отправки лежит в заголовке X-Create-Ui-Client-Request-Id: <ваш id отправки>. Он записывается в серверную запись задачи и упрощает разбор позже; он не предотвращает повторное списание.
2. Тайм-аут ≠ неудача: запрос мог уже быть принят и генерироваться. Перед повтором проверьте через GET /api/music/songs?p=1&page_size=20 (параметры пагинации — p / page_size, совместимое написание ps тоже работает), не появилась ли уже новая песня с generation_type=voice_profile_cover, и повторяйте тот же запрос, только если её нет.

Тела create и create-from-clip тоже принимают поле client_request_id (см. §3 и §4).

1.6 Обзор оплаты

Цены в любой момент читаются через публичный эндпоинт, поэтому не хардкодьте их (см. §9):

curl -sS https://www.suno-api.io/api/pricing/catalog | jq '.data.catalog.meta'
# {
#   "generation_price": "0.6",
#   "voice_generation_price": "1.2",      ← базовая цена кавера с голосом
#   "max_mode_factor": "2",
#   "enhanced_upload_price": "10",        ← цена усиленного клонирования
#   "voice_auto_verify_price": "5",
#   "voice_long_term_clone_price": "5"
# }

Кавер работает по схеме предоплата + возврат при неудаче:

• Отклонённый запрос (неверные параметры, 4xx/5xx платформы, сам факт нехватки баланса) не списывается — при отправке с несуществующим голосом баланс в измерениях вообще не изменился (delta = 0);
• Принятая задача, которая в итоге провалилась (включая сбой сервиса платформы), проходит по серверному пути возврата и возвращает предоплаченную сумму.

1.7 Словарь состояний

status голоса:

status песни (значение, которое возвращают эндпоинты запроса):

2. Обзор эндпоинтов

3. Создание голоса

POST /api/music/voice-profile/create

Зарегистрируйте фрагмент вокального аудио как «голос» и получите voice_id. Для платформы голос — это просто «аудио + его клип в каталоге», поэтому после успешного создания это исходное аудио сохраняется навсегда (для последующих каверов).

3.1 Три формы ввода (выберите одну)

Форма A: загрузка файла multipart (рекомендуется)

Content-Type: multipart/form-data

file=<двоичные данные аудио>      # обязательно
title=<название голоса>           # необязательно; если пусто, имя файла без расширения
file_name=<исходное имя файла>
source_file_name=<исходное имя файла>
source_kind=upload|record         # необязательно, метка источника (загрузка / запись); по умолчанию upload
enhanced=false|true               # необязательно, true = усиленное клонирование (см. §3.5)
client_request_id=<ключ идемпотентности>   # необязательно
voice_id=<свой ID>                # необязательно, обычно не используется

curl -sS -X POST "https://www.suno-api.io/api/music/voice-profile/create" \
  -H "Authorization: Bearer $API_KEY" \
  -F "file=@./my-voice.mp3;type=audio/mpeg" \
  -F "file_name=my-voice.mp3" \
  -F "source_file_name=my-voice.mp3" \
  -F "title=Мой голос" \
  -F "source_kind=upload"

Форма B: JSON + публичный URL аудио

curl -sS -X POST "https://www.suno-api.io/api/music/voice-profile/create" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "file_url": "https://your-cdn.example.com/voice/my-voice.mp3",
        "file_name": "my-voice.mp3",
        "title": "Мой голос"
      }'

• URL должен быть публично доступной прямой HTTPS-ссылкой; сервер один раз скачивает её и перекладывает в наше объектное хранилище.
• Адрес можно положить и в поле audio_url, эффект тот же (если отправлены оба, приоритет у file_url).
• Если адрес уже в объектном хранилище этой платформы (*.myqcloud.com/create-ui/voice-source/...), повторного скачивания не будет: он регистрируется напрямую.

Форма C: JSON + base64

{
  "file_base64": "data:audio/mpeg;base64,//uQxAAA…",
  "file_name": "my-voice.mp3",
  "title": "Мой голос"
}

• Поддерживается и префикс data:audio/xxx;base64,, и чистый base64.
• Размер ограничен (base64 увеличивает объём в 1,33 раза), для больших файлов используйте форму A.

3.2 Требования к аудио

3.3 Ответ

{
  "success": true,
  "message": "",
  "data": {
    "voice_id": "vp_20260926080618509168500DXXrxe",
    "clip_id": "91cc5935-389f-4193-b56b-cc796c15562d",
    "song_id": "91cc5935-389f-4193-b56b-cc796c15562d",
    "account_id": "acc_1790085275308",
    "title": "Мой голос",
    "source_file_name": "my-voice.mp3",
    "audio_url": "https://suno-api-p-1437223057.cos.ap-guangzhou.myqcloud.com/create-ui/voice-source/2026/09/26/xxx.mp3",
    "image_url": "https://cdn2.suno.ai/image_91cc5935-389f-4193-b56b-cc796c15562d.jpeg",
    "duration_s": 29.18,
    "enhanced": false,
    "source_kind": "upload",
    "status": "ready",
    "client_request_id": "",
    "created_at": 1790409978,
    "updated_at": 1790409998
  }
}

Описание полей (create / list / detail используют один и тот же набор):

created_at / updated_at — метки времени в секундах (10 цифр), не в миллисекундах.

3.4 Частые ошибки

3.5 Усиленное клонирование (enhanced=true)

Для случаев, когда «сам образец голоса содержит защищённые авторским правом слова / нужна усиленная загрузка». Цена — как за усиленную загрузку (по умолчанию 10 ¥ за вызов, при неудаче автоматический возврат):

• Ответ сразу status=processing + task_id (на этом этапе clip_id ещё нет), выполнение асинхронное;
• Во время обработки прогресс смотрите через GET /api/music/voice-profile/{voice_id}: возвращаются progress_percent / progress_stage / progress_message;
• По завершении status становится ready, а clip_id, audio_url, image_url заполняются;
• При неудаче status=failed, а error_message выглядит как «усиленная загрузка не удалась, средства возвращены автоматически, попробуйте позже»;
• Усиленное клонирование заметно дольше обычного создания (минуты), поэтому не ждите его синхронным тайм-аутом.

curl -sS -X POST "https://www.suno-api.io/api/music/voice-profile/create" \
  -H "Authorization: Bearer $API_KEY" \
  -F "file=@./my-voice.mp3" -F "title=Мой голос" -F "enhanced=true"

4. Создание голоса из имеющегося аудио

Если не хотите загружать заново: скопируйте в голос аудио, которое уже загружено или уже сгенерировано. Бесплатно и идемпотентно.

POST /api/music/voice-profile/create-from-clip
Content-Type: application/json

{
  "source_song_id": "97ee62fe-56cd-473f-a2f5-c66ac0766a2e",
  "title": "Сюй Цин Цян",
  "client_request_id": "vp-clip-1789…"
}

• source_song_id: clip id завершённого аудио в вашем аккаунте (совпадает с song_id песни).
• Повторная отправка того же клипа не создаёт новую запись: сразу возвращается существующий голос с reused: true (измерено).

Ответ — все поля из §3.3 плюс два поля только для чтения:

{
  "success": true,
  "data": {
    "voice_id": "vp_20260926081712557959800Z5gvlt",
    "clip_id": "97ee62fe-56cd-473f-a2f5-c66ac0766a2e",
    "title": "Сюй Цин Цян",
    "status": "ready",
    "enhanced": true,
    "reused": true,
    "source_type": "enhanced_upload"
  }
}

Ошибки (message как есть; рекомендуется показать или локализовать):

5. Список / детали / удаление голосов

5.1 Список

GET /api/music/voice-profile/list
GET /api/music/voice-profile/list?include_deleted=true

{
  "success": true,
  "message": "",
  "data": {
    "items": [ { "voice_id": "vp_…", "title": "Мой голос", "status": "ready", "audio_url": "…", "image_url": "…" } ],
    "total": 1
  }
}

Поля полностью совпадают с §3.3. Удалённые голоса по умолчанию не возвращаются.

5.2 Детали

GET /api/music/voice-profile/{voice_id}

Возвращается один объект голоса (data — сам объект, не массив). Пока идёт усиленное клонирование, добавляются:

5.3 Удаление

POST /api/music/voice-profile/delete
Content-Type: application/json

{ "voice_id": "vp_2026…" }

{ "success": true, "message": "", "data": { "voice_id": "vp_2026…", "status": "deleted" } }

• После удаления голос исчезает из списка и больше не годится для новых каверов: отправка с этим voice_id возвращает 400 (см. §6.4).
• Песни, уже созданные им, вообще не затрагиваются; воспроизведение, скачивание, продолжение, замена и разделение работают как прежде.
• Удаление несуществующего голоса или голоса, не принадлежащего этому аккаунту, возвращает {"success":false,"message":"voice not found"}.

6. Кавер с голосом (ключевой эндпоинт)

POST /api/music/voice-profile/cover
Content-Type: application/json

Одна отправка создаёт 2 песни (как и обычная генерация).

6.1 Два сценария

resolved_scene в ответе вернёт cover или sing, чтобы вы могли подтвердить выбранный путь.

6.2 Поля запроса

Рекомендуется также передавать заголовок X-Create-Ui-Client-Request-Id: <тот же id отправки>: только он записывается в серверную запись задачи и служит ключом для последующего разбора (см. §1.5).

Размерности: audio_weight / style_weight / weirdness_constraint — дроби от 0 до 1, variety — целое от 0 до 4, duration — в секундах. Путаница приводит к отказу или странному результату.

В сценарии B текст песни необязателен (модель справится сама), но всегда передавайте lyrics, если нужно спеть конкретный текст.

6.3 Ответ

{
  "code": 200,
  "message": "success",
  "data": {
    "voice_id": "vp_20260926081712557959800Z5gvlt",
    "voice_clip_id": "97ee62fe-56cd-473f-a2f5-c66ac0766a2e",
    "song_clip_id": "5b773e9a-a035-4134-a4a4-29c9961d3ccb",
    "resolved_scene": "cover",
    "model": "suno-v6",
    "audio_weight": 0.85,
    "clips": [
      {
        "song_id": "0f2a…",
        "status": "processing",
        "song_title": "",
        "model_version": "suno-v6",
        "audio_url": "",
        "play_url": "https://media.suno-api.io/play/0f2a…?expires=…&signature=…",
        "lyrics": "",
        "description": "[Задача] Это кавер. … (фиксированный структурный блок сервера + ваши требования к каверу / стилю)"
      },
      {
        "song_id": "7c91…",
        "status": "processing",
        "model_version": "suno-v6",
        "audio_url": ""
      }
    ],
    "source_updates": []
  }
}

Главное:

1. Готовые записи определяйте по clips[].song_id (этот эндпоинт не возвращает поле id).
2. Вы сразу получаете 2 значения song_id, при этом status ещё processing (это лишь значит «принято»), а audio_url пуст; перед скачиванием нужно опросить до completed. play_url — поток предпрослушивания платформы, может появиться уже на этапе отправки и истечёт.
3. description — это промпт, который сервер в итоге отправляет (фиксированный структурный блок + введённые вами cover_requirements / style_requirements); он очень помогает при разборе результата.
4. source_updates — результат обработки материалов на сервере, клиент может игнорировать.
5. Переданный вами title пишется в серверную запись задачи и появляется как song_title в последующих запросах; то, что clips[].song_title в ответе на отправку пустой, — нормально.

6.4 Ошибки

{ "error": { "message": "этот голос не существует или был удалён (voice_id=vp_xxx)…", "type": "new_api_error", "param": "", "code": "invalid_request" } }

Нехватка баланса возвращает ошибку биллинга прямо на этапе отправки и не оставляет незавершённых задач.

6.5 Доступные модели (имена для клиента)

Используйте имена моделей для клиента (те, что выше). chirp-* — внутренние имена платформы, их использовать напрямую не следует.

7. Запрос прогресса

7.1 Пакетный запрос (рекомендуется)

POST /api/music/query
Content-Type: application/json

{ "model": "suno-v6", "song_ids": "id1,id2" }

• song_ids — строка с запятыми (не массив).
• Ответ — голый массив (сразу [...], без оболочки success / data):

[
  {
    "song_id": "0f2a…",
    "song_title": "Два тигра",
    "status": "completed",
    "audio_url": "https://suno-api-hk-1437223057.cos.ap-hongkong.myqcloud.com/assets/0f2a…-mp3.mp3",
    "cover_url": "https://cdn2.suno.ai/image_0f2a….jpeg",
    "duration": 115.15,
    "model_version": "suno-v6",
    "generation_type": "voice_profile_cover",
    "play_url": "https://media.suno-api.io/play/…?expires=…&signature=…",
    "lyrics": "[Verse 1]…",
    "prompt": "[Verse 1]…",
    "description": "[Задача] Это кавер. … (итоговый промпт сервера)",
    "style_tags": "…",
    "created_at": "2026-09-25T18:19:09.918Z",
    "video_url": ""
  }
]

Совет по опросу: каждые 5–10 секунд, общий тайм-аут 10–15 минут (самый медленный измеренный «холодный» аккаунт занял около 4,5 минуты; очень немногие дольше). Завершение определяйте не по пустому audio_url, а по status.

Замечание о совместимости: этот эндпоинт идентифицирует песни по song_id; в некоторых ранних ответах появлялось поле id, поэтому безопаснее читать row.song_id || row.id.

7.2 Детали одной песни

GET /api/music/songs/{song_id}

{
  "success": true,
  "data": {
    "song_id": "0f2a…",
    "title": "Два тигра",
    "status": "completed",
    "generation_type": "voice_profile_cover",
    "model": "suno-v6",
    "duration": 115.15,
    "audio_url": "https://…/assets/0f2a…-mp3.mp3",
    "image_url": "https://cdn2.suno.ai/image_0f2a….jpeg",
    "wav_url": "https://www.suno-api.io/api/music/download?song_id=0f2a…&kind=wav",
    "video_url": "https://www.suno-api.io/api/music/download?song_id=0f2a…&kind=video",
    "created_at": 1790411012,
    "completed_at": 1790411500,
    "parameters": {
      "prompt": "[Verse 1]…",
      "style_tags": "…",
      "title": "Два тигра",
      "model": "suno-v6",
      "generation_type": "voice_profile_cover",
      "source_song_id": "5b773e9a-…"
    },
    "parameter_retention": {
      "core_parameters_available": true,
      "extended_parameters_available": false,
      "sources": ["suno_tasks"],
      "unavailable_fields": ["negative_tags", "vocal_gender", "style_weight", "weirdness_constraint"]
    }
  }
}

• Здесь created_at / completed_at — Unix-секунды (в отличие от строк ISO в пакетном запросе, клиенты должны их различать).
• wav_url / video_url — точки входа скачивания этой платформы (относительно текущего домена), GET отдаёт файл; если платформа такой материал не создала, там пустая строка.
• parameter_retention показывает, к каким параметрам отправки можно проследить песню: core_parameters_available=true означает, что основные параметры (текст / стиль / источник) доступны для запроса, а при extended_parameters_available=false перечисленные выше расширенные параметры не сохранены (каверы с голосом сейчас в этой категории).

7.3 Мои работы

GET /api/music/songs?p=1&page_size=20
GET /api/music/songs?status=completed&q=ключевое слово

Параметры пагинации: p (номер страницы с 1) / page_size (элементов на странице; совместимое написание ps). Необязательные status и q (ключевое слово в названии). По умолчанию сортировка по времени создания по убыванию.

{
  "success": true,
  "data": {
    "page": 1,
    "page_size": 20,
    "total": 42,
    "items": [
      {
        "song_id": "0f2a…",
        "title": "Два тигра",
        "status": "completed",
        "generation_type": "voice_profile_cover",
        "model": "suno-v6",
        "duration": 115.15,
        "audio_url": "https://…/assets/0f2a…-mp3.mp3",
        "image_url": "https://cdn2.suno.ai/image_0f2a….jpeg",
        "created_at": 1790411012,
        "completed_at": 1790411500
      }
    ]
  }
}

По generation_type=voice_profile_cover удобно отличать «песни из кавера с голосом» от остальных результатов генерации.

8. Скачивание готовых песен

8.1 Взять mp3 напрямую (рекомендуется, бесплатно)

Подходит любой из трёх способов, выберите один:

1. Взять audio_url из результата запроса (прямая ссылка на объектное хранилище, проще всего).
2. GET /api/music/download?song_id=<id>&kind=mp3 → сразу возвращает байтовый поток аудио (в Content-Disposition уже есть имя файла).
3. POST /api/music/download-url (получить подписанный временный адрес).

curl -sS -L "https://www.suno-api.io/api/music/download?song_id=0f2a…&kind=mp3" \
  -H "Authorization: Bearer $API_KEY" -o song.mp3

Значения kind: mp3 (эквивалент song) / playback (потоковое воспроизведение) / wav / video / lyrics / timestamped_lyrics. timestamped_lyrics (.lrc) сейчас доступен только для части песен; при неудаче сформируйте файл самостоятельно через API текста с метками времени. Ответ — это сам байтовый поток файла, Content-Type и Content-Disposition (имя файла) уже заданы; wav_url / video_url из GET /api/music/songs/{song_id} — та же точка входа с kind=wav|video.

8.2 Конвертация в wav / получить текст песни / метаданные (платно)

POST /api/music/free2
Content-Type: application/json

{ "song_ids": ["0f2a…"], "files": ["mp3", "wav", "lyrics"] }

{
  "success": true,
  "data": {
    "songs": [
      { "song_id": "0f2a…", "files": [ { "type": "mp3", "url": "https://…" }, { "type": "wav", "url": "https://…" } ] }
    ],
    "requested_songs": 1,
    "succeeded_songs": 1,
    "price": 0.2
  }
}

• files принимает: mp3 / wav / lyrics / metadata, до 10 песен за раз.
• Списание по числу удачных песен (0,2 ¥ за песню); полностью неудачная песня не оплачивается, а неудачный формат виден только в songs[].errors.
• Чтобы снова получить уже скачанные файлы, сначала используйте бесплатный POST /api/music/free2/cached (те же song_ids + files) и возьмите архивные адреса; его songs[].missing_files перечисляет форматы без кеша, которые нужно готовить заново.

9. Запрос цен

GET /api/pricing/catalog

Публичный эндпоинт, аутентификация не нужна. Все цены, которые нужно показать клиенту, лежат в data.catalog.meta (строки):

Цены меняются в бэк-офисе, поэтому читайте их в реальном времени и не зашивайте в клиент. Фактическое списание за кавер = voice_generation_price × (при истинном max_mode ещё × max_mode_factor).

10. Ограничения и предупреждения

1. Размер загрузки: ≤ 10 МБ (сервер принимает больше, но входной шлюз обрезает слишком большие тела на 10 МиБ, что выглядит как «отклонено Suno»; блокируйте раньше на своей стороне).
2. Длительность образца: минимум 6 с, рекомендуется 10–60 с; слишком короткий платформа отклоняет.
3. Содержимое образца: чистый вокал; избегайте всего, что сильно похоже на существующую запись (сравнение с каталогом отклонит).
4. Лимиты текста: lyrics ≤ 3000 символов; для style_requirements / negative_tags / title желательно 1000 / 1000 / 100 символов соответственно (требования к стилю и каверу дописываются в промпт, держите сумму в пределах 3000 символов).
5. Текст песни не переписывается: поётся то, что вы передали (посимвольно), локальной обрезки нет.
6. Каждая песня даёт 2 записи; не рассчитывайте на один результат.
7. Исходное аудио сохраняется навсегда: удаление голоса не очищает его исходное аудио; так сохраняется возможность последующих каверов и прослеживаемость соответствия требованиям.
8. Голос должен быть ready: голос в состоянии processing нельзя использовать для каверов.
9. Тайм-аут запроса: у «холодного» аккаунта первая отправка в измерениях занимала до ~4,5 минуты, поэтому ставьте тайм-аут клиента ≥ 6 минут. Каверы не дедуплицируются на уровне запроса, поэтому после тайм-аута проверьте, не появилась ли уже новая песня (§1.5), прежде чем отправлять снова.
10. Принадлежность голоса: голоса принадлежат создателю; кавер принимает только готовые и не удалённые голоса. Несуществующий, удалённый или принадлежащий другому аккаунту голос вернёт 400: этот голос не существует или был удалён (voice_id=…).

11. Частые вопросы (FAQ)

В1. Создание голоса стоит денег? Обычное создание и «создать из имеющегося аудио» бесплатны; платными являются только каверы (1,2 ¥ / MAX 2,4 ¥) и усиленное клонирование (по умолчанию 10 ¥).

В2. Можно ли использовать как образец готовую песню с аккомпанементом? Не рекомендуется. Всё с музыкой или сильно похожее на существующую запись в каталоге платформа отклоняет (This audio matches an existing recording in our catalog.). Берите чисто вокальную сухую запись.

В3. Почему audio_url пуст после отправки кавера? Отправка означает только приём, status ещё processing. Воспроизводимый/скачиваемый адрес появляется после опроса /api/music/query до status=completed.

В4. Нужно ли передавать текст в сценарии B (без song_clip_id)? Необязательно. Передавайте lyrics, чтобы спеть конкретный текст; без него модель справится сама, но управляемость ниже.

В5. Можно ли использовать загруженное клиентом аудио напрямую как голос? Да: через форму file_url у create либо сначала загрузив его как песню и затем вызвав create-from-clip.

В6. Вернут ли деньги при неудаче? Резко отклонённый запрос (неверные параметры / ошибка платформы) не списывается, по измерениям; принятая, но в итоге неудачная задача вернёт предоплаченную сумму. При окончательной неудаче задача отдаёт status=failed и error_message.

В7. После удаления голоса можно ли ещё слушать созданные им песни? Да. Удаление влияет только на то, можно ли использовать этот голос для новых каверов.

В8. Какой длины песню можно закаверить за раз? duration принимает 1–480 секунд; если не передать, платформа решит по оригиналу / материалу. Учтите: готовые записи платформы не короче примерно 30 секунд; при меньшем значении в измерениях всё равно выходило 29,96 / 29,76 секунды.

Приложение A: полный пример (Node.js, с опросом и скачиванием)

const BASE = "https://www.suno-api.io";
const KEY = process.env.SUNO_API_KEY;
const H = { Authorization: `Bearer ${KEY}` };

// ① Создать голос (multipart)
async function createVoice(filePath, title) {
  const fd = new FormData();
  fd.set("file", new Blob([await (await import("node:fs/promises")).readFile(filePath)], { type: "audio/mpeg" }), "my-voice.mp3");
  fd.set("file_name", "my-voice.mp3");
  fd.set("source_file_name", "my-voice.mp3");
  fd.set("title", title);
  fd.set("client_request_id", `vp-create-${Date.now()}`);
  const res = await fetch(`${BASE}/api/music/voice-profile/create`, { method: "POST", headers: H, body: fd });
  const body = await res.json();
  if (!body.success) throw new Error(body.message);
  return body.data; // { voice_id, status, audio_url, ... }
}

// ② Кавер
async function cover(voiceId, songClipId, lyrics) {
  const submissionId = `vp-cover-${Date.now()}`;
  const res = await fetch(`${BASE}/api/music/voice-profile/cover`, {
    method: "POST",
    headers: { ...H, "Content-Type": "application/json", "X-Create-Ui-Client-Request-Id": submissionId },
    body: JSON.stringify({
      model: "suno-v6",
      voice_id: voiceId,
      song_clip_id: songClipId || "",
      lyrics: lyrics || "",
      style_requirements: "медленный фолк, акустическая гитара",
      audio_weight: 0.85,
      max_mode: false,
      client_request_id: submissionId,
    }),
  });
  const body = await res.json();
  if (body.error) throw new Error(body.error.message);
  return body.data; // { resolved_scene, clips: [{ song_id, status }] }
}

// ③ Опрос до завершения (каждые 5 секунд, максимум 15 минут)
async function waitUntilCompleted(songIds) {
  const deadline = Date.now() + 15 * 60 * 1000;
  while (Date.now() < deadline) {
    const res = await fetch(`${BASE}/api/music/query`, {
      method: "POST",
      headers: { ...H, "Content-Type": "application/json" },
      body: JSON.stringify({ model: "suno-v6", song_ids: songIds.join(",") }),
    });
    const songs = await res.json(); // голый массив
    if (songs.every((s) => s.status === "completed" || s.status === "failed")) return songs;
    await new Promise((r) => setTimeout(r, 5000));
  }
  throw new Error("timeout waiting for cover");
}

// ④ Скачивание
async function download(songId, outPath) {
  const res = await fetch(`${BASE}/api/music/download?song_id=${encodeURIComponent(songId)}&kind=mp3`, { headers: H });
  if (!res.ok) throw new Error(`download failed: ${res.status}`);
  (await import("node:fs/promises")).writeFile(outPath, Buffer.from(await res.arrayBuffer()));
}

const voice = await createVoice("./my-voice.mp3", "Мой голос");
const result = await cover(voice.voice_id, "5b773e9a-a035-4134-a4a4-29c9961d3ccb", "[Verse 1]\nтекст…");
const ids = result.clips.map((c) => c.song_id);
const songs = await waitUntilCompleted(ids);
for (const [i, s] of songs.entries()) {
  if (s.status === "completed") await download(s.song_id, `./out-${i}.mp3`);
}

Приложение B: журнал изменений