--- title: Suno Voice-to-Validation-Phrase url: https://runapi.ai/docs/api/suno/voice-to-validation-phrase.md canonical: https://runapi.ai/docs/api/suno/voice-to-validation-phrase locale: en --- # Suno Voice-to-Validation-Phrase ## Overview Use the voice to validation phrase endpoint with the required inputs. Use the returned Task ID to retrieve its state, or provide callback_url for the deliveries documented below. ### Quick start 1. Create an API key and set it as RUNAPI_API_KEY. 2. Send a POST request whose body matches the request schema. 3. Store the returned task ID, then poll until a terminal state or handle the callbacks documented below. ## Endpoint POST /api/v1/suno/voice_to_validation_phrase Base URL: https://runapi.ai API version: v1 Authentication: Authorization: Bearer YOUR_API_TOKEN ## Supported models Open a model page for current pricing, rate limits, and commercial-usage details. - [Suno](/models/suno) ## Request schema Send only the documented fields. When supplied, callback_url receives the Task deliveries documented below. ### Request body ```json { "callback_url": { "description": "Webhook URL for async notifications.", "type": "string" }, "language": { "description": "Language code.", "enum": [ "en", "zh", "es", "fr", "pt", "de", "ja", "ko", "hi", "ru" ], "type": "string" }, "vocal_end_seconds": { "description": "End time (seconds) of the source vocal segment. Must be greater than vocal_start_seconds.", "required": true, "type": "integer" }, "vocal_start_seconds": { "description": "Start time (seconds) of the source vocal segment.", "required": true, "type": "integer" }, "voice_url": { "description": "Source voice recording URL.", "required": true, "type": "string" } } ``` ## Create acceptance HTTP 202 - POST /api/v1/suno/voice_to_validation_phrase ### Response schema ```json { "properties": { "billing": { "properties": { "refund": { "oneOf": [ { "properties": { "refunded_at": { "type": "string" } }, "required": [ "refunded_at" ], "type": "object", "unevaluatedProperties": false }, { "enum": [ null ] } ] }, "reservation": { "oneOf": [ { "properties": { "amount_cents": { "type": "integer" } }, "required": [ "amount_cents" ], "type": "object", "unevaluatedProperties": false }, { "enum": [ null ] } ] }, "settlement": { "oneOf": [ { "properties": { "amount_micro_cents": { "type": "integer" }, "charged_amount_cents": { "type": "integer" } }, "required": [ "charged_amount_cents", "amount_micro_cents" ], "type": "object", "unevaluatedProperties": false }, { "enum": [ null ] } ] } }, "required": [ "reservation", "settlement", "refund" ], "type": "object", "unevaluatedProperties": false }, "id": { "type": "string" }, "status": { "enum": [ "processing" ], "type": "string" }, "task_replayed": { "type": "boolean" } }, "required": [ "id", "status", "billing" ], "type": "object", "unevaluatedProperties": false } ``` ### Response example ```json { "billing": { "refund": null, "reservation": null, "settlement": null }, "id": "tsk_reference_demo", "status": "processing" } ``` ## Polling processing HTTP 200 - GET /api/v1/suno/voice_to_validation_phrase/:id ### Response schema ```json { "properties": { "billing": { "properties": { "refund": { "oneOf": [ { "properties": { "refunded_at": { "type": "string" } }, "required": [ "refunded_at" ], "type": "object", "unevaluatedProperties": false }, { "enum": [ null ] } ] }, "reservation": { "oneOf": [ { "properties": { "amount_cents": { "type": "integer" } }, "required": [ "amount_cents" ], "type": "object", "unevaluatedProperties": false }, { "enum": [ null ] } ] }, "settlement": { "oneOf": [ { "properties": { "amount_micro_cents": { "type": "integer" }, "charged_amount_cents": { "type": "integer" } }, "required": [ "charged_amount_cents", "amount_micro_cents" ], "type": "object", "unevaluatedProperties": false }, { "enum": [ null ] } ] } }, "required": [ "reservation", "settlement", "refund" ], "type": "object", "unevaluatedProperties": false }, "id": { "type": "string" }, "provider_status": { "enum": [ "wait_processing", "processing_validate" ], "type": "string" }, "status": { "enum": [ "processing" ], "type": "string" }, "validation_phrase": { "type": "string" } }, "required": [ "id", "status", "provider_status", "billing" ], "type": "object", "unevaluatedProperties": false } ``` ### Response example ```json { "billing": { "refund": null, "reservation": null, "settlement": null }, "id": "tsk_reference_demo", "provider_status": "processing_validate", "status": "processing" } ``` ## Polling completed HTTP 200 - GET /api/v1/suno/voice_to_validation_phrase/:id ### Response schema ```json { "properties": { "billing": { "properties": { "refund": { "oneOf": [ { "properties": { "refunded_at": { "type": "string" } }, "required": [ "refunded_at" ], "type": "object", "unevaluatedProperties": false }, { "enum": [ null ] } ] }, "reservation": { "oneOf": [ { "properties": { "amount_cents": { "type": "integer" } }, "required": [ "amount_cents" ], "type": "object", "unevaluatedProperties": false }, { "enum": [ null ] } ] }, "settlement": { "oneOf": [ { "properties": { "amount_micro_cents": { "type": "integer" }, "charged_amount_cents": { "type": "integer" } }, "required": [ "charged_amount_cents", "amount_micro_cents" ], "type": "object", "unevaluatedProperties": false }, { "enum": [ null ] } ] } }, "required": [ "reservation", "settlement", "refund" ], "type": "object", "unevaluatedProperties": false }, "id": { "type": "string" }, "provider_status": { "type": "string" }, "status": { "enum": [ "completed" ], "type": "string" }, "validation_phrase": { "type": "string" } }, "required": [ "id", "status", "provider_status", "validation_phrase", "billing" ], "type": "object", "unevaluatedProperties": false } ``` ### Response example ```json { "billing": { "refund": null, "reservation": null, "settlement": null }, "id": "tsk_reference_demo", "provider_status": "wait_validating", "status": "completed", "validation_phrase": "Harmonies fill the air with joyful melodies tonight." } ``` ## Polling failed HTTP 200 - GET /api/v1/suno/voice_to_validation_phrase/:id ### Response schema ```json { "properties": { "billing": { "properties": { "refund": { "oneOf": [ { "properties": { "refunded_at": { "type": "string" } }, "required": [ "refunded_at" ], "type": "object", "unevaluatedProperties": false }, { "enum": [ null ] } ] }, "reservation": { "oneOf": [ { "properties": { "amount_cents": { "type": "integer" } }, "required": [ "amount_cents" ], "type": "object", "unevaluatedProperties": false }, { "enum": [ null ] } ] }, "settlement": { "oneOf": [ { "properties": { "amount_micro_cents": { "type": "integer" }, "charged_amount_cents": { "type": "integer" } }, "required": [ "charged_amount_cents", "amount_micro_cents" ], "type": "object", "unevaluatedProperties": false }, { "enum": [ null ] } ] } }, "required": [ "reservation", "settlement", "refund" ], "type": "object", "unevaluatedProperties": false }, "error": { "type": "string" }, "id": { "type": "string" }, "status": { "enum": [ "failed" ], "type": "string" } }, "required": [ "id", "status", "error", "billing" ], "type": "object", "unevaluatedProperties": false } ``` ### Response example ```json { "billing": { "refund": null, "reservation": null, "settlement": null }, "error": "Task processing failed.", "id": "tsk_reference_demo", "status": "failed" } ``` ## Customer callback: completed HTTP 200 - POST callback_url ### Response schema ```json { "properties": { "id": { "type": "string" }, "provider_status": { "type": "string" }, "status": { "enum": [ "completed" ], "type": "string" }, "validation_phrase": { "type": "string" } }, "required": [ "id", "status", "provider_status", "validation_phrase" ], "type": "object", "unevaluatedProperties": false } ``` ### Response example ```json { "id": "tsk_reference_demo", "provider_status": "wait_validating", "status": "completed", "validation_phrase": "Harmonies fill the air with joyful melodies tonight." } ``` ## Customer callback: failed HTTP 200 - POST callback_url ### Response schema ```json { "properties": { "error": { "oneOf": [ { "type": "string" }, { "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object", "unevaluatedProperties": false } ] }, "id": { "type": "string" }, "status": { "enum": [ "failed" ], "type": "string" } }, "required": [ "id", "status", "error" ], "type": "object", "unevaluatedProperties": false } ``` ### Response example ```json { "error": { "code": "generation_failed", "message": "Task processing failed." }, "id": "tsk_reference_demo", "status": "failed" } ``` ## Errors HTTP 401 - POST /api/v1/suno/voice_to_validation_phrase This response has no body. ## Errors HTTP 401 - GET /api/v1/suno/voice_to_validation_phrase/:id This response has no body. ## Errors HTTP 400 - POST /api/v1/suno/voice_to_validation_phrase ### Response schema ```json { "properties": { "billing": { "properties": { "refund": { "oneOf": [ { "properties": { "refunded_at": { "type": "string" } }, "required": [ "refunded_at" ], "type": "object", "unevaluatedProperties": false }, { "enum": [ null ] } ] }, "reservation": { "oneOf": [ { "properties": { "amount_cents": { "type": "integer" } }, "required": [ "amount_cents" ], "type": "object", "unevaluatedProperties": false }, { "enum": [ null ] } ] }, "settlement": { "oneOf": [ { "properties": { "amount_micro_cents": { "type": "integer" }, "charged_amount_cents": { "type": "integer" } }, "required": [ "charged_amount_cents", "amount_micro_cents" ], "type": "object", "unevaluatedProperties": false }, { "enum": [ null ] } ] } }, "required": [ "reservation", "settlement", "refund" ], "type": "object", "unevaluatedProperties": false }, "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object", "unevaluatedProperties": false } }, "required": [ "error" ], "type": "object", "unevaluatedProperties": false } ``` ### Response example ```json { "error": { "code": "voice_url_is_required", "message": "voice_url is required" } } ``` ## Errors HTTP 402 - POST /api/v1/suno/voice_to_validation_phrase ### Response schema ```json { "properties": { "billing": { "properties": { "refund": { "oneOf": [ { "properties": { "refunded_at": { "type": "string" } }, "required": [ "refunded_at" ], "type": "object", "unevaluatedProperties": false }, { "enum": [ null ] } ] }, "reservation": { "oneOf": [ { "properties": { "amount_cents": { "type": "integer" } }, "required": [ "amount_cents" ], "type": "object", "unevaluatedProperties": false }, { "enum": [ null ] } ] }, "settlement": { "oneOf": [ { "properties": { "amount_micro_cents": { "type": "integer" }, "charged_amount_cents": { "type": "integer" } }, "required": [ "charged_amount_cents", "amount_micro_cents" ], "type": "object", "unevaluatedProperties": false }, { "enum": [ null ] } ] } }, "required": [ "reservation", "settlement", "refund" ], "type": "object", "unevaluatedProperties": false }, "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object", "unevaluatedProperties": false } }, "required": [ "error" ], "type": "object", "unevaluatedProperties": false } ``` ### Response example ```json { "error": { "code": "insufficient_balance", "message": "Insufficient balance" } } ``` ## Errors HTTP 403 - POST /api/v1/suno/voice_to_validation_phrase ### Response schema ```json { "properties": { "billing": { "properties": { "refund": { "oneOf": [ { "properties": { "refunded_at": { "type": "string" } }, "required": [ "refunded_at" ], "type": "object", "unevaluatedProperties": false }, { "enum": [ null ] } ] }, "reservation": { "oneOf": [ { "properties": { "amount_cents": { "type": "integer" } }, "required": [ "amount_cents" ], "type": "object", "unevaluatedProperties": false }, { "enum": [ null ] } ] }, "settlement": { "oneOf": [ { "properties": { "amount_micro_cents": { "type": "integer" }, "charged_amount_cents": { "type": "integer" } }, "required": [ "charged_amount_cents", "amount_micro_cents" ], "type": "object", "unevaluatedProperties": false }, { "enum": [ null ] } ] } }, "required": [ "reservation", "settlement", "refund" ], "type": "object", "unevaluatedProperties": false }, "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object", "unevaluatedProperties": false } }, "required": [ "error" ], "type": "object", "unevaluatedProperties": false } ``` ### Response example ```json { "error": { "code": "api_token_credit_limit_exceeded", "message": "API key credit limit exceeded" } } ``` ## Errors HTTP 409 - POST /api/v1/suno/voice_to_validation_phrase ### Response schema ```json { "properties": { "billing": { "properties": { "refund": { "oneOf": [ { "properties": { "refunded_at": { "type": "string" } }, "required": [ "refunded_at" ], "type": "object", "unevaluatedProperties": false }, { "enum": [ null ] } ] }, "reservation": { "oneOf": [ { "properties": { "amount_cents": { "type": "integer" } }, "required": [ "amount_cents" ], "type": "object", "unevaluatedProperties": false }, { "enum": [ null ] } ] }, "settlement": { "oneOf": [ { "properties": { "amount_micro_cents": { "type": "integer" }, "charged_amount_cents": { "type": "integer" } }, "required": [ "charged_amount_cents", "amount_micro_cents" ], "type": "object", "unevaluatedProperties": false }, { "enum": [ null ] } ] } }, "required": [ "reservation", "settlement", "refund" ], "type": "object", "unevaluatedProperties": false }, "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object", "unevaluatedProperties": false } }, "required": [ "error" ], "type": "object", "unevaluatedProperties": false } ``` ### Response example ```json { "error": { "code": "request_conflict", "message": "The request uses features that are not supported for the selected model" } } ``` ## Errors HTTP 429 - POST /api/v1/suno/voice_to_validation_phrase ### Response schema ```json { "properties": { "billing": { "properties": { "refund": { "oneOf": [ { "properties": { "refunded_at": { "type": "string" } }, "required": [ "refunded_at" ], "type": "object", "unevaluatedProperties": false }, { "enum": [ null ] } ] }, "reservation": { "oneOf": [ { "properties": { "amount_cents": { "type": "integer" } }, "required": [ "amount_cents" ], "type": "object", "unevaluatedProperties": false }, { "enum": [ null ] } ] }, "settlement": { "oneOf": [ { "properties": { "amount_micro_cents": { "type": "integer" }, "charged_amount_cents": { "type": "integer" } }, "required": [ "charged_amount_cents", "amount_micro_cents" ], "type": "object", "unevaluatedProperties": false }, { "enum": [ null ] } ] } }, "required": [ "reservation", "settlement", "refund" ], "type": "object", "unevaluatedProperties": false }, "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object", "unevaluatedProperties": false } }, "required": [ "error" ], "type": "object", "unevaluatedProperties": false } ``` ### Response example ```json { "error": { "code": "rate_limited", "message": "Rate limit reached. Please retry later." } } ``` ## Errors HTTP 503 - POST /api/v1/suno/voice_to_validation_phrase ### Response schema ```json { "properties": { "billing": { "properties": { "refund": { "oneOf": [ { "properties": { "refunded_at": { "type": "string" } }, "required": [ "refunded_at" ], "type": "object", "unevaluatedProperties": false }, { "enum": [ null ] } ] }, "reservation": { "oneOf": [ { "properties": { "amount_cents": { "type": "integer" } }, "required": [ "amount_cents" ], "type": "object", "unevaluatedProperties": false }, { "enum": [ null ] } ] }, "settlement": { "oneOf": [ { "properties": { "amount_micro_cents": { "type": "integer" }, "charged_amount_cents": { "type": "integer" } }, "required": [ "charged_amount_cents", "amount_micro_cents" ], "type": "object", "unevaluatedProperties": false }, { "enum": [ null ] } ] } }, "required": [ "reservation", "settlement", "refund" ], "type": "object", "unevaluatedProperties": false }, "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object", "unevaluatedProperties": false } }, "required": [ "error" ], "type": "object", "unevaluatedProperties": false } ``` ### Response example ```json { "error": { "code": "service_unavailable", "message": "Service under maintenance, please try again later" } } ``` ## Errors HTTP 504 - POST /api/v1/suno/voice_to_validation_phrase ### Response schema ```json { "properties": { "billing": { "properties": { "refund": { "oneOf": [ { "properties": { "refunded_at": { "type": "string" } }, "required": [ "refunded_at" ], "type": "object", "unevaluatedProperties": false }, { "enum": [ null ] } ] }, "reservation": { "oneOf": [ { "properties": { "amount_cents": { "type": "integer" } }, "required": [ "amount_cents" ], "type": "object", "unevaluatedProperties": false }, { "enum": [ null ] } ] }, "settlement": { "oneOf": [ { "properties": { "amount_micro_cents": { "type": "integer" }, "charged_amount_cents": { "type": "integer" } }, "required": [ "charged_amount_cents", "amount_micro_cents" ], "type": "object", "unevaluatedProperties": false }, { "enum": [ null ] } ] } }, "required": [ "reservation", "settlement", "refund" ], "type": "object", "unevaluatedProperties": false }, "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object", "unevaluatedProperties": false } }, "required": [ "error" ], "type": "object", "unevaluatedProperties": false } ``` ### Response example ```json { "billing": { "refund": null, "reservation": null, "settlement": null }, "error": { "code": "timeout_error", "message": "The request timed out" } } ``` ## Errors HTTP 404 - GET /api/v1/suno/voice_to_validation_phrase/:id ### Response schema ```json { "properties": { "billing": { "properties": { "refund": { "oneOf": [ { "properties": { "refunded_at": { "type": "string" } }, "required": [ "refunded_at" ], "type": "object", "unevaluatedProperties": false }, { "enum": [ null ] } ] }, "reservation": { "oneOf": [ { "properties": { "amount_cents": { "type": "integer" } }, "required": [ "amount_cents" ], "type": "object", "unevaluatedProperties": false }, { "enum": [ null ] } ] }, "settlement": { "oneOf": [ { "properties": { "amount_micro_cents": { "type": "integer" }, "charged_amount_cents": { "type": "integer" } }, "required": [ "charged_amount_cents", "amount_micro_cents" ], "type": "object", "unevaluatedProperties": false }, { "enum": [ null ] } ] } }, "required": [ "reservation", "settlement", "refund" ], "type": "object", "unevaluatedProperties": false }, "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object", "unevaluatedProperties": false } }, "required": [ "error" ], "type": "object", "unevaluatedProperties": false } ``` ### Response example ```json { "error": { "code": "not_found", "message": "Task with id 'tsk_reference_demo' not found" } } ``` ## Generated Code Samples Use cURL directly, or install an SDK for your language. Each sample submits the validated request shown in this reference. ### curl ```curl curl -X POST https://runapi.ai/api/v1/suno/voice_to_validation_phrase \ -H 'Authorization: Bearer YOUR_API_TOKEN' \ -H 'Content-Type: application/json' \ -d '{"voice_url":"https://file.runapi.ai/source-vocal.mp3","vocal_start_seconds":2,"vocal_end_seconds":12,"language":"en"}' ``` ### javascript #### Install ```bash npm install @runapi.ai/suno ``` ```javascript import { SunoClient } from "@runapi.ai/suno"; const client = new SunoClient({ apiKey: process.env.RUNAPI_API_KEY }); const task = await client.voiceToValidationPhrase.create({ "voice_url": "https://file.runapi.ai/source-vocal.mp3", "vocal_start_seconds": 2, "vocal_end_seconds": 12, "language": "en" }); ``` ### python #### Install ```bash pip install runapi-suno ``` ```python import os from runapi.suno import SunoClient client = SunoClient(api_key=os.environ["RUNAPI_API_KEY"]) task = client.voice_to_validation_phrase.create( voice_url="https://file.runapi.ai/source-vocal.mp3", vocal_start_seconds=2, vocal_end_seconds=12, language="en" ) ``` ### go #### Install ```bash go get github.com/runapi-ai/suno-sdk/go@latest ``` ```go package main import ( "context" "log" "os" "github.com/runapi-ai/core-sdk/go/option" suno "github.com/runapi-ai/suno-sdk/go/suno" ) func main() { client, err := suno.NewClient(option.WithAPIKey(os.Getenv("RUNAPI_API_KEY"))) if err != nil { log.Fatal(err) } task, err := client.VoiceToValidationPhrase.Create(context.Background(), suno.VoiceToValidationPhraseParams{ VoiceURL: "https://file.runapi.ai/source-vocal.mp3", VocalStartSeconds: 2, VocalEndSeconds: 12, Language: suno.ValidationPhraseLanguage("en"), }) if err != nil { log.Fatal(err) } _ = task } ``` ### ruby #### Install ```bash gem install runapi-suno ``` ```ruby require "runapi/suno" client = RunApi::Suno::Client.new(api_key: ENV.fetch("RUNAPI_API_KEY")) task = client.voice_to_validation_phrase.create( voice_url: "https://file.runapi.ai/source-vocal.mp3", vocal_start_seconds: 2, vocal_end_seconds: 12, language: "en" ) ``` ### java #### Install ```kotlin implementation("ai.runapi:runapi-suno") ``` ```java import ai.runapi.suno.SunoClient; import ai.runapi.suno.types.VoiceToValidationPhraseParams; import ai.runapi.core.polling.TaskCreateResponse; public final class Example { public static void main(String[] args) { SunoClient client = SunoClient.builder() .apiKey(System.getenv("RUNAPI_API_KEY")) .build(); TaskCreateResponse task = client.voiceToValidationPhrase().create( VoiceToValidationPhraseParams.builder() .voiceUrl("https://file.runapi.ai/source-vocal.mp3") .vocalStartSeconds(2) .vocalEndSeconds(12) .language("en") .build() ); } } ``` ### php #### Install ```bash composer require runapi-ai/suno ``` ```php voiceToValidationPhrase->create([ "voice_url" => "https://file.runapi.ai/source-vocal.mp3", "vocal_start_seconds" => 2, "vocal_end_seconds" => 12, "language" => "en" ]); ``` ## Related Guides - [Authentication](/docs/guides/authentication) - [Quickstart](/docs/guides/task-api/quickstart)