Suno Voice Creation and Reuse

Product overview · Task model

Create and reuse Voices

There are two public Voice creation workflows:

• Create from a completed clip owned by your OmnAPI user for 5 credits. This derives a reusable singer from generated song audio and does not require a verification phrase or separate recordings.
• Create from recordings for 66 credits. This verifies a real speaker with an assigned phrase and clean singing audio.

Both workflows return one asynchronous Task and produce a public voiceId that can be listed and reused with mode: "vox".

Create a Voice from an owned clip

The minimum request needs only the clip ID:

For each new logical operation, set and save a fresh REQUEST_KEY once. Reuse it with the exact same route and body only when recovering that operation. Use a different saved key when trying a different example or export format.

export REQUEST_KEY="$(uuidgen)"

curl -X POST https://api.omnapi.com/api/v1/suno/voices/from-clip \
  -H "x-api-key: $OMNAPI_KEY" \
  -H "Idempotency-Key: $REQUEST_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "clipId": "clip_owned_123",
    "name": "My Singer"
  }'

clipId must refer to a completed Suno clip owned by the current OmnAPI user. OmnAPI selects a compatible vocal range automatically. Advanced callers may provide both vocalRange.startSeconds and vocalRange.endSeconds; the ordered range must fit inside the source clip. name, description, imageUrl, and config are optional.

The source relationship is managed by OmnAPI. Do not send a verification phrase or recording URLs. A clip that is not owned by the caller returns 404 before paid task creation; an incomplete clip returns 409.

Create a Voice from verified recordings

1. Obtain the verification phrase

Request the phrase before recording the verification audio:

curl "https://api.omnapi.com/api/v1/suno/voices/verification-phrase?language=zh" \
  -H "x-api-key: $OMNAPI_KEY"

The response follows the read-style task contract. On an inline 200, use taskId as verificationPhraseTaskId and read the phrase from outputResults.phraseText. A 202 means the phrase task is still running; poll its pollUrl before recording.

The phrase task belongs to the current API user and is valid only for its associated Voice creation attempt.

2. Record two inputs

• voiceAudioUrl: clean singing or a cappella material used to build the reusable voice.
• verificationAudioUrl: the same person reading the returned phrase.

Both URLs must be publicly retrievable over HTTPS. Supported extension hints are mp3, wav, m4a, flac, and ogg.

3. Create the public Voice

Field	Type	Notes
verificationPhraseTaskId	string	Required Task ID returned by the verification-phrase request
voiceAudioUrl	HTTPS URL	Required clean singing recording
verificationAudioUrl	HTTPS URL	Required phrase-reading recording from the same person
voiceExtensionType / verificationExtensionType	enum	Optional mp3, wav, m4a, flac, or ogg hints
name	string, max 100	Optional public display name
description	string, max 2,000	Optional public description
imageUrl	HTTPS URL	Optional public image for the Voice
config	object	Priority, webhook URL, tags, and metadata

curl -X POST https://api.omnapi.com/api/v1/suno/voices \
  -H "x-api-key: $OMNAPI_KEY" \
  -H "Idempotency-Key: $REQUEST_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Demo Voice",
    "verificationPhraseTaskId": "task_phrase_01J...",
    "voiceAudioUrl": "https://example.com/clean-vocal.m4a",
    "verificationAudioUrl": "https://example.com/phrase-reading.m4a",
    "voiceExtensionType": "m4a",
    "verificationExtensionType": "m4a"
  }'

The request creates one asynchronous task and returns the standard Task create receipt. Poll links.task; on success, outputResults.voiceId is the reusable public ID and outputResults.voice is the normalized public Voice object.

If the verification session expires before task creation, the API returns 409. Obtain a new verification phrase instead of retrying with the old phrase task.

List, inspect, and use Voices

GET /api/v1/suno/voices?page=1&pageSize=20 returns only completed public Voices created by the current OmnAPI user through either public creation workflow.

List Voices

curl "https://api.omnapi.com/api/v1/suno/voices?page=1&pageSize=20" \
  -H "x-api-key: $OMNAPI_KEY"

Voice detail

curl https://api.omnapi.com/api/v1/suno/voices/voice_public_123 \
  -H "x-api-key: $OMNAPI_KEY"

{
  "voices": [
    {
      "voiceId": "voice_public_123",
      "name": "Demo Voice",
      "description": "Warm acoustic vocal",
      "imageUrl": "https://...",
      "voiceType": "recording",
      "isPublic": true,
      "taskId": "task_voice_01J...",
      "createdAt": "2026-07-30T12:00:00.000Z"
    }
  ],
  "currentPage": 1,
  "pageSize": 20,
  "totalResults": 1
}

page defaults to 1; pageSize defaults to 20 and accepts up to 100.

GET /api/v1/suno/voices/{voiceId} intentionally has no OmnAPI owner restriction. A known public Voice ID may be inspected and used by another user. It uses the read-style Task response: HTTP 200 contains outputResults: { voiceId, voice }; HTTP 202 supplies pollUrl.

Use the Voice in song generation:

curl -X POST https://api.omnapi.com/api/v1/suno/songs \
  -H "x-api-key: $OMNAPI_KEY" \
  -H "Idempotency-Key: $REQUEST_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "vox",
    "voiceId": "voice_public_123",
    "lyrics": "[Verse]\nSing this with the reusable voice...",
    "tags": "warm acoustic pop"
  }'

The voiceId is the complete public Voice reference. Callers do not need to provide any source-clip or provider-specific relationship fields.